Development documentation (#705)
* delete unused files, move webpack configs to their own directory * start of improved developer documentation, moving everything to developer_docs/ directory * documentation updates
This commit is contained in:
Cassie Tarakajian
GitHub
parent
7ac6dd0b39
commit
8495a59e36
|
|
@ -1,10 +1,5 @@
|
|||
API_URL=/api
|
||||
MONGO_URL=mongodb://localhost:27017/p5js-web-editor
|
||||
MONGO_HOSTNAME=localhost
|
||||
MONGO_PORT=27017
|
||||
MONGO_NAME=p5js-web-editor
|
||||
MONGO_ROOT_USERNAME=processing_user
|
||||
MONGO_ROOT_PASSWORD=<change-this-to-a-secure-password>
|
||||
PORT=8000
|
||||
SESSION_SECRET=whatever_you_want_this_to_be_it_only_matters_for_production
|
||||
AWS_ACCESS_KEY=<your-aws-access-key>
|
||||
|
|
|
|||
|
|
@ -1,2 +1,2 @@
|
|||
webpack.config.js
|
||||
webpack/*
|
||||
index.js
|
||||
|
|
@ -1,17 +1,12 @@
|
|||
# Contributing to the p5.js web editor
|
||||
# Contributing to the p5.js Web Editor
|
||||
|
||||
Hello! We welcome community contributions to the p5.js web editor. Contributing takes many forms and doesn't have to be **writing code**, it can be **documenting bugs**, **proposing new features**, and **updating documentation**. We would also like to Thank you for choosing to contribute p5.js web editor, any way possible. You are awesome! :blush:
|
||||
|
||||
This **web editor** for **p5.js**, a JavaScript library with the goal of making coding accessible to **artists**, **designers**, **educators**, and **beginners**, is an environment to make p5.js sketches without needing to download any software or do any configuration, which makes it a great place to start learning how to code and start learning p5.js.
|
||||
Hello! We welcome community contributions to the p5.js Web Editor. Contributing takes many forms and doesn't have to be **writing code**, it can be **report bugs**, **proposing new features**, **creating UI/UX designs**, and **updating documentation**.
|
||||
|
||||
Here are links to all the sections in this document:
|
||||
|
||||
<!-- If you change any of the headings in this document, remember to update the table of contents. -->
|
||||
|
||||
- [Code of Conduct](#code-of-conduct)
|
||||
- [Technologies Used](#technologies-used)
|
||||
- [Development Installation](#development-installation)
|
||||
- [New Design](#new-design)
|
||||
- [How Can I Contribute ?](#how-can-i-contribute?)
|
||||
- [First Timers](#first-timers)
|
||||
- [Want something more challenging](#want-something-more-challenging)
|
||||
|
|
@ -23,30 +18,6 @@ Here are links to all the sections in this document:
|
|||
|
||||
Please follow the guidelines mentioned at [CODE OF CONDUCT.md](https://github.com/processing/p5.js-web-editor/blob/master/CODE_OF_CONDUCT.md#p5js-code-of-conduct).
|
||||
|
||||
# Technologies Used
|
||||
|
||||
> **MERN stack - MongoDB, Express, React/Redux, and Node**.
|
||||
|
||||
- For a reference to the **file structure format** I am using, please look at the [Mern Starter](https://github.com/Hashnode/mern-starter).
|
||||
|
||||
- This project **does not use CSS Modules, but uses Sass**. [BEM guidelines and naming conventions](http://getbem.com/) are followed.
|
||||
|
||||
- For repeatitive and common styles, write OOSCSS (Object-Oriented SCSS) with placeholders and mixins. For organizing styles, follow the 7-1 Pattern for Sass.
|
||||
|
||||
- We're using [ES6](http://es6-features.org/) and transpiling to ES5 using [Babel](https://babeljs.io/).
|
||||
|
||||
- For reference to the JavaScript style guide, see the [Airbnb Style Guide](https://github.com/airbnb/javascript), [React ESLint Plugin](https://github.com/yannickcr/eslint-plugin-react).
|
||||
|
||||
- The ESLint configuration is based on a few popular React/Redux boilerplates. Open to suggestions on this. If in development, **you're getting annoyed with ESLint**, you can **remove** it from `webpack.config.dev.js` in the JavaScript loader, or disable any line from eslint by commenting at the end of the line `// eslint-disable-line`.
|
||||
|
||||
# Development Installation
|
||||
|
||||
To get started on a patch, first read the instruction from [README.md](https://github.com/processing/p5.js-web-editor#development-installation).
|
||||
|
||||
# New Design
|
||||
|
||||
Design proposed and theme changes are present at: [Zeplin](https://scene.zeplin.io/project/55f746c54a02e1e50e0632c3).
|
||||
|
||||
# How Can I Contribute?
|
||||
|
||||
### First Timers
|
||||
|
|
|
|||
|
|
@ -10,7 +10,8 @@ ENV NODE_ENV development
|
|||
COPY package.json package-lock.json ./
|
||||
RUN npm install
|
||||
RUN npm rebuild node-sass
|
||||
COPY .babelrc index.js nodemon.json webpack.config.babel.js webpack.config.dev.js webpack.config.prod.js webpack.config.server.js webpack.config.examples.js ./
|
||||
COPY .babelrc index.js nodemon.json ./
|
||||
COPY ./webpack ./webpack
|
||||
COPY client ./client
|
||||
COPY server ./server
|
||||
CMD ["npm", "start"]
|
||||
|
|
|
|||
|
|
@ -1,20 +0,0 @@
|
|||
FROM node:8.11.1
|
||||
|
||||
ENV APP_HOME=/opt/node/app \
|
||||
TERM=xterm
|
||||
|
||||
# Copy in the project files and set as working directory
|
||||
ADD . $APP_HOME
|
||||
WORKDIR $APP_HOME
|
||||
|
||||
# Install node modules
|
||||
RUN npm install
|
||||
|
||||
# Rebuild node-sass just to be safe
|
||||
RUN npm rebuild node-sass
|
||||
|
||||
# For development, mark the directory as a mount override point
|
||||
VOLUME $APP_HOME
|
||||
|
||||
# Expose default server port
|
||||
EXPOSE 8000
|
||||
130
README.md
130
README.md
|
|
@ -1,127 +1,23 @@
|
|||
# p5.js Web Editor
|
||||
# [p5.js Web Editor](https://editor.p5js.org)
|
||||
|
||||
This project is currently in development! It will be announced when there is a (public) beta release.
|
||||
The p5.js Web Editor is an in-browser code editor for creating [p5.js](https://p5js.org/) sketches. p5.js, which is a separate project, is a JavaScript library with the goal of making coding accessible for artists, designers, educators, and beginners, and the web editor shares this same spirit. It is designed with the benginner in mind—when using the web editor, you don't need to download or configure anything, you can simply open the website, and start writing code. You can also host their work online and share it with others.
|
||||
|
||||
## Development Installation
|
||||
The p5.js Web Editor is currently in active development, and looking for contributions of any type! Please check out the [contribution guide](https://github.com/processing/p5.js-web-editor/blob/master/.github/CONTRIBUTING.md) for more details.
|
||||
|
||||
1. Fork this repository.
|
||||
2. Clone the forked repository and cd into it
|
||||
3. `$ npm install`
|
||||
4. Install MongoDB and make sure it is running
|
||||
* For Mac OSX with [homebrew](http://brew.sh/): `brew install mongodb` then `brew services start mongodb`
|
||||
* For Windows and Linux: [MongoDB Installation](https://docs.mongodb.com/manual/installation/)
|
||||
5. `$ cp .env.example .env`
|
||||
6. (Optional) Update `.env` with necessary keys to enable certain app behavoirs, i.e. add Github ID and Github Secret if you want to be able to log in with Github.
|
||||
7. `$ npm run fetch-examples` - this downloads the example sketches into a user called 'p5'
|
||||
8. `$ npm start`
|
||||
9. Navigate to [http://localhost:8000](http://localhost:8000) in your browser
|
||||
10. Install the [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en)
|
||||
11. Open and close the Redux DevTools using `ctrl+h`, and move them with `ctrl+w`
|
||||
If you have found a bug in the p5.js Web Editor, you can file it under the ["issues" tab](https://github.com/processing/p5.js-web-editor/issues).
|
||||
|
||||
### Testing SSL on your local machine
|
||||
Please refer to [this gist](https://gist.github.com/andrewn/953ffd5cb17ac2634dc969fc7bdaff3f). This allows you to access the editor using both HTTP and HTTPS. Don't worry about this unless you need to make changes or test HTTPS behavior.
|
||||
## Issues
|
||||
|
||||
The automatic redirection to HTTPS is turned off by default in development. If you need to test this behavior, put `FORCE_TO_HTTPS=true` in your `.env` file.
|
||||
Please post bugs and feature requests in the correct repository:
|
||||
|
||||
## Development Installation using Docker
|
||||
* p5.js general and p5.dom: [https://github.com/processing/p5.js/issues](https://github.com/processing/p5.js/issues)
|
||||
* p5.accessibility: [https://github.com/processing/p5.accessibility/issues](https://github.com/processing/p5.accessibility/issues)
|
||||
* p5.sound: [https://github.com/processing/p5.js-sound/issues](https://github.com/processing/p5.js-sound/issues)
|
||||
* p5.js website: [https://github.com/processing/p5.js-website/issues](https://github.com/processing/p5.js-website/issues)
|
||||
|
||||
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.
|
||||
## Get Involved
|
||||
|
||||
Note that this takes up a significant amount of space on your machine. Make sure you have at least 5GB free.
|
||||
The p5.js Web Editor is a collaborative project created by many individuals, and you are invited to help. All types of involvement are welcome. You can start with the [p5.js community section](https://p5js.org/community), which also applies to this project.
|
||||
|
||||
1. Install Docker for your operating system
|
||||
* Mac: https://www.docker.com/docker-mac
|
||||
* Windows: https://www.docker.com/docker-windows
|
||||
2. Clone this repository and cd into it
|
||||
3. `$ docker-compose -f docker-compose-development.yml build`
|
||||
4. `$ docker-compose -f docker-compose-development.yml run --rm app npm run fetch-examples`
|
||||
Developers, check the [developer docs](https://github.com/processing/p5.js-web-editor/blob/master/developer_docs/) details about contributing code, bug fixes, and documentation.
|
||||
|
||||
Now, anytime you wish to start the server with its dependencies, you can run:
|
||||
|
||||
5. `$ docker-compose -f docker-compose-development.yml up`
|
||||
6. Navigate to [http://localhost:8000](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):
|
||||
|
||||
7. `$ 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):
|
||||
|
||||
8. `$ docker-compose -f docker-compose-development.yml run app --rm bash -l`
|
||||
|
||||
## Production Installation
|
||||
1. Clone this repository and `cd` into it
|
||||
2. `$ npm install`
|
||||
3. Install MongoDB and make sure it is running
|
||||
4. `$ cp .env.example .env`
|
||||
5. (NOT Optional) edit `.env` and fill in all necessart values.
|
||||
6. `$ npm run fetch-examples` - this downloads the example sketches into a user called 'p5'
|
||||
7. `$ npm run build`
|
||||
8. `$ npm run start:prod`
|
||||
|
||||
### For Production Setup with PM2
|
||||
1. `$ npm install -g pm2`
|
||||
2. `$ pm2 start ecosystem.json`
|
||||
|
||||
## S3 Bucket Configuration
|
||||
|
||||
Please refer to the folllowing [gist](https://gist.github.com/catarak/70c9301f0fd1ac2d6b58de03f61997e3) to set up an S3 bucket to be used with this project.
|
||||
|
||||
|
||||
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:
|
||||
|
||||
`S3_BUCKET_URL_BASE=https://s3.amazonaws.com`
|
||||
|
||||
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
|
||||
|
||||
## Accessibility Guidelines
|
||||
|
||||
Here is guide on [how to use the accessible editor](https://gist.github.com/MathuraMG/e86666b7b41fbc8c078bad9aff3f666d) and here is an overview of the [p5-accessibility.js](https://github.com/processing/p5.accessibility) library that makes p5.js sketches accessible to screen readers.
|
||||
|
||||
The code for the p5.js web editor adheres to web accessibility standards. The following guidelines will help to ensure that accessibility continues to be a priority as development continues.
|
||||
|
||||
**Code Structure**
|
||||
|
||||
* Screen Readers are an assistive technology for vision loss which helps users to navigate a web page. They are able to prioritize content based on the semantic meaning of HTML tags. Therefore, it is important to use specific tags, such as `nav`, `ul`, `li`, `section`, and so on. `div` is the least screen reader friendly tag. For example, [here is the semantic meaning of the `body` tag](http://html5doctor.com/element-index/#body)
|
||||
* All buttons/links/windows need to be accessible by the keyboard ( By tabbing, pressing space etc.)
|
||||
* In cases where tags are not screen reader friendly, we can take advantage of [tabIndex](http://webaim.org/techniques/keyboard/tabindex). Using tabIndex ensures that all elements are accessible via keyboard. [code example](https://github.com/processing/p5.js-web-editor/blob/master/client/modules/IDE/components/Editor.jsx#L249)
|
||||
* When opening a new window or pop up window, ensure the keyboard focus also moves to the new window. [code example](https://github.com/processing/p5.js-web-editor/blob/master/client/modules/IDE/components/NewFileForm.jsx#L16)
|
||||
|
||||
**Labeling**
|
||||
|
||||
* When creating button icons, images, or something without text (this does not include an HTML5 `<button>`), use [aria-labels](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute). [code example](https://github.com/processing/p5.js-web-editor/blob/master/client/modules/IDE/components/Toolbar.jsx#L67)
|
||||
* All `<table>`s need to have a `summary` attribute. This will ensure user is given context to what the table is. [code example](https://github.com/processing/p5.js-web-editor/blob/master/client/modules/IDE/components/SketchList.jsx#L39)
|
||||
* `ul`s and `nav`s menus need to include a title. [code example](https://github.com/processing/p5.js-web-editor/blob/master/client/components/Nav.jsx#L7)
|
||||
|
||||
For more information on accessibility see the [teach access tutorial](https://teachaccess.github.io/tutorial/)
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](https://github.com/processing/p5.js-web-editor/blob/master/contributing.md).
|
||||
|
||||
## Tooling and Style Overview
|
||||
|
||||
The p5.js Web Editor is built on a MERN stack - MongoDB, Express, React/Redux, and Node. For a reference to the file structure format I am using, please look at the [Mern Starter](https://github.com/Hashnode/mern-starter) and [this comment](https://github.com/Hashnode/mern-starter/issues/90#issuecomment-221553573).
|
||||
|
||||
This project uses an in-development [p5-accessibility.js library](https://github.com/processing/p5.accessibility) for accessibility.
|
||||
|
||||
This project does not use CSS Modules, but uses Sass. I like to follow [BEM rules](http://getbem.com/) for CSS naming conventions, write OOSCSS with placeholders and mixins, and follow the [7-1 Pattern](https://sass-guidelin.es/#the-7-1-pattern) for Sass.
|
||||
|
||||
I'm using [ES6](http://es6-features.org/) and transpiling to ES5 using [Babel](https://babeljs.io/). For reference to the JavaScript style guide, see the [Airbnb Style Guide](https://github.com/airbnb/javascript), [React ESLint Plugin](https://github.com/yannickcr/eslint-plugin-react).
|
||||
|
||||
The ESLint configuration is based on a few popular React/Redux boilerplates. Open to suggestions on this. If in development, you're getting annoyed with ESLint, you can remove it from `webpack.config.dev.js` in the JavaScript loader, or disable any line from eslint by commenting at the end of the line `// eslint-disable-line`.
|
||||
|
||||
## AWS information
|
||||
This project is currently hosted on an EC2 instance and uses S3 for media hosting.
|
||||
|
||||
Backups on the MongoDB are also hosted on an S3 bucket, based on the following [gist](https://gist.github.com/eladnava/96bd9771cd2e01fb4427230563991c8d). The backup script runs nightly via a cronjob at 8AM UTC/3AM EST/12AM PST. Backups are deleted after 30 days.
|
||||
|
|
|
|||
57
backup.sh
57
backup.sh
|
|
@ -1,57 +0,0 @@
|
|||
#!/bin/sh
|
||||
|
||||
# Make sure to:
|
||||
# 1) Name this file `backup.sh` and place it in /home/ec2-user (or symlink it)
|
||||
# 2) Run sudo apt-get install awscli to install the AWSCLI
|
||||
# 3) Run aws configure (enter s3-authorized IAM user and specify region)
|
||||
# 4) Fill in DB host + name
|
||||
# 5) Create S3 bucket for the backups and fill it in below (set a lifecycle rule to expire files older than X days in the bucket)
|
||||
# 6) Run chmod +x backup.sh
|
||||
# 7) Test it out via ./backup.sh
|
||||
# 8) Set up a daily backup at 8AM UTC via `crontab -e`:
|
||||
# 0 8 * * * /home/ec2-user/backup.sh > /home/ec2-user/backup.log
|
||||
|
||||
# DB host (secondary preferred as to avoid impacting primary performance)
|
||||
HOST=localhost:27017
|
||||
|
||||
# DB name
|
||||
DBNAME=p5js-web-editor
|
||||
|
||||
# S3 bucket name
|
||||
BUCKET=p5js-web-editor-backup
|
||||
|
||||
# Linux user account
|
||||
USER=ec2-user
|
||||
|
||||
# Current time
|
||||
TIME=`/bin/date +%d-%m-%Y-%T`
|
||||
|
||||
# Backup directory
|
||||
DEST=/home/$USER/tmp
|
||||
|
||||
# Tar file of backup directory
|
||||
TAR=$DEST/../$TIME.tar
|
||||
|
||||
# Create backup dir (-p to avoid warning if already exists)
|
||||
/bin/mkdir -p $DEST
|
||||
|
||||
# Log
|
||||
echo "Backing up $HOST/$DBNAME to s3://$BUCKET/ on $TIME";
|
||||
|
||||
# Dump from mongodb host into backup directory
|
||||
/usr/bin/mongodump -h $HOST -d $DBNAME -o $DEST
|
||||
|
||||
# Create tar of backup directory
|
||||
/bin/tar cvf $TAR -C $DEST .
|
||||
|
||||
# Upload tar to s3
|
||||
/usr/bin/aws s3 cp $TAR s3://$BUCKET/
|
||||
|
||||
# Remove tar file locally
|
||||
/bin/rm -f $TAR
|
||||
|
||||
# Remove backup directory
|
||||
/bin/rm -rf $DEST
|
||||
|
||||
# All done
|
||||
echo "Backup available at https://s3.amazonaws.com/$BUCKET/$TIME.tar"
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
This folder contains documents intended for developers of the p5.js Web Editor.
|
||||
|
||||
## List of Documents
|
||||
* [Installation](https://github.com/processing/p5.js-web-editor/blob/master/developer_docs/installation.md) - A guide for setting up your development environment
|
||||
* [Preparing a pull-request](https://github.com/processing/p5.js/blob/master/developer_docs/preparing_a_pull_request.md) - Instructions for how to make a pull-request
|
||||
* [Accessibility Guidelines](https://github.com/processing/p5.js-web-editor/blob/master/developer_docs/accessibility.md) - Guidelines for writing code to create an accessible application
|
||||
* [Deployment](https://github.com/processing/p5.js-web-editor/blob/master/developer_docs/deployment.md) - A guide to production deployment, and all platforms that are being used.
|
||||
|
||||
## Documents to Create
|
||||
* Design Principles - reference [p5.js design principles](https://github.com/processing/p5.js/edit/master/developer_docs/design_principles.md)
|
||||
* Issue Labels - reference [p5.js issue labels](https://github.com/processing/p5.js/blob/master/developer_docs/issue_labels.md)
|
||||
* File Structure - An explanation of the file structure of this application.
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
## Accessibility Guidelines
|
||||
|
||||
Here is guide on [how to use the accessible editor](https://gist.github.com/MathuraMG/e86666b7b41fbc8c078bad9aff3f666d) and here is an overview of the [p5-accessibility.js](https://github.com/processing/p5.accessibility) library that makes p5.js sketches accessible to screen readers.
|
||||
|
||||
The code for the p5.js web editor adheres to web accessibility standards. The following guidelines will help to ensure that accessibility continues to be a priority as development continues.
|
||||
|
||||
**Code Structure**
|
||||
|
||||
* Screen Readers are an assistive technology for vision loss which helps users to navigate a web page. They are able to prioritize content based on the semantic meaning of HTML tags. Therefore, it is important to use specific tags, such as `nav`, `ul`, `li`, `section`, and so on. `div` is the least screen reader friendly tag. For example, [here is the semantic meaning of the `body` tag](http://html5doctor.com/element-index/#body)
|
||||
* All buttons/links/windows need to be accessible by the keyboard ( By tabbing, pressing space etc.)
|
||||
* In cases where tags are not screen reader friendly, we can take advantage of [tabIndex](http://webaim.org/techniques/keyboard/tabindex). Using tabIndex ensures that all elements are accessible via keyboard. [code example](https://github.com/processing/p5.js-web-editor/blob/master/client/modules/IDE/components/Editor.jsx#L249)
|
||||
* When opening a new window or pop up window, ensure the keyboard focus also moves to the new window. [code example](https://github.com/processing/p5.js-web-editor/blob/master/client/modules/IDE/components/NewFileForm.jsx#L16)
|
||||
|
||||
**Labeling**
|
||||
|
||||
* When creating button icons, images, or something without text (this does not include an HTML5 `<button>`), use [aria-labels](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute). [code example](https://github.com/processing/p5.js-web-editor/blob/master/client/modules/IDE/components/Toolbar.jsx#L67)
|
||||
* All `<table>`s need to have a `summary` attribute. This will ensure user is given context to what the table is. [code example](https://github.com/processing/p5.js-web-editor/blob/master/client/modules/IDE/components/SketchList.jsx#L39)
|
||||
* `ul`s and `nav`s menus need to include a title. [code example](https://github.com/processing/p5.js-web-editor/blob/master/client/components/Nav.jsx#L7)
|
||||
|
||||
For more information on accessibility see the [teach access tutorial](https://teachaccess.github.io/tutorial/)
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
# Deployment
|
||||
|
||||
WIP.
|
||||
* Production Setup/Installation
|
||||
* Travis
|
||||
* Docker Hub
|
||||
* Kubernetes
|
||||
* S3
|
||||
* Mailgun
|
||||
* Cloudflare
|
||||
* DNS/Dreamhost
|
||||
* mLab
|
||||
|
||||
## Production Installation
|
||||
1. Clone this repository and `cd` into it
|
||||
2. `$ npm install`
|
||||
3. Install MongoDB and make sure it is running
|
||||
4. `$ cp .env.example .env`
|
||||
5. (NOT Optional) edit `.env` and fill in all necessart values.
|
||||
6. `$ npm run fetch-examples` - this downloads the example sketches into a user called 'p5'
|
||||
7. `$ npm run build`
|
||||
8. `$ npm run start:prod`
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
# Development
|
||||
|
||||
A guide for adding code to this project.
|
||||
|
||||
## Installation
|
||||
Follow the [installation guide](https://github.com/processing/p5.js-web-editor/blob/master/developer_docs/installation.md).
|
||||
|
||||
## Design
|
||||
Design proposed and theme changes are present at: [Zeplin](https://scene.zeplin.io/project/55f746c54a02e1e50e0632c3).
|
||||
|
||||
# Technologies Used
|
||||
|
||||
**MERN stack** - MongoDB, Express, React/Redux, and Node.
|
||||
|
||||
- For a reference to the **file structure format** this project is using, please look at the [Mern Starter](https://github.com/Hashnode/mern-starter).
|
||||
|
||||
- This project does not use CSS Modules, styled-components, or other CSS-in-JS libraries, but uses Sass. [BEM guidelines and naming conventions](http://getbem.com/) are followed.
|
||||
|
||||
- For common and reusable styles, write OOSCSS (Object-Oriented SCSS) with placeholders and mixins. For organizing styles, follow the [7-1 Pattern](https://sass-guidelin.es/#the-7-1-pattern) for Sass.
|
||||
|
||||
- We're using [ES6](http://es6-features.org/) and transpiling to ES5 using [Babel](https://babeljs.io/).
|
||||
|
||||
- For reference to the JavaScript style guide, see the [Airbnb Style Guide](https://github.com/airbnb/javascript), [React ESLint Plugin](https://github.com/yannickcr/eslint-plugin-react).
|
||||
|
||||
- The ESLint configuration is based on a few popular React/Redux boilerplates. Open to suggestions on this. If in development, you're getting annoyed with ESLint, you can temporarily remove the `eslint-loader` it from `webpack/config.dev.js` in the JavaScript loader, or disable any line from eslint by commenting at the end of the line `// eslint-disable-line`.
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
# 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
|
||||
|
||||
1. Install [node.js](http://nodejs.org/), which also automatically installs the [npm](https://www.npmjs.org) package manager.
|
||||
2. [Fork](https://help.github.com/articles/fork-a-repo) the [p5.js Web Editor repository](https://github.com/processing/p5.js-web-editor) into your own GitHub account.
|
||||
3. [Clone](https://help.github.com/articles/cloning-a-repository/) 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. Navigate into the project folder and install all its necessary dependencies with npm.
|
||||
|
||||
```
|
||||
$ cd p5.js-web-editor
|
||||
$ npm install
|
||||
```
|
||||
5. Install MongoDB and make sure it is running
|
||||
* For Mac OSX with [homebrew](http://brew.sh/): `brew install mongodb` then `brew services start mongodb`
|
||||
* For Windows and Linux: [MongoDB Installation](https://docs.mongodb.com/manual/installation/)
|
||||
6. `$ cp .env.example .env`
|
||||
7. (Optional) Update `.env` with necessary keys to enable certain app behavoirs, i.e. add Github ID and Github Secret if you want to be able to log in with Github.
|
||||
8. `$ npm run fetch-examples` - this downloads the example sketches into a user called 'p5'
|
||||
9. `$ npm start`
|
||||
10. Navigate to [http://localhost:8000](http://localhost:8000) in your browser
|
||||
11. Install the [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en)
|
||||
12. Open and close the Redux DevTools using `ctrl+h`, and move them with `ctrl+w`
|
||||
|
||||
## Docker Installation
|
||||
|
||||
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
|
||||
* Mac: https://www.docker.com/docker-mac
|
||||
* Windows: https://www.docker.com/docker-windows
|
||||
2. Clone this repository and cd into it
|
||||
3. `$ docker-compose -f docker-compose-development.yml build`
|
||||
4. `$ cp .env.example .env`
|
||||
5. (Optional) Update `.env` with necessary keys to enable certain app behavoirs, i.e. add Github ID and Github Secret if you want to be able to log in with Github.
|
||||
6. `$ docker-compose -f docker-compose-development.yml run --rm app npm run fetch-examples`
|
||||
|
||||
Now, anytime you wish to start the server with its dependencies, you can run:
|
||||
|
||||
7. `$ docker-compose -f docker-compose-development.yml up`
|
||||
8. Navigate to [http://localhost:8000](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):
|
||||
|
||||
9. `$ 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):
|
||||
|
||||
10. `$ docker-compose -f docker-compose-development.yml run app --rm bash -l`
|
||||
|
||||
## 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 folllowing [gist](https://gist.github.com/catarak/70c9301f0fd1ac2d6b58de03f61997e3) to set up an S3 bucket to be used with this project.
|
||||
|
||||
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:
|
||||
|
||||
`S3_BUCKET_URL_BASE=https://s3.amazonaws.com`
|
||||
|
||||
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
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
# Preparing a pull request
|
||||
|
||||
Copied from the [p5.js repository](https://github.com/processing/p5.js).
|
||||
|
||||
Pull-requests are easier when your code is up to date! You can use git rebase to update your code to incorporate changes from other contributors. Here's how.
|
||||
|
||||
## Save and Update
|
||||
|
||||
### Save everything you have!
|
||||
git status
|
||||
git add -u
|
||||
git commit
|
||||
|
||||
|
||||
### Find out about changes
|
||||
Make sure you're tracking upstream p5.js repository.
|
||||
|
||||
git remote show upstream
|
||||
|
||||
If you see an error, you'll need to start tracking the main p5.js repo as an "upstream" remote repository. You'll only need to do this once! But, no harm is done if you run it a second time.
|
||||
|
||||
git remote add upstream https://github.com/processing/p5.js
|
||||
|
||||
Then ask git about the latest changes.
|
||||
|
||||
git fetch upstream
|
||||
|
||||
### Just in case: make a copy of your changes in a new branch
|
||||
git branch your-branch-name-backup
|
||||
|
||||
### Apply changes from master branch, adds your changes *after*
|
||||
git rebase upstream/master
|
||||
|
||||
## CONFLICTS
|
||||
You will probably have some conflicts!
|
||||
If it’s just lib/p5.js and lib/p5.min.js, it’s easy to fix. just build the project again with grunt.
|
||||
|
||||
grunt
|
||||
git add -u
|
||||
git rebase --continue
|
||||
|
||||
If you have conflicts in other files & you're not sure how to resolve them... ask for help! Lauren, David, Kevin, and Kate are familiar with recent changes and can help you figure out what's new.
|
||||
|
||||
## And finally, for great glory
|
||||
git push origin
|
||||
|
||||
Here's a good reference on rebasing, in case you're intensely curious about the technical details. https://www.atlassian.com/git/tutorials/merging-vs-rebasing
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
version: '3.4'
|
||||
services:
|
||||
mongo:
|
||||
image: mongo:3.4.7
|
||||
image: mongo:3.6
|
||||
volumes:
|
||||
- dbdata:/data/db
|
||||
app:
|
||||
|
|
|
|||
|
|
@ -1,35 +1,23 @@
|
|||
version: '3.4'
|
||||
services:
|
||||
mongo:
|
||||
image: mongo:3.4
|
||||
image: mongo:3.6
|
||||
volumes:
|
||||
- dbdata:/data/db
|
||||
- "$PWD/mongo/:/docker-entrypoint-initdb.d/"
|
||||
expose:
|
||||
- "27017"
|
||||
ports:
|
||||
- '27017:27017'
|
||||
# restart: always
|
||||
# env_file:
|
||||
# - "$PWD/.env"
|
||||
environment:
|
||||
- MONGO_INITDB_ROOT_USERNAME
|
||||
- MONGO_INITDB_ROOT_PASSWORD
|
||||
- MONGO_INITDB_DATABASE
|
||||
- MONGO_RW_USERNAME
|
||||
- MONGO_RW_PASSWORD
|
||||
app:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile
|
||||
target: production
|
||||
# uncomment the following line to pull the image from docker hub
|
||||
# image: index.docker.io/catarak/p5.js-web-editor:latest
|
||||
# uncomment the following lines if you don't want export all of the variables
|
||||
# defined in your .env file for testing
|
||||
# env_file:
|
||||
# - "$PWD/.env"
|
||||
environment:
|
||||
- API_URL
|
||||
- MONGO_URL
|
||||
- MONGO_NAME
|
||||
- PORT
|
||||
- SESSION_SECRET
|
||||
- AWS_ACCESS_KEY
|
||||
|
|
@ -50,14 +38,10 @@ services:
|
|||
- GOOGLE_SECRET
|
||||
- EXAMPLE_USER_EMAIL
|
||||
- EXAMPLE_USER_PASSWORD
|
||||
- MONGO_INITDB_ROOT_USERNAME
|
||||
- MONGO_INITDB_ROOT_PASSWORD
|
||||
- MONGO_INITDB_DATABASE
|
||||
- MONGO_RW_USERNAME
|
||||
- MONGO_RW_PASSWORD
|
||||
- MONGO_HOSTNAME
|
||||
- MONGO_PORT
|
||||
- FORCE_TO_HTTPS
|
||||
# you can either set this in your .env or as an environment variables
|
||||
# or here YOU CHOOSE
|
||||
# - MONGO_URL=mongodb://mongo:27017/p5js-web-editor
|
||||
volumes:
|
||||
- .:/opt/node/app
|
||||
- /opt/node/app/node_modules
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
{
|
||||
"name": "p5js-web-editor",
|
||||
"script": "index.js",
|
||||
"env": {
|
||||
"NODE_ENV": "production"
|
||||
},
|
||||
"instances" : "max",
|
||||
"exec_mode" : "cluster"
|
||||
}
|
||||
2
index.js
2
index.js
|
|
@ -9,7 +9,7 @@ if (process.env.NODE_ENV === 'production') {
|
|||
[
|
||||
"babel-plugin-webpack-loaders",
|
||||
{
|
||||
"config": "./webpack.config.babel.js",
|
||||
"config": "./webpack/config.babel.js",
|
||||
"verbose": false
|
||||
}
|
||||
]
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
mongo $MONGO_INITDB_DATABASE -u $MONGO_INITDB_ROOT_USERNAME -p $MONGO_INITDB_ROOT_PASSWORD --authenticationDatabase admin --eval "db.createUser({ user: '$MONGO_RW_USERNAME', pwd: '$MONGO_RW_PASSWORD', roles: [ { role: 'readWrite', db: '$MONGO_INITDB_DATABASE' }, { role: 'readWrite', db: 'sessions' }] })"
|
||||
|
|
@ -9,15 +9,14 @@
|
|||
"lint": "eslint client server --ext .jsx --ext .js",
|
||||
"lint-fix": "eslint client server --ext .jsx --ext .js --fix",
|
||||
"build": "npm run build:client && npm run build:server && npm run build:examples",
|
||||
"build:client": "cross-env NODE_ENV=production webpack --config webpack.config.prod.js",
|
||||
"build:server": "cross-env NODE_ENV=production webpack --config webpack.config.server.js",
|
||||
"build:examples": "cross-env NODE_ENV=production webpack --config webpack.config.examples.js",
|
||||
"build:client": "cross-env NODE_ENV=production webpack --config webpack/config.prod.js",
|
||||
"build:server": "cross-env NODE_ENV=production webpack --config webpack/config.server.js",
|
||||
"build:examples": "cross-env NODE_ENV=production webpack --config webpack/config.examples.js",
|
||||
"test": "npm run lint",
|
||||
"fetch-examples": "cross-env NODE_ENV=development node ./server/scripts/fetch-examples.js",
|
||||
"fetch-examples-gg": "cross-env NODE_ENV=development node ./server/scripts/fetch-examples-gg.js",
|
||||
"fetch-examples:prod": "cross-env NODE_ENV=production node ./dist/fetch-examples.bundle.js",
|
||||
"fetch-examples-gg:prod": "cross-env NODE_ENV=production node ./dist/fetch-examples.bundle.js",
|
||||
"ssl-proxy": "local-ssl-proxy --source 443 --target 80 &"
|
||||
"fetch-examples-gg:prod": "cross-env NODE_ENV=production node ./dist/fetch-examples-gg.bundle.js"
|
||||
},
|
||||
"main": "index.js",
|
||||
"author": "Cassie Tarakajian",
|
||||
|
|
|
|||
|
|
@ -66,22 +66,8 @@ canvas {
|
|||
|
||||
const headers = { 'User-Agent': 'p5js-web-editor/0.0.1' };
|
||||
|
||||
let mongoConnectionString;
|
||||
if (process.env.NODE_ENV === 'production' && process.env.MONGO_RW_USERNAME && process.env.MONGO_RW_PASSWORD) {
|
||||
const {
|
||||
MONGO_RW_USERNAME,
|
||||
MONGO_RW_PASSWORD,
|
||||
MONGO_HOSTNAME,
|
||||
MONGO_PORT,
|
||||
MONGO_NAME
|
||||
} = process.env;
|
||||
const muo = new URL(`mongodb://${MONGO_HOSTNAME}:${MONGO_PORT}/${MONGO_NAME}`);
|
||||
muo.username = MONGO_RW_USERNAME;
|
||||
muo.password = MONGO_RW_PASSWORD;
|
||||
mongoConnectionString = `${muo.href}`;
|
||||
} else {
|
||||
mongoConnectionString = process.env.MONGO_URL;
|
||||
}
|
||||
const mongoConnectionString = process.env.MONGO_URL;
|
||||
|
||||
mongoose.connect(mongoConnectionString, { useMongoClient: true });
|
||||
mongoose.connection.on('error', () => {
|
||||
console.error('MongoDB Connection Error. Please make sure that MongoDB is running.');
|
||||
|
|
|
|||
|
|
@ -36,22 +36,7 @@ const clientSecret = process.env.GITHUB_SECRET;
|
|||
|
||||
const headers = { 'User-Agent': 'p5js-web-editor/0.0.1' };
|
||||
|
||||
let mongoConnectionString;
|
||||
if (process.env.NODE_ENV === 'production' && process.env.MONGO_RW_USERNAME && process.env.MONGO_RW_PASSWORD) {
|
||||
const {
|
||||
MONGO_RW_USERNAME,
|
||||
MONGO_RW_PASSWORD,
|
||||
MONGO_HOSTNAME,
|
||||
MONGO_PORT,
|
||||
MONGO_NAME
|
||||
} = process.env;
|
||||
const muo = new URL(`mongodb://${MONGO_HOSTNAME}:${MONGO_PORT}/${MONGO_NAME}`);
|
||||
muo.username = MONGO_RW_USERNAME;
|
||||
muo.password = MONGO_RW_PASSWORD;
|
||||
mongoConnectionString = `${muo.href}`;
|
||||
} else {
|
||||
mongoConnectionString = process.env.MONGO_URL;
|
||||
}
|
||||
const mongoConnectionString = process.env.MONGO_URL;
|
||||
|
||||
mongoose.connect(mongoConnectionString, { useMongoClient: true });
|
||||
mongoose.connection.on('error', () => {
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ import basicAuth from 'express-basic-auth';
|
|||
import webpack from 'webpack';
|
||||
import webpackDevMiddleware from 'webpack-dev-middleware';
|
||||
import webpackHotMiddleware from 'webpack-hot-middleware';
|
||||
import config from '../webpack.config.dev';
|
||||
import config from '../webpack/config.dev';
|
||||
|
||||
// Import all required modules
|
||||
import users from './routes/user.routes';
|
||||
|
|
@ -58,22 +58,7 @@ if (process.env.NODE_ENV === 'development') {
|
|||
corsOriginsWhitelist.push(/localhost/);
|
||||
}
|
||||
|
||||
let mongoConnectionString;
|
||||
if (process.env.NODE_ENV === 'production' && process.env.MONGO_RW_USERNAME && process.env.MONGO_RW_PASSWORD) {
|
||||
const {
|
||||
MONGO_RW_USERNAME,
|
||||
MONGO_RW_PASSWORD,
|
||||
MONGO_HOSTNAME,
|
||||
MONGO_PORT,
|
||||
MONGO_NAME
|
||||
} = process.env;
|
||||
const muo = new URL(`mongodb://${MONGO_HOSTNAME}:${MONGO_PORT}/${MONGO_NAME}`);
|
||||
muo.username = MONGO_RW_USERNAME;
|
||||
muo.password = MONGO_RW_PASSWORD;
|
||||
mongoConnectionString = `${muo.href}`;
|
||||
} else {
|
||||
mongoConnectionString = process.env.MONGO_URL;
|
||||
}
|
||||
const mongoConnectionString = process.env.MONGO_URL;
|
||||
app.set('trust proxy', true);
|
||||
|
||||
// Enable Cross-Origin Resource Sharing (CORS) for all origins
|
||||
|
|
|
|||
|
|
@ -88,7 +88,7 @@ module.exports = [{
|
|||
},
|
||||
},
|
||||
{
|
||||
entry: path.resolve(__dirname, 'client/utils/previewEntry.js'),
|
||||
entry: path.resolve(__dirname, '../client/utils/previewEntry.js'),
|
||||
target: 'web',
|
||||
output: {
|
||||
path: `${__dirname}`,
|
||||
|
|
@ -117,8 +117,8 @@ module.exports = [{
|
|||
plugins: [
|
||||
[
|
||||
'babel-plugin-webpack-loaders', {
|
||||
'config': './webpack.config.babel.js',
|
||||
"verbose": false
|
||||
'config': path.resolve(__dirname, './config.babel.js'),
|
||||
'verbose': false
|
||||
}
|
||||
]
|
||||
]
|
||||
|
|
@ -2,10 +2,10 @@ const path = require('path');
|
|||
const nodeExternals = require('webpack-node-externals');
|
||||
|
||||
module.exports = [{
|
||||
entry: path.resolve(__dirname, 'server/scripts/fetch-examples.js'),
|
||||
entry: path.resolve(__dirname, '../server/scripts/fetch-examples.js'),
|
||||
|
||||
output: {
|
||||
path: __dirname + '/dist/',
|
||||
path: path.resolve(__dirname, '../dist/'),
|
||||
filename: 'fetch-examples.bundle.js'
|
||||
},
|
||||
|
||||
|
|
@ -36,7 +36,7 @@ module.exports = [{
|
|||
plugins: [
|
||||
[
|
||||
'babel-plugin-webpack-loaders', {
|
||||
'config': './webpack.config.babel.js',
|
||||
'config': path.resolve(__dirname, './config.babel.js'),
|
||||
"verbose": false
|
||||
}
|
||||
]
|
||||
|
|
@ -47,10 +47,10 @@ module.exports = [{
|
|||
},
|
||||
},
|
||||
{
|
||||
entry: path.resolve(__dirname, 'server/scripts/fetch-examples-gg.js'),
|
||||
entry: path.resolve(__dirname, '../server/scripts/fetch-examples-gg.js'),
|
||||
|
||||
output: {
|
||||
path: __dirname + '/dist/',
|
||||
path: path.resolve(__dirname, '../dist/'),
|
||||
filename: 'fetch-examples-gg.bundle.js'
|
||||
},
|
||||
|
||||
|
|
@ -81,7 +81,7 @@ module.exports = [{
|
|||
plugins: [
|
||||
[
|
||||
'babel-plugin-webpack-loaders', {
|
||||
'config': './webpack.config.babel.js',
|
||||
'config': path.resolve(__dirname, './config.babel.js'),
|
||||
"verbose": false
|
||||
}
|
||||
]
|
||||
|
|
@ -1,4 +1,5 @@
|
|||
const webpack = require('webpack');
|
||||
const path = require('path');
|
||||
const ExtractTextPlugin = require('extract-text-webpack-plugin');
|
||||
const ManifestPlugin = require('webpack-manifest-plugin');
|
||||
const ChunkManifestPlugin = require('chunk-manifest-webpack-plugin');
|
||||
|
|
@ -16,7 +17,7 @@ module.exports = [{
|
|||
entry: {
|
||||
app: [
|
||||
'babel-polyfill',
|
||||
'./client/index.jsx'
|
||||
path.resolve(__dirname, '../client/index.jsx')
|
||||
],
|
||||
vendor: [
|
||||
'axios',
|
||||
|
|
@ -39,7 +40,7 @@ module.exports = [{
|
|||
]
|
||||
},
|
||||
output: {
|
||||
path: `${__dirname}/dist/static`,
|
||||
path: path.resolve(__dirname, '../dist/static'),
|
||||
filename: '[name].[chunkhash].js',
|
||||
publicPath: '/'
|
||||
},
|
||||
|
|
@ -132,12 +133,12 @@ module.exports = [{
|
|||
{
|
||||
entry: {
|
||||
app: [
|
||||
'./client/utils/previewEntry.js'
|
||||
path.resolve(__dirname, '../client/utils/previewEntry.js')
|
||||
]
|
||||
},
|
||||
target: 'web',
|
||||
output: {
|
||||
path: `${__dirname}/dist/static`,
|
||||
path: path.resolve(__dirname, '../dist/static'),
|
||||
filename: 'previewScripts.js',
|
||||
publicPath: '/'
|
||||
},
|
||||
|
|
@ -4,10 +4,10 @@ const nodeExternals = require('webpack-node-externals');
|
|||
|
||||
module.exports = {
|
||||
|
||||
entry: path.resolve(__dirname, 'server/server.js'),
|
||||
entry: path.resolve(__dirname, '../server/server.js'),
|
||||
|
||||
output: {
|
||||
path: __dirname + '/dist/',
|
||||
path: path.resolve(__dirname, '../dist/'),
|
||||
filename: 'server.bundle.js',
|
||||
},
|
||||
|
||||
|
|
@ -42,7 +42,7 @@ module.exports = {
|
|||
plugins: [
|
||||
[
|
||||
'babel-plugin-webpack-loaders', {
|
||||
'config': './webpack.config.babel.js',
|
||||
'config': path.resolve(__dirname, './config.babel.js'),
|
||||
"verbose": false
|
||||
}
|
||||
]
|
||||
Loading…
Reference in New Issue