diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index c545ad3..68fee76 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -3,6 +3,10 @@ This file contains an overview of how to do development on this application, as well as HOWTOs for specific tasks. +## Testing + +`$ make test` + ## Architecture Overview TBD: Explain the various locations in the code tree that we most commonly find ourselves editing to accomplish tasks. @@ -208,4 +212,4 @@ are candidates for removal later. * Status - Part of Drywall package, but not used for this application. * StatusLog - Part of Drywall package, but not used for this application. * UsAddress - Used in this application. -* User - Used by Drywall for user management. \ No newline at end of file +* User - Used by Drywall for user management. diff --git a/INSTALL.md b/INSTALL.md index e949bcb..9058c0f 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,77 +1,78 @@ # Installing smoke-alarm-portal -These installation instructions assume a Debian GNU/Linux 'testing' -distribution operating system, but they should be portable without -much difficulty to most other Unix-like operating systems. + $ git clone https://github.com/redcross/smoke-alarm-portal.git + $ cd smoke-alarm-portal + +## Configuring -1. Download the code. + $ cp .env.tmpl .env - $ git clone https://github.com/OpenTechStrategies/smoke-alarm-portal.git - $ cd smoke-alarm-portal +For development/production, fill in the following values in `.env`: -1. Install [Node](https://nodejs.org/download/) and npm (a package manager). - On Debian, run: + * COMPANY_NAME + * PROJECT_NAME + * SYSTEM_EMAIL + * CRYPTO_KEY + * MAILGUN_API_KEY + * MAIL_DOMAIN + * MAIL_FROM_ADDR + * GOOGLE_MAPS_API_KEY + +Non-docker only: - $ sudo apt-get install nodejs - $ sudo apt-get install npm + * DB_USERNAME + * DB_PASSWORD + * DB_DATABASE + * DB_HOST - On Max OSX, use the Macintosh installer which can be downloaded - from https://nodejs.org/download/, to install both node and - npm. In Terminal, run: +## Installing with Docker - $ sudo npm install npm -g +Make sure you have [Docker](https://docs.docker.com/install/) and [Docker +Compose](https://docs.docker.com/compose/install/) installed. -1. Install PostgreSQL, at least version 9.2 (to support `JSON` column type). + $ make build + $ make run - On Debian: +## Installing Locally - $ sudo apt-get install postgresql-9.4 # for example +These installation instructions assume a Debian GNU/Linux 'testing' +distribution operating system, but they should be portable without +much difficulty to most other Unix-like operating systems. - (This may result in your having multiple versions of PostgreSQL - installed, which in turn can lead to mysterious errors in the - coming import step. If you encounter such errors, see the - appropriate part of the "Troubleshooting" section later on.) +1. Install dependencies - On Mac OS X: + **Debian:** - Install PostgreSQL via Brew (http://exponential.io/blog/2015/02/21/install-postgresql-on-mac-os-x-via-brew/). - Installation instructions for brew can be found on the [Homebrew website](http://brew.sh). + $ sudo apt-get install nodejs npm postgresql-9.4 - $ brew update - $ brew install postgres + (This may result in your having multiple versions of PostgreSQL installed, + which in turn can lead to mysterious errors in the coming import step. If + you encounter such errors, see the appropriate part of the "Troubleshooting" + section later on.) -1. OPTIONAL: PostgreSQL probably created a `postgres` user, but if it -didn't, you might want to add one: + **MacOS:** - $ adduser postgres + Use the Macintosh installer which can be downloaded from + https://nodejs.org/download/, to install both node and npm and run: -1. Set up the live config files. Note that there are multiple files to -be edited here. - - 1. Do `cp config.js.tmpl config.js`. For dev, move on to step 2. For non-dev, edit the `config.js` file: - - * Update `exports.companyName`, - `exports.projectName`, `exports.signupEnabled`,`exports.systemEmail`, and - `exports.cryptoKey`. + $ sudo npm install npm -g - 1. Do `cp config/config.json.tmpl config/config.json`. For dev, move on to step 3. For non-dev, edit the `config/config.json`: + Install PostgreSQL via Homebrew + (http://exponential.io/blog/2015/02/21/install-postgresql-on-mac-os-x-via-brew/). + Installation instructions for brew can be found on the [Homebrew website](http://brew.sh). - * Fill in database usernames and passwords, and - the Mailgun.com API key and sender information that the app will use to send out email notifications. - You can modify one of the existing top-level environments listed in `config.json` - or set up a whole new environment, e.g., "demo" (e.g., based on the "test" example). + $ brew update + $ brew install postgres - To enable Geocoding of entered addresses, make sure to configure your - Google Maps geocoding API key: `googleMapsApiKey` +2. OPTIONAL: PostgreSQL probably created a `postgres` user, but if it didn't, + you might want to add one: - (Don't worry if you don't know how to set up a database - username / password; that will be explained in a later step.) + $ adduser postgres - 1. Do `cp config/recipients.sql.tmpl config/recipients.sql`, edit the `config/recipients.sql` file: +3. Do `cp config/recipients.sql.tmpl config/recipients.sql`, edit the `config/recipients.sql` file: - * Fill in appropriate contact names and email - addresses. - * For dev, either leave the placeholders intact (if you didn't set up Mailgun and don't want to test the email-sending functionality) or replace the placeholders with your name and email address (so that when you submit test requests to your local instance, all the emails generated come to you). + * Fill in appropriate contact names and email addresses. + * For dev, either leave the placeholders intact (if you didn't set up Mailgun and don't want to test the email-sending functionality) or replace the placeholders with your name and email address (so that when you submit test requests to your local instance, all the emails generated come to you). 1. Get other required node modules. @@ -159,40 +160,34 @@ be edited here. $ ./node_modules/.bin/forever -da start --watchDirectory . -l forever.log -o out.log -e err.log ./bin/www -1. See if it's working, by visiting http://localhost:3000/ - - TBD: Need instructions for changing to port 80 and eventually 443 - for demo and production. +## Creating an admin user -1. Create an admin user. + To create the admin user, you must first temporarily re-enable signups, which + are disabled by default. - To create the admin user, you must first temporarily re-enable - signups, which are disabled by default. + 1. In `.env`, change `SIGNUP_ENABLED` from `0` to `1`. - 1. In `config.js`, change `exports.signupEnabled` from `false` to `true`. + 2. Visit http://localhost:3000/signup in your browser - 1. Visit http://localhost:3000/signup in your browser + 3. Create a user named `admin` there (remember the password you choose) - 1. Create a user named `admin` there (remember the password you choose) - - 1. In `config.js`, change `exports.signupEnabled` back to `false`. + 4. In `.env`, change `SIGNUP_ENABLED` back to `0`. (If you don't do this step, anyone who can figure out the URL can create a user account with administrative privileges, which would obviously be bad.) - 1. Grant your new admin user permission to view requests from all - regions, using this file: + 5. Grant your new admin user permission to view requests from all regions, + using this file: [migrations/20151208-admin-access.sql.tmpl](migrations/20151208-admin-access.sql.tmpl). Following the instructions in the file, copy it to - `migrations/20151208-admin-access.sql` and replace the - `__USER_ID__` with the id of your new admin user (if the admin - user was the first user you created, then this will probably be - `1`). Once you've done that, run the following commands: - - ``` - $ psql smokealarm_development - smokealarm_development=# \i migrations/20151208-admin-access.sql - ``` + migrations/20151208-admin-access.sql` and replace the __USER_ID__` with + the id of your new admin user (if the admin user was the first user you + created, then this will probably be 1). + + 6. Once you've done that, run the following commands: + + Docker: `docker-compose run db psql -d smokealarm_development -f migrations/20151208-admin-access.sql` + Local: `psql -d smokealarm_development -f migrations/20151208-admin-access.sql` Now you can visit http://localhost:3000/login/ at any time, log in as `admin`, and from there click on "Smoke Alarm Installation Requests" @@ -204,19 +199,20 @@ be edited here. page (http://localhost:3000/) before any requests would be listed on the /admin/requests page.) -1. Sign up for [Twilio](https://www.twilio.com): Set up a number that +## Signing up for [Twilio](https://www.twilio.com) - * Create account, or use the OTS account (if part of OTS) - * Get a new phone number (in Manage Phone Numbers) - * Update `config/config.json` twilio parameters to the account SID/Auth Token - in your settings on twilio - * Setup the phone number in twilio messaging section to be - * Webhook -> `http:///sms`, using `HTTP GET` + * Create account, or use the OTS account (if part of OTS) + * Get a new phone number (in Manage Phone Numbers) + * Update `config/config.json` twilio parameters to the account SID/Auth Token in your settings on twilio + * Setup the phone number in twilio messaging section to be + * Webhook -> `http:///sms`, using `HTTP GET` - Then when you start your server up, you should be able to text the number you - set up to test the system. + Then when you start your server up, you should be able to text the number you + set up to test the system. + +## Testing -1. Manually perform tests listed in [TESTING.md](docs/TESTING.md). +See testing instructions at [TESTING.md](docs/TESTING.md). Appendix A: Setting up Apache->Node ProxyPass with https:// -----------------------------------------------------------