p5.js-web-editor/README.md

120 lines
8.1 KiB
Markdown
Raw Normal View History

2017-04-06 03:50:17 +02:00
# p5.js Web Editor
2016-05-03 22:13:04 +02:00
2017-03-10 00:03:45 +01:00
This project is currently in development! It will be announced when there is a (public) beta release.
2016-11-23 19:55:42 +01:00
2017-04-06 03:50:17 +02:00
## Development Installation
2016-05-11 06:02:12 +02:00
2016-06-29 00:21:05 +02:00
1. Clone this repostory and cd into it
2016-11-23 19:43:19 +01:00
2. `$ git submodule init`
3. `$ npm install`
4. Install MongoDB and make sure it is running
2017-01-17 21:03:37 +01:00
* 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/)
2016-11-23 19:43:19 +01:00
5. Create a file called `.env` in the root of this directory that looks like
2016-08-01 10:28:43 +02:00
```
API_URL=/api
2016-08-01 10:26:53 +02:00
MONGO_URL=mongodb://localhost:27017/p5js-web-editor
PORT=8000
SESSION_SECRET=whatever_you_want_this_to_be_it_only_matters_for_production
AWS_ACCESS_KEY=<your-aws-access-key>
AWS_SECRET_KEY=<your-aws-secret-key>
2017-04-13 20:39:03 +02:00
AWS_REGION=<your-aws-region>
2016-08-01 10:26:53 +02:00
S3_BUCKET=<your-s3-bucket>
2016-09-02 23:40:44 +02:00
GITHUB_ID=<your-github-client-id>
GITHUB_SECRET=<your-github-client-secret>
2016-08-01 10:26:53 +02:00
```
If you don't care about being able to upload media files to S3 or Login with Github, you can drop in the file exactly how it is. Or, if you don't want to do that, just ask me to send you mine. Refer to [this gist](https://gist.github.com/catarak/70c9301f0fd1ac2d6b58de03f61997e3) for creating an S3 bucket for testing, or if you don't want to do that, I can add you to one of my S3 buckets.
2017-04-12 01:55:05 +02:00
6. `$ npm run fetch-examples` - this downloads the example sketches into a user called 'p5'
7. `$ npm start`
8. Navigate to [http://localhost:8000](http://localhost:8000) in your browser
9. Install the [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en).
10. Open and close the Redux DevTools using `ctrl+h`, and move them with `ctrl+w`
2016-05-11 06:02:12 +02:00
2017-04-06 03:50:17 +02:00
### 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.
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.
2017-04-06 03:50:17 +02:00
## Production Installation
2016-06-29 00:28:35 +02:00
1. Clone this repostory and `cd` into it
2016-11-23 19:43:19 +01:00
2. `$ git submodule init`
3. `$ npm install`
4. Install MongoDB and make sure it is running
5. Create a file called `.env` in the root of this directory that looks like
2016-08-01 10:28:43 +02:00
```
API_URL=/api
2016-08-01 10:26:53 +02:00
MONGO_URL=mongodb://localhost:27017/p5js-web-editor
PORT=8000
SESSION_SECRET=make_this_a_long-random_string_like_maybe_126_characters_long
AWS_ACCESS_KEY=<your-aws-access-key>
AWS_SECRET_KEY=<your-aws-secret-key>
2017-04-13 20:39:03 +02:00
AWS_REGION=<your-aws-region>
2016-08-01 10:26:53 +02:00
S3_BUCKET=<your-s3-bucket>
2016-09-02 23:40:44 +02:00
GITHUB_ID=<your-github-client-id>
GITHUB_SECRET=<your-github-client-secret>
Email verification (#369) * Re-introduce Email Verification code Revert "Revert "Email verification"" This reverts commit d154d8bff259350523a0f139e844db96c43d2ee1. * Uses MJML to generate Reset Password email * Sends Password Reset and Email Confirmation emails using MJML template * Sends verified status along with user data * API endpoint for resending email verification confirmation * Displays verification status on Account page and allows resending * Send back error string * Passes email address through to sign/verify helper * Uses enum-style object to set verified state * Sends minimal info when user verifies since it can be done without login * Provides /verify UI and sends confirmation token to API * Better name for JWT secret token env var * Adds mail config variables to Readme * Encrypts email address in JWT The JWT sent as the token in the Confirm Password URL can be unencoded by anyone, although it's signature can only be verified by us. To ensure that no passwords are leaked, we encrypt the email address before creating the token. * Removes unused mail templates * Resets verified flag when email is changed and sends another email * Moves email confirmation functions next to each other * Extracts random token generator to helper * Moves email confirmation actions into Redux - updates the AccountForm label with a message to check inbox - show status when verifying email token * Uses generated token stored in DB for email confirmation * Sets email confirmation status to verified if logging in from Github * Sends email using new method on account creation * Fixes linting errors * Removes replyTo config
2017-06-26 18:48:28 +02:00
EMAIL_SENDER=<email-address-to-send-from>
MAILGUN_KEY=<mailgun-api-key>
MAILGUN_DOMAIN=<mailgun-domain>
EMAIL_VERIFY_SECRET_TOKEN=whatever_you_want_this_to_be_it_only_matters_for_production
2016-08-01 10:26:53 +02:00
```
For production, you will need to have real Github and Amazon credentions. Refer to [this gist](https://gist.github.com/catarak/70c9301f0fd1ac2d6b58de03f61997e3) for creating an S3 bucket for testing.
2017-04-06 03:50:17 +02:00
6. `$ npm run fetch-examples` - this downloads the example sketches into a user called 'p5'
7. `$ npm run build`
8. `$ npm run start:prod`
2016-05-11 06:02:12 +02:00
2017-04-06 03:50:17 +02:00
### For Production Setup with PM2
2016-06-29 00:21:05 +02:00
1. `$ npm install -g pm2`
2. `$ pm2 start ecosystem.json`
2017-04-06 03:50:17 +02:00
## Accessibility Guidelines
Here is guide on [how to use the accessible editor](https://gist.github.com/MathuraMG/e86666b7b41fbc8c078bad9aff3f666d)
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/)
2017-04-06 03:50:17 +02:00
## Contribution Guide
2016-06-29 00:21:05 +02:00
I am currently open to contributors! Email me if you are looking for a task, or look at the open issues and reply that you are working on a task.
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).
2016-11-23 19:43:19 +01:00
This project uses an in-development [p5.js interceptor library](https://github.com/MathuraMG/p5-interceptor) for accessibility as git submodule. Every time you run `npm install`, it will update the interceptor to HEAD, so it is important to do this often.
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.
2016-06-29 00:21:05 +02:00
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).
2016-11-16 21:03:10 +01:00
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.
2016-05-11 06:02:12 +02:00
2017-04-06 03:50:17 +02:00
## Dump of links I'm saving for reference
2016-05-11 06:02:12 +02:00
2016-06-29 18:52:16 +02:00
* https://github.com/brigade/scss-lint
2016-05-03 22:13:04 +02:00
* https://github.com/petehunt/react-howto
* https://github.com/jsbin/jsbin (especially look at the console)
2016-05-11 06:02:12 +02:00
* Need to figure out how to solve the XSS issue, https://github.com/jsbin/jsbin/wiki/Best-practices-for-building-your-own-live-paste-bin
2016-08-01 10:25:38 +02:00
* https://www.npmjs.com/package/express-subdomain
2016-11-16 21:03:10 +01:00
* https://github.com/jsbin/jsbin/blob/master/public/js/render/console.js - the code is a little messy but it might be useful