rabblerouser-core

Rabble Rouser core is the membership database component of the Rabble Rouser ecosystem. It provides a member sign up form and an administrative backend which allows editing of members.

To find out more about the Rabble Rouser project, check out our documentation repo.

First-time setup

Install VirtualBox, Vagrant, and Ansible

Clone the project

 git clone https://github.com/rabblerouser/rabblerouser-core.git

Start the Vagrant VM and log into it

 cd rabblerouser-core
 vagrant up
 vagrant ssh

Install project dependencies and compile the frontend assets
```
 npm install
```
Run the tests (backend & frontend)
```
 npm test
```
Seed the local database and start the app
```
 npm run seed
 npm start
```
Run the e2e tests (With the server still running - you may need to open another tab and vagrant ssh again.)
```
 npm run e2e
```
Verify that the app works:
Register a new member at http://localhost:3000
Log in at http://localhost:3000/login, with admin@rr.com/apassword

Later on you can run all tests (frontend, backend, and e2e) in one go with:

    npm run precommit

For the optional email configuration step, see near the bottom of this document.

Understanding this repository

This repository is split into these sub-directories:

backend: The backend node.js API
bin: Utility scripts, mostly for build/deploy tasks
e2e: End-to-end tests built with casperjs
frontend: The frontend React.js webapp
provisioning: Ansible scripts for environment setup (local and deployed)

The frontend, backend, and E2E tests are all written in JavaScript, so each one has a package.json file for dependencies and tasks. There is also another package.json at the top-level of the repo, which mainly orchestrates the tasks contained within the sub-projects.

The following sections assume that you've done the first time setup above.

"I want to work on the backend"

Automated testing workflow:

Make your changes
From the backend directory: npm test
Goto #1

###Manual testing workflow:

From the root directory: npm run build && npm start
Make your changes
Point your browser at http://localhost:3000
Goto #2

Note: Some specific files, such as the routes, may require a full restart. In this case, start from step 1 again. This is also the case if you happen to change any frontend code during this process.

"I want to work on the frontend (javascript or styles)"

###Automated testing workflow:

Make your changes
From the frontend directory: npm test
Goto #1

###Manual testing workflow:

cd /vagrant/backend && npm start
cd /vagrant/frontend && npm start
Make your changes
Point your browser at http://localhost:8080, and wait for the changes to hot-reload.
Goto #3

Linting

We use ESLint to maintain a consistent style and detect common sources of bugs, and this is run as part of the build system. To run ESLint just do npm run lint in one of the frontend, backend, or e2e directories.

To lint just a specific file or directory:

./node_modules/.bin/eslint --ext js,jsx src/path/to/file

You can even add --fix to the end of that command to automatically fix things like whitespace errors.

If you're not sure how to fix an ESLint error, you can look up the docs for specific rules using a URL like: http://eslint.org/docs/rules/arrow-parens. In this case, arrow-parens is the name of the rule.

We're using the airbnb style (slightly modified), which encourages use of many ES6 features. If you're not up to speed on ES6, this reference may come in handy: http://es6-features.org/.

Backend utility scripts

These should all be run from the backend directory.

Migrate the database (run automatically as part and npm start or npm test)
```
  ./node_modules/sequelize-cli/bin/sequelize db:migrate
```

Create a new migration

  ./node_modules/sequelize-cli/bin/sequelize migration:create --config config/db.json --name <migration_name>

Create an admin user for your local dev environment:
```
  npm run dev:createSuperAdmin
```
Create an admin user for the production environment:
```
  npm run createSuperAdmin
```

Customising the app for your organisation

At the moment, this is done using environment variables. The table below describes the use of these environment variables. At the moment, everything is optional, and a default theme will be provided if none is given.

Variable	Description	Used when...
ORG_NAME	The name of the organisation that members are registering for.	compiling the frontend
SKIN	The directory under `frontend/public/images` from where logos etc should be loaded.	compiling the frontend, running the backend

"compiling the frontend" means npm run build, or cd frontend && npm start.
"running the backend" means npm start or cd backend && npm start.

Email configuration

Rabble Rouser supports the following e-mailing tools:

Gmail

Set the email.transporter setting (in default.json) to 'gmail'
Create an Application Password trough your Google Account (Go here if you have 2 factor Authentication enabled)
Add EMAIL_USERNAME="your_email@gmail.com" EMAIL_PASSWORD="the password generated in the previous step" to environment vars
Turn on the toggle email.sendEmails in each specific environment (config/default.json, config/ staging.json, config/production.json)

MailGun

Set the email.transporter setting (in default.json) to 'mailgun'
In your control panel check the Default SMTP Login and Default Password for your domain.
Create the following env vars: EMAIL_USERNAME="Default SMTP Login" EMAIL_PASSWORD="Default Password"
Turn on the toggle email.sendEmails in each specific environment (config/default.json, config/ staging.json, config/production.json)

Pull a copy of the staging database from Heroku

heroku pg:backups capture --app <app_name>
curl -o db/dumps/latest.dump heroku pg:backups public-url
(in the VM) pg_restore --verbose --clean --no-acl --no-owner -h localhost -U rabble_rouser -d rabble_rouser_core_db db/dumps/latest.dump

Happy hacking!

yearofthedan / rr-playground