diff --git a/contributor_docs/installation.md b/contributor_docs/installation.md index 461812d37d..8678002fa4 100644 --- a/contributor_docs/installation.md +++ b/contributor_docs/installation.md @@ -14,7 +14,7 @@ _Note_: The installation steps assume you are using a Unix-like shell. If you ar $ git clone https://github.com/YOUR_USERNAME/p5.js-web-editor.git ``` -4. If you are using nvm, run `$ nvm use` to set your Node version to 16.14.2 +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. @@ -27,12 +27,14 @@ _Note_: The installation steps assume you are using a Unix-like shell. If you ar * For Windows and Linux: [MongoDB Installation](https://docs.mongodb.com/manual/installation/) 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](#github-api-configuration) section. -11. Enable Prettier in your text editor by following [this guide](https://prettier.io/docs/en/editors.html). -12. `$ npm start` -13. Navigate to [http://localhost:8000](http://localhost:8000) in your browser -14. Install the [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en) -15. Open and close the Redux DevTools using `ctrl+h`, and move them with `ctrl+w` + * See the [GitHub API Configuration](#github-api-configuration) section for information on how to authenticate with Github. + * See the [S3 Bucket Configuration](#s3-bucket-configuration) section for information on how to set up an S3 bucket +11. 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](#github-api-configuration) section. +12. Enable Prettier in your text editor by following [this guide](https://prettier.io/docs/en/editors.html). +13. `$ npm start` +14. Navigate to [http://localhost:8000](http://localhost:8000) in your browser +15. Install the [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en) +16. Open and close the Redux DevTools using `ctrl+h`, and move them with `ctrl+w` ## Docker Installation @@ -50,6 +52,8 @@ Note that this takes up a significant amount of space on your machine. Make sure 4. `$ docker-compose -f docker-compose-development.yml build` 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. + * See the [GitHub API Configuration](#github-api-configuration) section for information on how to authenticate with Github. + * See the [S3 Bucket Configuration](#s3-bucket-configuration) section for information on how to set up an S3 bucket 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](#github-api-configuration) section. 8. Enable Prettier in your text editor by following [this guide](https://prettier.io/docs/en/editors.html). @@ -68,22 +72,9 @@ If you don't have the full server environment running, you can launch a one-off ## S3 Bucket Configuration -Note that this is optional unless you are working on the part of the application that allows a user to upload images, videos, etc. Please refer to the following [gist](https://gist.github.com/catarak/70c9301f0fd1ac2d6b58de03f61997e3) to set up an S3 bucket to be used with this project. +See [this configuration guide](./s3_configuration.md) for information about how to configure your own S3 bucket. These instructions were adapted from [this gist](https://gist.github.com/catarak/70c9301f0fd1ac2d6b58de03f61997e3). -If your S3 bucket is in the US East (N Virginia) region (us-east-1), you'll -need to set a custom URL base for it, because it does not follow the standard -naming pattern as the rest of the regions. Instead, add the following to your -environment/.env file, changing `BUCKET_NAME` to your bucket name. This is necessary because this override is currently treated as the full path to the bucket rather than as a proper base URL: -`S3_BUCKET_URL_BASE=https://s3.amazonaws.com/{BUCKET_NAME}/` - -If you've configured your S3 bucket and DNS records to use a custom domain -name, you can also set it using this variable. I.e.: - -`S3_BUCKET_URL_BASE=https://files.mydomain.com` - -For more information on using a custom domain, see this documentation link: - -http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html#VirtualHostingCustomURLs +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 @@ -94,9 +85,15 @@ In this application, GitHub credentials are used for: 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](https://docs.github.com/en/free-pro-team@latest/developers/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: +When you go to the [Developer settings](https://github.com/settings/developers) 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](https://docs.github.com/en/free-pro-team@latest/developers/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](https://developer.github.com/v3/). diff --git a/contributor_docs/s3_configuration.md b/contributor_docs/s3_configuration.md new file mode 100644 index 0000000000..9b2ecb621a --- /dev/null +++ b/contributor_docs/s3_configuration.md @@ -0,0 +1,64 @@ +# S3 Bucket Configuration +1. [Create an S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html), with any name +2. Navigate to the S3 bucket permissions and add the following CORS policy. This is for development only, as it allows CORS from any origin. +``` +[ + { + "AllowedHeaders": [ + "*" + ], + "AllowedMethods": [ + "GET", + "PUT", + "POST", + "DELETE", + "HEAD" + ], + "AllowedOrigins": [ + "*" + ], + "ExposeHeaders": [] + } +] +``` +3. In permissions, add the following bucket policy. Change "YOUR_BUCKET_NAME" to reflect name of the S3 bucket. +``` +{ + "Version": "2008-10-17", + "Id": "Policy1397632521960", + "Statement": [ + { + "Sid": "Stmt1397633323327", + "Effect": "Allow", + "Principal": { + "AWS": "*" + }, + "Action": "s3:GetObject", + "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME_HERE/*" + } + ] +} +``` +4. Uncheck "Block all public access" under "Block public access (bucket settings)". +5. Under "Object Ownership", check "ACLs enabled" and set "Object Ownership" to "Object writer" +6. Locate your AWS key and Secret Key. You can find this in the top AWS navigation under your name -> Security Credentials. +7. Update the following lines to your .env file: +``` +AWS_ACCESS_KEY={AWS_ACCESS_KEY} +AWS_REGION={S3_BUCKET_REGION} +AWS_SECRET_KEY={AWS_SECRET_KEY} +S3_BUCKET={S3_BUCKET_NAME} +``` + +If your S3 bucket is in the US East (N Virginia) region (us-east-1), you'll +need to set a custom URL base for it, because it does not follow the standard +naming pattern as the rest of the regions. Instead, add the following to your +environment/.env file, changing `BUCKET_NAME` to your bucket name. This is necessary because this override is currently treated as the full path to the bucket rather than as a proper base URL: +`S3_BUCKET_URL_BASE=https://s3.amazonaws.com/{BUCKET_NAME}/` + +If you've configured your S3 bucket and DNS records to use a custom domain +name, you can also set it using this variable. I.e.: + +`S3_BUCKET_URL_BASE=https://files.mydomain.com` + +For more information on using a custom domain, see [this documentation link](http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html#VirtualHostingCustomURLs).