Skip to content

Latest commit

 

History

History
100 lines (73 loc) · 7.05 KB

installation.md

File metadata and controls

100 lines (73 loc) · 7.05 KB
Raw

Development Installation

Follow these instructions to set up your development environment, which you need to do before you start contributing code to this project.

Manual Installation

Note: The installation steps assume you are using a Unix-like shell. If you are using Windows, you will need to use copy instead of cp.

  1. Install Node.js. The recommended way is to Node through nvm. You can also install node.js version 16.14.2 directly from the Node.js website.

  2. Fork the p5.js Web Editor repository into your own GitHub account.

  3. Clone your new fork of the repository from GitHub onto your local computer.

    $ git clone https://github.com/YOUR_USERNAME/p5.js-web-editor.git

  4. If you are using nvm, run $ nvm use 16.14.2 to set your Node version to 16.14.2

  5. Ensure your npm version is set to 8.5.0. If it isn't, run npm install -g npm@8.5.0 to install it.

  6. Navigate into the project folder and install all its necessary dependencies with npm.

    $ cd p5.js-web-editor
$ npm install

  7. Install MongoDB and make sure it is running

  8. $ cp .env.example .env

  9. (Optional) Update .env with necessary keys to enable certain app behaviors, i.e. add Github ID and Github Secret if you want to be able to log in with Github.

  10. Run $ npm run fetch-examples to download the example sketches into a user called 'p5'. Note that you need to configure your GitHub Credentials, which you can do by following the Github API Configuration section.

  11. Enable Prettier in your text editor by following this guide.

  12. $ npm start

  13. Navigate to http://localhost:8000 in your browser

  14. Install the React Developer Tools

  15. Open and close the Redux DevTools using ctrl+h, and move them with ctrl+w

Docker Installation

Note: The installation steps assume you are using a Unix-like shell. If you are using Windows, you will need to use copy instead of cp.

Using Docker, you can have a complete, consistent development environment without having to manually install dependencies such as Node, Mongo, etc. It also helps isolate these dependencies and their data from other projects that you may have on the same computer that use different/conflicting versions, etc.

Note that this takes up a significant amount of space on your machine. Make sure you have at least 5GB free.

  1. Install Docker for your operating system
  2. Install Docker Desktop
  3. Clone this repository and cd into it
  4. $ docker-compose -f docker-compose-development.yml build
    • Note: Depending on which version of Docker Compose you are using, the base command will be either docker-compose or docker compose. More information about it can be found in Docker Compose's documentation for their V1 to V2 transition.
  5. $ cp .env.example .env
  6. (Optional) Update .env with necessary keys to enable certain app behaviors, i.e. add Github ID and Github Secret if you want to be able to log in with Github.
  7. $ docker-compose -f docker-compose-development.yml run --rm app npm run fetch-examples - note that you need to configure your GitHub Credentials, which you can do by following the Github API Configuration section.
  8. Enable Prettier in your text editor by following this guide.

Now, anytime you wish to start the server with its dependencies, you can run:

  1. $ docker-compose -f docker-compose-development.yml up
  2. Navigate to http://localhost:8000 in your browser

To open a terminal/shell in the running Docker server (i.e. after docker-compose up has been run):

  1. $ docker-compose -f docker-compose-development.yml exec app bash -l

If you don't have the full server environment running, you can launch a one-off container instance (and have it automatically deleted after you're done using it):

  1. $ docker-compose -f docker-compose-development.yml run app --rm bash -l

S3 Bucket Configuration

See this configuration guide for information about how to configure your own S3 bucket. These instructions were adapted from this gist.

Note that this is optional unless you are working on the part of the application that allows a user to upload images, videos, etc.

GitHub API Configuration

In this application, GitHub credentials are used for:

  • Authentication with GitHub
  • Importing the p5.js examples to your local database
  • Rendering the 404 pages

If you are working on a part of the application that requires one of the above uses, then you will need to get GitHub API credentials.

When you go to the Developer settings in your GitHub account, you will see that you can create two types of Apps: GitHub Apps and OAuth Apps (differences between GitHub Apps and OAuth Apps). This project requires you to make an OAuth App. After clicking on "New OAuth App", you will need to fill in the following fields:

  • Application name: p5.js Web Editor - Local
  • Homepage URL: http://localhost:8000
  • Authorization Callback URL: http://localhost:8000/auth/github/callback

Once you've created a new OAuth app, update your .env:

GITHUB_ID={GITHUB_ID}
GITHUB_SECRET={GITHUB_SECRET}

If you would like to learn more about what you can do with the GitHub API, you can look at the API documentation.