Bmore Responsive

An API to drive disaster and emergency response systems.

Bmore Responsive
- Documentation
Setup
Using this product
- Testing
Sources and Links
- Contributors ✨

Documentation

Detailed documents describing this project and its use are available in this repository. The documentation currently available is as follows:

API Spec

Our API spec is on Swagger. You can view it here https://app.swaggerhub.com/apis/codeforbaltimore/bmoreResponsive or you can find the swagger.json file in our docs folder and use it via http://localhost:3000/api-docs/ when the app is running locally.

Database Documentation

Our database documentation can be found in the /sequelize directory or you can click here

Infrastructure and Deployment

We have included a terraform option to deploy to AWS. For more information on how to use this feature, please see the terraform directory.

Setup

This setup section will focus on setting up the local dev environment. For more detailed instructions for how to deploy this to a production environment please see the section above this one ☝️

To work on this project you should have:

Node.js
PostgreSQL (can be in Docker)
Docker (optional)
Terraform (optional, for AWS deploy) Once you have the prerequisite software installed you can proceed to setup this application.

A Dockerfile and docker-compose file have been included for convenience, however this may not be the best local development setup for this project. For more information on how to use Docker with this project, please see the docker section.

Node and Express setup

This application is designed to work as an API driven by Express. To setup your environment first you must install all required dependencies by running the following command from the root of your project directory:

npm install

Once all dependencies are installed you will need to setup some environment variables to interact with your database and application.

Environment variables

You will need to set some local environment variables to run this application. This is true even if you're using Docker.

touch .env
echo 'NODE_ENV=local
PORT=<your port>
DATABASE_SCHEMA=<your database schema>
JWT_KEY=<your secret JWT seed phrase or key>
DATABASE_URL=<your db connection string>
' >> ./.env

The DATABASE_URL is not a very clear var name, and the string is broken down as postgres://username:password@host:port/database_name

An example of the DATABASE_URL would be DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres

The various variables are defined as follows:

NODE_ENV = The label for your environment.
PORT = The local port you wish to run on. Defaults to 3000.
DATABASE_URL = The URL string for your db connection. For example: postgres://user:pass@example.com:5432/dbname
DATABASE_SCHEMA = Your local database schema. Postgres default is public.
JWT_KEY = A secret value to generate JWT's locally.
SMTP_HOST = optional hostname for the SMTP server used to send notification emails
SMTP_PORT = optional port number for the SMTP server used to send notification emails
SMTP_USER = optional username for the SMTP server used to send notification emails
SMTP_PASSWORD = optional password for the SMTP server used to send notification emails
URL = optional the URL for your front-end application
TEST_EMAIL = optional the email you wish to send tests to
BYPASS_LOGIN = optional Allows you to hit the endpoints locally without having to login. If you wish to bypass the login process during local dev, set this to true.

We do not recommend using the default options for PostgreSQL. The above values are provided as examples. It is more secure to create your own credentials.

Warning: If you are running Docker Toolbox instead of Docker Desktop (likely meaning you are running Windows 10 Home, not Professional) you will need to change your .env to reflect Docker running on a VM:

DATABASE_HOST: The IP address Docker is running on. You can find this by running docker-machine ip but it's usually 192.168.99.100 instead of localhost
DATABASE_URL: This will need to be adjusted as well, for example DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres would become DATABASE_URL=postgres://postgres:postgres@192.168.99.100:5432/postgres

Example .env

To make this easier included below is an example .env file using all default values. We highly recommend you use custom values, but this should clarify what is needed for this to run.

NODE_ENV=development
PORT=3000
JWT_KEY=test123
DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres
DATABASE_SCHEMA=public
BYPASS_LOGIN=true
URL=http://localhost:8080
TEST_EMAIL=jason@codeforbaltimore.org

PostgreSQL

You will need a PostgreSQL database running locally to run this application locally. You may setup PostgreSQL however you wish, however we recommend using Docker using the instructions found here: https://hub.docker.com/_/postgres

If you are using Docker you may spin up your database layer by running this command:

docker run -d -e POSTGRES_PASSWORD=<your chosen password> -p 5432:5432 postgres

If you're running a database in another way then we trust you can sort it out on your own because you're awesome 😎

Sequelize

To properly start the application the database needs to be built by Sequlize ahead of time. To do that run the following commands

You must create your database tables without running the application by running npm run db-create first.
optional You can now seed your database if you wish by running npm run db-seed.

Example /migrations and /seeders scripts have been supplied. You can rollback your all seeded data at any time by running npm run db-unseed and delete all created tables with npm run db-delete.

Docker

You can build and run the application in Docker locally by running the following commands:

docker build -t bmoreres .
docker run -d -p 3000:3000 --env-file=.env bmoreres

Note that DATABASE_URL host location will be different depending on what OS you're using. On Mac it is docker.for.mac.host.internal and on Windows it is docker.for.win.host.internal if using docker-compose it will be db. Please see Example .env for more information.

Alternatively you can manually set the environment variables and not use a .env file by setting the following vars:

-e NODE_ENV=development
-e PORT=3000 
-e JWT_KEY=<your JWT phrase>
-e DATABASE_URL=<your connection string>
-e DATABASE_DATABASE_SCHEMA=<your database schema>

docker-compose

To use the docker-compose.yml file included you will first need to set environment variables. You MUST set your DATABASE_HOST to db to use the docker-compose solution. It is not recommended to use docker-compose for any reason other than to test a solution for a separate front-end component.

Using this product

You may use this product to create and manage users for your front-end.

To run the application--after the above steps are completed--run npm start.

Testing

To test your code you may write test cases to ./index.spec.js and then run the tests with npm test.

To check your linting you may run npm run lint and to format and automatically fix your formatting run npm run format.

Sources and Links

We are also building a front-end application called Healthcare Rollcall to interact with this backend API. To view that project, or to contribute to it, please visit the repo here: https://github.com/CodeForBaltimore/Healthcare-Rollcall

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Jason Anton} 💻 📖 🚇	_{Jason Bixon} 💻 🚇 👀	_cshamrick 💻 🚇 🛡️	_{Ati Ok} 💻	_joffutt4 💻 📖 👀	_{joffutt-bellese} 💻 📖 👀	_{Snyk bot} 🛡️
_Dependabot 🛡️	_{Gabriel Boorse} 💻 👀	_bani-bellese 💻 🚇 🛡️	_{Sean Crim} 💻 👀	_carorm ⚠️ 👀	_{blakenan-bellese} 🤔 ⚠️ 📖	_c-w-allen 💻 👀
_msmith125 ⚠️ 👀