README_FOR_APP.md

If you're not a developer, please go away now.

Development methodology -- read me first

0. We use branch-per-feature for development, so that master is always clean and ready to deploy. NEVER PUSH MASTER THAT HAS FAILING TESTS. EVER. See below for how to run tests. The main repo is ucberkeley/moocchat on GitHub.
1. We use Pivotal Tracker to track features, bugs, releases, etc.
2. Branch naming convention is feature/XX/name-of-feature (where XX are initials of developer, eg "AF") for new features, bug/XX/description-of-bug for bug fixes, test/XX/description-of-test for changes that add test coverage, etc.
3. We are using CodeClimate to monitor our code quality

Developers -- important note on authentication

Google OAuth2 is used to enforce that only Instructors and Administrators may administer content. To make someone an instructor or administrator:

0. Make sure the type field (i.e. subclass) of their entry in the users table is set to either Instructor or Administrator
1. Make sure they have a nonblank email attribute that exactly matches their Google email address.
   Currently this must be done manually.

In production, you must setup a Google OAuth2 API key and enable Google+ and Google Contacts on your Heroku deployment, and wait a few minutes for the changes to take effect on Google's side. You must also set environment variable GOOGLE_CLIENT_ID to the OAuth2 client ID provided by Google and GOOGLE_CLIENT_SECRET to the client secret provided by Google for that key. (On Heroku, you do this on the app's Settings page.) In addition, on the Google settings for that API key, the "Redirect URI" must be https://your-app-name.herokuapp.com/auth/google_oauth2/callback.

In development, Google OAuth2 is turned off, and the "Google Login" button is replaced by a "Dev Mode Login" button. On the login form, enter your name and email exactly as they'd appear if you were authenticating with Google, and you'll be logged in.

For testing (Cucumber scenarios), if your scenario specifically deals with testing authentication directly, give it the tag @auth_test. You will then have to create OmniAuth mocks to simulate the desired result of an authentication transaction; see features/step_definitions/auth_steps.rb for an example. All scenarios WITHOUT this tag will be preceded by a Before action (see features/support/env.rb) that simulates an admin login, so these scenarios can assume that an admin is logged in.

For testing (RSpec controller tests): TBD

Developers -- detailed setting up on a fresh Ubuntu 14.04.1 install

0. sudo apt-get update && sudo apt-get upgrade
1. mkdir .ssh
2. Install your SSH key for Github in ~/.ssh/id_rsa
3. chmod 600 ~/.ssh/id_rsa
4. sudo apt-get install git curl libpq-dev phantomjs chromium-chromedriver python-selenium nodejs postgresql default-jre
5. sudo ln -s /usr/lib/chromium-browser/chromedriver /usr/bin/chromedriver
6. sudo ln -s /usr/lib/chromium-browser/libs/lib*.so /usr/lib/
7. sudo su postgres -c psql (this will enter the postgres environment where you will set up the database)
8. CREATE USER yourusername CREATEDB; (use your UNIX username in place of yourusername)
9. \q (to exit postgres)
10. curl -sSL https://get.rvm.io | bash
11. source ~/.rvm/scripts/rvm
12. git clone git@github.com:ucberkeley/moocchat.git
13. cd moocchat
14. rvm install ruby-1.9.3-p547 --disable-binary
15. bundle install
16. make check
17. foreman run local
18. Access http://localhost:3000 in a web browser to try the app.

Developers -- getting started on other systems

0. Clone this repo
1. Change into app's root directory
2. Run bundle install to make sure you have all gems/libraries
3. Install PhantomJS to run JavaScript tests headlessly:
4. Mac OS with homebrew: brew install phantomjs
5. Other cases: download here
6. Install Google Chrome and chromedriver for certain Cucumber tests that require it:
7. Mac OS with homebrew: brew install chromedriver
8. Mac OS without homebrew, or other platforms:
   Download here, but in general, after download sudo mv chromedriver /usr/bin/ and sudo chmod +x /usr/bin/chromedriver;
9. Run make check (that's make, not rake) to create development database, populate its schema, insert any initial data, and run regression tests to make sure all is well (see below under Deploying)
10. foreman run local to start the app
11. It should now be live on http://localhost:3000

Pushing to master

0. Before you do any merging: go back to master and do a git pull to make sure you have latest master
1. Then switch back into your branch and rebase against master, fixing any conflicts, and making sure all your tests are passing.
2. Running make check will run the following, which "clean-tests" your branch:

rm -rf tmp/      # deletes any cached assets
rake db:schema:load  # recreates fresh set of empty tables in DB
rake db:seed     # loads fixed data
rake db:test:prepare  # loads DB schema into test database
rake cucumber    # runs all scenarios
rake spec        # runs all specs, including javascript

to verify that there is no bug introduced 0. Then do pull request on your rebased branch

To deploy on Heroku for your own testing:

0. Install the Heroku tools as instructed here: https://toolbelt.heroku.com
1. First time: heroku apps:create pick-some-app-name (or to use the existing moocchat deployment, heroku git:remote -a moocchat)
2. Make sure your changes are committed locally
3. git push heroku master
4. The first time you deploy, you must also heroku run rake db:migrate to setup the database, and heroku run rake db:seed to populate it with necessary initial data. (Warning: the db:seed task wipes the database before re-seeding it, so don't use it if you want to preserve existing data!)
5. Your app should now be live at http://pick-some-app-name.herokuapp.com
6. If you get an application failed error message, try 'heroku run rake db:migrate' then refresh page

Testing your JavaScript

0. You can add tests in spec/javascripts/*.js or *.js.coffee
1. To run tests with browser GUI: start the app locally (foreman start) then go to http://localhost:5000; each time you re-load this page, it re-runs all your JS specs
2. To run tests from command line: rake spec:javascript (uses phantomjs)

Other useful tasks

Do not push code that causes these tasks to fail!

• git push heroku master deploys on Heroku; don't push code that cannot be deployed
• rake diagram:all creates three .svg picture files in doc/ that contain the app's class diagrams. The most interesting is probably doc/models_complete.svg
• rake spec runs all unit and functional tests
• rake spec:javascript runs all JavaScript tests in headless mode
• rake cucumber runs all features that should pass (user stories)
• rake metrics:all generates a bunch of metrics; to see them, open ./tmp/metric_fu/output/index.html in a browser after running this command
• CodeClimate code quality for this project

The Heroku production deployment

The app is hosted on Armando's Heroku account as moocchat.herokuapp.com.

We have extended monitoring turned on to help troubleshoot system load issues. heroku logs --tail shows them.

NewRelic APM (application performance monitoring) is turned on. In the app's Heroku resources dashboard,
click New Relic.

Notes on websocket chatserver load testing

1. open moocchat/benchmark/chatserver/groups.py and modify number and size accordingly. number is total number of alive websockets at at the same time. size is size of a chat group.
2. cd into moocchat/benchmark/chatserver/result
3. run python ../groups.py
4. result of load testing will be stored in moocchat/benchmark/chatserver/result. Scroll to the bottom of this file to for "Finish a total of: " to see total number of websockets successfully kept alive at the same time.