Merge pull request #3082 from beccyabraham/feature/update-contributor-docs

Update contributor docs for clarity

Author: raclim

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/).

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).