From f9bd6db12eecdd4af6174d21157eddc677c3424e Mon Sep 17 00:00:00 2001 From: Rebecca Abraham <33535365+beccyabraham@users.noreply.github.com> Date: Fri, 12 Apr 2024 14:47:22 -0600 Subject: [PATCH 1/5] Add links and clarify instructions in `installation.md` --- contributor_docs/installation.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/contributor_docs/installation.md b/contributor_docs/installation.md index 461812d37d..2cf9388e6d 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). @@ -94,9 +98,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/). From e90c53c5516573f8e1696046efc6720e14941d13 Mon Sep 17 00:00:00 2001 From: Rebecca Abraham <33535365+beccyabraham@users.noreply.github.com> Date: Fri, 12 Apr 2024 15:05:55 -0600 Subject: [PATCH 2/5] Create s3_configuration.md --- contributor_docs/s3_configuration.md | 66 ++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 contributor_docs/s3_configuration.md diff --git a/contributor_docs/s3_configuration.md b/contributor_docs/s3_configuration.md new file mode 100644 index 0000000000..61d7764191 --- /dev/null +++ b/contributor_docs/s3_configuration.md @@ -0,0 +1,66 @@ +# 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 From 2c7ceed78a5b7fb70bffaf197e383f66cf710127 Mon Sep 17 00:00:00 2001 From: Rebecca Abraham <33535365+beccyabraham@users.noreply.github.com> Date: Fri, 12 Apr 2024 15:10:35 -0600 Subject: [PATCH 3/5] Update s3 configuration section to refer to `s3_configuration.md` --- contributor_docs/installation.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/contributor_docs/installation.md b/contributor_docs/installation.md index 2cf9388e6d..492161185e 100644 --- a/contributor_docs/installation.md +++ b/contributor_docs/installation.md @@ -72,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 From f347a5d4c803d506ddd3fd84330571cc3aa5bfb1 Mon Sep 17 00:00:00 2001 From: Rebecca Abraham <33535365+beccyabraham@users.noreply.github.com> Date: Fri, 12 Apr 2024 15:33:15 -0600 Subject: [PATCH 4/5] Fix hyperlinks --- contributor_docs/s3_configuration.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/contributor_docs/s3_configuration.md b/contributor_docs/s3_configuration.md index 61d7764191..9b2ecb621a 100644 --- a/contributor_docs/s3_configuration.md +++ b/contributor_docs/s3_configuration.md @@ -1,5 +1,5 @@ # S3 Bucket Configuration -1. (Create an S3 bucket)[https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html], with any name +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. ``` [ @@ -61,6 +61,4 @@ 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 +For more information on using a custom domain, see [this documentation link](http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html#VirtualHostingCustomURLs). From 44faf23cf5d180aab63f301f4b704a317e3f0bf3 Mon Sep 17 00:00:00 2001 From: Rebecca Abraham <33535365+beccyabraham@users.noreply.github.com> Date: Fri, 12 Apr 2024 15:33:59 -0600 Subject: [PATCH 5/5] Fix hyperlink --- contributor_docs/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributor_docs/installation.md b/contributor_docs/installation.md index 492161185e..8678002fa4 100644 --- a/contributor_docs/installation.md +++ b/contributor_docs/installation.md @@ -85,7 +85,7 @@ 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)[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: +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`