diff --git a/.gitignore b/.gitignore index ff84b186..6ef67133 100644 --- a/.gitignore +++ b/.gitignore @@ -113,4 +113,7 @@ dist .idea .terraform *.plan -*.out \ No newline at end of file +*.out + +# MKDocs Wiki +site/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8c57725a..ec7790a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,76 +1,2 @@ # Contributing -When contributing to this repository, please first discuss the change you wish to make via issue, -email, slack, or any other method with the contributes of this repository, or Code for Baltimore, before making a change. - -Please note we have a [Code of Conduct](/docs/Code_of_Conduct.md), please follow it in all your interactions with the project. - -## Overview -In the event of a disaster a municipality or state may have need to check in on the status of all healthcare providers, -or other types of entities, within in the jurisdiction. This system will provide methods for healthcare providers and -entities to check-in during disasters, and update their contact information during non-emergency periods. During an -emergency this system will track (among other things) if any entity: - -* Has power -* Has sufficient supplies -* Is informed about the emergency - -This system will make use of digital services and modern methodologies to automate and simplify parts of the check-in process -to help the municipality prioritize its call/check-in list and response plan. Additionally, the system will validate contact -information regularly during non-emergency times to ensure the municipality has the most up-to-date information for each entity. - -### Non Goals -What will this project not accomplish during its initial creation? - -- No front-end website or app -- No outside data interactions -- Non-city employee full login (dashboard, etc) -- Statistical or analytical endpoints - -### Minimum Viable Product -To use this product as quickly as possible we will be implementing the following features: -- User creation -- Contact creation -- Entity creation -- Contact->Entity linking -- Contact single-use login check-in ability - -### Roadmap -Milestones and project timelines can be viewed on the [Projects page](https://github.com/CodeForBaltimore/Bmore-Responsive/projects) - -## Technology and Code - -This project will make exclusive use of open-source software, packages, and contributions. The application is built with the following -technologies: - -- Javascript (ES6) -- [Node.js](https://nodejs.org/en/) -- [Express.js](https://expressjs.com/) -- [Sequelize](https://sequelize.org/v3/) -- [Docker](https://www.docker.com/) -- [Terraform](https://www.terraform.io/) - -Please see our [Tech Spec](/docs/Tech_Spec.md) for a full breakdown of the project and workflows. - -Please see our [Best Practices](/docs/Best_Practices.md) for code standards, git standards, and other guidance for writing clean and well -documented code. - -### Pull Request Process -1. Ensure you thoroughly fill out the pull request form presented when submitting the request. - This includes listing what work was done, what issues are resolved by that work, what tests - have been added, how to perform other tests or run the code, and other potentially relevant - notes. -2. Update the README.md with details of changes to the application, this includes new environment - variables, exposed ports, useful file locations and/or container parameters. -3. If you are on the project team you may merge the Pull Request in once you have the sign-off of one other developer, or if you - do not have permission to do that, you may request the second reviewer to merge it for you. - -## Contact -The best ways to get in touch with us is via Slack. An active Slack link can be found on our website: - -***[codeforbaltimore.org](https://codeforbaltimore.org/)*** - -You can also reach out to the tech lead [Jason Anton](https://github.com/revjtanton) via email at [jason@codeforbaltimore.org](mailto:jason@codeforbaltimore.org). - -## Sources and Links -We are also building a front-end application called [Healthcare Rollcall](https://github.com/CodeForBaltimore/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 +Bmore-Responsive is an Open Source project maintained by [CodeForBaltimore](https://codeforbaltimore.org). We welcome contributions to anyone that accepts the [project's license](./LICENSE) and abides by our [Code of Conduct](./docs/Code_of_Conduct.md). For more details, please refer to [How to Contribute](./docs/HowToContribute.md) in our project Wiki. diff --git a/README.md b/README.md index 65691680..dfa6aaea 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,26 @@ [![Build Status](https://travis-ci.org/CodeForBaltimore/Bmore-Responsive.svg?branch=master)](https://travis-ci.org/CodeForBaltimore/Bmore-Responsive) [![codecov](https://codecov.io/gh/CodeForBaltimore/Bmore-Responsive/branch/master/graph/badge.svg)](https://codecov.io/gh/CodeForBaltimore/Bmore-Responsive) # Bmore Responsive -An API to drive disaster and emergency response systems. +A simple, flexible API to support emergency response coordination. Sample use cases include: + +- keeping track of local nursing home status and needs during a global pandemic +- identifying hospitals lacking power during a natural disaster +- assuring safety of hikers in a national park during a snow storm + +Bmore-Responsive provides the following primary features via a secure REST API: + +- Maintain set of Entities (could be hospitals, nursing homes, campers, etc) +- Maintain set of Contacts for Entities (people who can provide status/need info for entities) +- Capture of status/need information about Entities +- User account and role management to enable secure authentication and authorization +- Export of any data via CSV + +<> + + + + +## --- Old README content below, Refactored version above ---- @@ -25,22 +44,7 @@ An API to drive disaster and emergency response systems. -## Documentation -Detailed documents describing this project and its use are available in this repository. The documentation currently available is as follows: -- [Best Practices](/docs/Best_Practices.md) -- [Code of Conduct](/docs/Code_of_Conduct.md) -- [Sequelize](/sequelize/README.md) -- [Tech Spec](/docs/Tech_Spec.md) -- [Terraform](/terraform/README.md) - -### 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](/sequelize/README.md) -### 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](/terraform/README.md) 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 :point_up: @@ -59,7 +63,7 @@ This application is designed to work as an API driven by Express. To setup your ``` npm install ``` -Once all dependencies are installed you will need to setup some environment variables to interact with your database and application. +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. @@ -77,11 +81,11 @@ The `DATABASE_URL` is not a very clear var name, and the string is broken down a 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. +- `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. +- `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 @@ -92,7 +96,7 @@ The various variables are defined as follows: _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: +**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` @@ -123,7 +127,7 @@ If you're running a database in another way then we trust you can sort it out on ### Sequelize To properly start the application the database needs to be built by Sequlize ahead of time. To do that run the following commands 1. You must create your database tables without running the application by running `npm run db-create` first. -2. _optional_ You can now seed your database if you wish by running `npm run db-seed`. +2. _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`. @@ -138,17 +142,17 @@ Note that `DATABASE_URL` host location will be different depending on what OS yo 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 PORT=3000 -e JWT_KEY= -e DATABASE_URL= -e DATABASE_DATABASE_SCHEMA= ``` ### docker-compose -To use the `docker-compose.yml` file included you will first need to set [environment variables](#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. +To use the `docker-compose.yml` file included you will first need to set [environment variables](#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. +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`. diff --git a/docs/Best_Practices.md b/docs/Best_Practices.md index 48436302..afb3d719 100644 --- a/docs/Best_Practices.md +++ b/docs/Best_Practices.md @@ -1,39 +1,8 @@ # Best Practices -Code for Baltimore projects should be built with the intention of deploying on [Heroku](https://heroku.com) or [AWS](https://aws.amazon.com/). For details on Heroku Best Practices see their [developer documentation](https://devcenter.heroku.com/articles/node-best-practices). +Here's an incomplete list of things that are inportant to consider when developing code to be controibuted to Bmore Responsive: - -- [Best Practices](#best-practices) - - [Project Management](#project-management) - - [Projects](#projects) - - [Issues and Milestones](#issues-and-milestones) - - [Tagging Issues](#tagging-issues) - - [Code Quality Standards](#code-quality-standards) - - [Style Guides](#style-guides) - - [Static Code Analysis](#static-code-analysis) - - [Git and Branching](#git-and-branching) - - [Branch Names](#branch-names) - - [Merging and Pull Requests](#merging-and-pull-requests) - - - -## Project Management - -We are using Github Issues to track outstanding issues and work for projects. - -### Projects - -Github Projects help organize our repositories by creating a Kanban board to track issues. These boards can be automatically generated by Github when creating the Project and should include a Todo, In Progress, Under Review, Reviewer Approved, and Done column. As issues are added to a Project they should be added to the board. A repo can have one or many Projects or boards at any given time. - -### Issues and Milestones - -When breaking down work it is important to add tasks to the Github project. For convenience various types of issues have templates built into this repo for easy issue entry. Before tasks are entered the project managers should agree on milestones based on the Project objectives. Issues should be tracked against Milestones so progress can be measured and planned for. - -### Tagging Issues - -When entering issues tagging can be used to further organize work or make work more visible to team members. - -## Code Quality Standards +### Code Quality Standards Regardless of Language: @@ -50,19 +19,19 @@ Consistent style guidelines for each language should be used. Where possible, op Example: Google has openly published style guides for many languages in wide use on their open source projects, and these can be adopted for use in this project: [Google Language Specific Styleguides](https://google.github.io/styleguide/) -## Static Code Analysis +### Static Code Analysis Static code analysis tools should be used when possible, to monitor and improve code quality. This may be integrated in the local development environment, automated repository commit checks, automated CI/CD pipelines, or other steps in the code development process. -## Git and Branching +### Git and Branching All code work should be done in an isolated or feature branch off of the `master` branch. Before starting work on new code, developers should create their feature branch using a standard naming convention determined by the project. ### Branch Names -Branch names should follow this patter: `/issue-`. This will ensure there are no branch name conflicts, and anyone looking for your branch will know what it is called based on the issue addressed. For example if your username was `letsGoOs`, and you were working on issue 8, then your branch name would be `letsGoOs/issue-8`. If you wanted to make a new branch to continue your work on your issue then add a suffix with an incremented number. To continue the previous example if you wanted to make a second branch for your issue 8 work your second branch would be called `letsGoOs/issue-8-2`. +Branch names should follow this pattern: `/issue-`. This will ensure there are no branch name conflicts, and anyone looking for your branch will know what it is called based on the issue addressed. For example if your username was `letsGoOs`, and you were working on issue 8, then your branch name would be `letsGoOs/issue-8`. If you wanted to make a new branch to continue your work on your issue then add a suffix with an incremented number. To continue the previous example if you wanted to make a second branch for your issue 8 work your second branch would be called `letsGoOs/issue-8-2`. ### Merging and Pull Requests When work is complete, and after static code analysis has been performed, the developer should submit a pull request in Github. A pull request template has been provided, and developers should take care to fill out the form as completely as possible when submitting new pull requests omitting any sections that are deemed unnecessary for that particular submission. Pull requests should require at least 1 review from another verified team member before they are approved and merged into the `master` branch. -While not strictly required, it is recommended that pull requests are submitted early on in the development process with the intention of maintaining high visibility over the work while it is in progress. +While not strictly required, it is recommended that pull requests are submitted early on in the development process with the intention of maintaining high visibility over the work while it is in progress. diff --git a/docs/DevIntro.md b/docs/DevIntro.md new file mode 100644 index 00000000..0288686d --- /dev/null +++ b/docs/DevIntro.md @@ -0,0 +1,57 @@ +Wanna improve Bmore Responsive? This page will provide an introduction the to the architecture, implementation and processes of Bmore Responsive. + + +## Components +This application will be broken down into several components. Each will be outlined here. + +### Application Architecture +The overall application will have several components in support of the code. These will facilitate secure communication between any front end, our API, and the data layer. Additionally our architecture will be designed to be scalable for instances of heavy load. +![Application Architecture](/img/architecture-diagram.png) + + +### API +The API is the application for all intents and purposes. Use of the API and possible paths of use are defined in the flowchart below. +![API Flowchart](/img/api-flowchart.png) + +### CI/CD +We will use TravisCI, Docker, Netlify, and AWS to provide constant code deployments and test coverage. +![CI/CD Pipeline](/img/cicd-pipeline.png) + +### Data +This product makes use of [PostgreSQL](https://www.postgresql.org/) for the data layer and [Sequelize](https://sequelize.org/) for database interactions. Our database documentation can be found in the `/sequelize` directory or you can [click here](/sequelize/README.md). The schema is outlined below +![Database Diagram](/img/db-diagram.png) + +#### Migrations +Migrations are the scripts to create tables and initialize the database. Migrations can be written to run after the initial migration takes place. + +It is important to note that the migrations run in sequential order, so using a numbering system is important. It is also important to note that FK columns and relationships can be ***and should be*** defined as their own migrations. This is to prevent errors of columns being created when the parent table no longer exists. + +Individual migrations _can_ be reverted as per the Sequelize documentation. + +#### Data Seeders +A seeder is a script to seed a particular set of data. As with Migrations these scripts run in order, so numbering is important. + +Because of FK constraints it is again important to note when data is seeded to prevent errors with FK constraints. Imports can be chained in a single seed script, and this may be useful and advised for seeded data that is related through a FK. + +To create new models, migrations, and seeders you _must_ use the Sequelize CLI commands. Full documentation is here https://sequelize.org/master/manual/migrations.html but here are a few useful commands: + +- `npx sequelize-cli model:generate --name User --attributes firstName:string,lastName:string,email:string` - Creates a model under `/src/models` and a migration script. +- `npx sequelize-cli seed:generate --name demo-user` - Creates a seeder for the `User` model and migration previously setup. + +#### NPM commands +This repo has simplified a few of the Sequelize CLI options that would be commonly used by this project. + +- `npm run db-create` will create the database and run all migrations. +- `npm run db-delete` will delete all tables and revert all migrations. +- `npm run db-seed` will run all seeders and populate all data. +- `npm run db-unseed` will delete all data in all tables and revert all seeders. + + +### Role and Access Mgmt +User role management is being handled by [Casbin](https://casbin.org/). To facilitate this our migrations and seeding will replicate the `casbin_rule` table that would be generated by the casbin-sequelize package. We are then seeding as normal, however the field names are not straight-forward. They are defined as follows: + +- `role` = The plain-text name of the role. _Example:_ `admin` +- `path` = The path the role has access to. _Example:_ `/user` +- `method` = The http method that can be hit. _Example_ `GET` + +For use and management of roles after seeding, please refer to the API spec or Casbin Node.js documentation. diff --git a/docs/HowToUse.md b/docs/HowToUse.md new file mode 100644 index 00000000..d19bd730 --- /dev/null +++ b/docs/HowToUse.md @@ -0,0 +1,32 @@ +Once you've installed the + + +## API Spec +The Bmore Responsive API is documented via a OAS 3.0 API spec in the `swagger.json` file. This API spec lists all the end points, supported REST actions, request parameters and response data formats. While you can open the `swagger.json` file in any text editor, there are better ways to view it in a richer format, such as: + +- View the [API Spec on Swaggerhub](https://app.swaggerhub.com/apis/codeforbaltimore/bmoreResponsive) +- If you are running Bmore Responsive, then you can just point your browser at the root URL of your server, often `http://localhost:3000/`, you'll be redirected to `http://localhost:3000/api-docs/`. + +## Postman Collection + +For a library (aka collection) of sample API calls, please refer to Postman the collection saved as `Bmore-Responsive.postman_collection.json`. Need Postman? Click [here](https://www.postman.com/downloads/). + + + +## Authentication + +The Bmore Responsive API provides security by limiting use of nearly all feature to authenticated users. If you have NOT disabled login, you'll need to pass a token (aka "JWT") with every call, except `/health` and `/user/login` endpoints. To get this token, you'll need to pass a valid username and password to `/user/login` which will reply with a JWT. This JWT should be passed as a query parameter named `token`. This token will expire after a short period of time. Once expired you can get a new token by another call to `user/login`. + +_Note: If you have used the db-seed script, you'll already have a user account created that will enable you to login. This default login is username `homer.simpson@sfpp.com` and password `donuts`._ + + + + +## Seed and re-seed the database + +This repo has four scripts that simplifies the creation and loading of the database. These script commands are as follows: + +- `npm run db-create` will create the database and run all migrations. +- `npm run db-delete` will delete all tables and revert all migrations. +- `npm run db-seed` will run all seeders and populate database with random, Simpsons-like data. +- `npm run db-unseed` will delete all data in all tables and revert all seeders. diff --git a/docs/QuickStart.md b/docs/QuickStart.md new file mode 100644 index 00000000..e04917bc --- /dev/null +++ b/docs/QuickStart.md @@ -0,0 +1,74 @@ +# Quick Start + +This brief guide will get you up and running your own copy of Bmore Responsive with sample data so you can get familiar with the solution by using it directly. The approach below is just one way to get Bmore Responsive running. For other approaches and more detail on configuration, please see the [Slow Start Guide](SlowStart.md) section of the Users' Guide. + + +## Step 0 - Download code from github +We're assuming that you've cloned or downloaded the contents of the [Bmore Responsive repository on GitHub](https://github.com/CodeForBaltimore/Bmore-Responsive). + +## Step 1 - Install Required Software +In order to follow this quick start guide you'll need to make sure you have the following software installed on your machine: + +- **Node.js** - You can confirm you have Node.js by executing `node -v` at a command line. If your machine replies with a version number like `13.8.0` then you have Node.js installed. If you need to install Node.js, head on over to [Nodejs.org](https://nodejs.org/). +- **Docker Desktop with DockerHub access** - Docker is not technically required to run BMore Responsive, but this guide uses Docker to get up and running quickly. You can confirm that you have Docker Desktop by executing `docker -v` at a command line. If your machine replies with a version number like `Docker version 19.03.8, build afaca4b` then you have Docker Desktop installed. If you need to install Docker Desktop, head on over to the [Docker Desktop page](https://www.docker.com/products/docker-desktop). + +## Step 2 - Install + +Open your terminal, change to your Bmore-Responsive directory (created in Step 0) then run `npm install` + +## Step 3 - Configure Your Environment + +You'll need to create a text file named `.env` in your Bmore-Responsive directory. This file set initial values of your environment variables. + +``` +NODE_ENV=development +PORT=3000 +JWT_KEY=test123 +DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres +DATABASE_SCHEMA=public +BYPASS_LOGIN=true +``` + +*Note: The DATABASE_URL above asserts that your username and password for your DB are both `postgres` as the URL format is generally `postgres://user:pass@example.com:5432/dbname`.* _We highly recommend_ *changing these values in this step and the following step.* + +## Step 4 - Start Up a Database + +Use Docker to start up a PostgreSQL database with the following command: +``` +docker run -d -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres +``` +*Note: If you changed your username or password in the previous step, you'll need to replace values in this command to match.* + +## Step 5 - Create and Seed Database + +In order to create the necessary database tables run `npm run db-create`. + +To populate the DB with sample users, entities and contacts that may resemble the fictional world of *The Simpsons* just run `npm run db-seed`. + +## Step 6 - Run Server + +To run the application run `npm start`. Your terminal output should end with a line like `Bmore Responsive is available at http://localhost:5000` + +## Step 7 - Confirm Success + +To confirm the server is running, just point your browser to [http://localhost:5000/entity](http://localhost:5000/entity) (or just add "/entity" to the URL from the previous step). A response like the sample below lets you know your server is healthy. + +``` +{ + "_meta": { + "total": 25 + }, + "results": [ + { + "id": "376fb5a1-d8fe-42ce-9492-cca41148ff1a", + "name": "The Leftorium", + "type": "Test", + "address": { + "street": [ + "123 Anyplace St." + ], + + ... +``` + +**Congratulations!** Why not check out the ["How to Use"](HowToUse.md) guide and learn more by using Bmore Responsive. diff --git a/docs/SlowStart.md b/docs/SlowStart.md new file mode 100644 index 00000000..0308d4d5 --- /dev/null +++ b/docs/SlowStart.md @@ -0,0 +1,51 @@ +If you want to tweak the installation of Bmore Responsive or have a different environment, then this page will provide additional detail on how to install/configure Bmore Responsive. + +## Configuring via Environment variables +Regardless of where you are running the system, environment variables to run this application. These variables are set in the `.env` file on the root directory of Bmore Responsive. + +The various variables are defined as follows: + +- `NODE_ENV` = The label for your environment. It can be anything you want and will allow you to differentiate multiple instances. +- `PORT` = The local port you wish to run on. Defaults to `3000`. +- `DATABASE_URL` = The URL string for your db connection. For example: `postgres://username:password@host:port/dbname` where `host` can be specified as a (sub)domain or IP address. +- `DATABASE_SCHEMA` = Your local database schema. Postgres default is `public`. +- `JWT_KEY` = A secret value to generate JSON Web Tokens (JWTs) 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 +- `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`. _Note: at the moment, login will be bypassed if this variable simply exists in the `.env` file. Even `BYPASS_LOGIN = false` will remove the need to login. To require login, simply remove mention of this variable from this file._ + +_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._ + +## Deploying to AWS + +If you want to deploy to AWS, we have included a `terraform` option. For more information on how to use this feature, please see the README in `/terraform`. + + + +## Running in 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](#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= +-e DATABASE_URL= +-e DATABASE_DATABASE_SCHEMA= +``` + +### docker-compose +To use the `docker-compose.yml` file included you will first need to set [environment variables](#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. + +**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` diff --git a/docs/TECH_SPEC.md b/docs/TECH_SPEC.md deleted file mode 100644 index c0e540a8..00000000 --- a/docs/TECH_SPEC.md +++ /dev/null @@ -1,85 +0,0 @@ -# Tech Spec -Bmore Responsive is a Contact and Response Management System (CRMS) and API. This document will describe the application in some detail. - - - -- [Tech Spec](#tech-spec) - - [Overview](#overview) - - [Scenarios](#scenarios) - - [COVID-19](#covid-19) - - [Automatic Checkin](#automatic-checkin) - - [Organized Response](#organized-response) - - [Non Goals](#non-goals) - - [Minimum Viable Product](#minimum-viable-product) - - [Components](#components) - - [API](#api) - - [CI/CD](#cicd) - - [Data](#data) - - [Application Architecture](#application-architecture) - - [Roadmap](#roadmap) - - [Contact Info](#contact-info) - - - -## Overview -This application will allow users to add and update contact information for individuals and entities. Additionally, the system will facilitate tracking of entity status and any other pertinent information. The data collected can be used by municipalities to organize response efforts in a disaster or crisis situation. - -## Scenarios -This application and API can be used in a few different ways. - -### COVID-19 -During the COVID-19 Pandemic the City of Baltimore needs a way to check-in with healthcare providers to ensure they have all of the supplies they need, if they have any patients sick with the virus, if anyone is in quarantine, etc. - -Many healthcare facilities have a few members on staff, however the contact information for those individuals may be out of date or the facility may have experienced some changeover since the last checkin. - -Using the API and a front-end, the City of Baltimore would be able to keep track of the facility's status via multipule contact points in an organized and efficient way. - -### Automatic Checkin -Facilities may not have time for phone calls, and the number of available city workers may not be sufficient to check in with all providers during an emergency. - -Using our API the providers can securely check-in using a web form on their own. One-time use logins can be sent on regular intervals to preferred contacts for each facility. This can allow contacts to update facility status on their own time without the need for city workers to contact them directly. - -### Organized Response -City workers and volunteers have a need to check in with facilities during the COVID-19 pandemic. The callers need to track who has called who and when, and track the overall trends in automatic updates. - -Using this API workers can login and see the status of the city at a glance, and they can prioritize their check-ins based on need and trend. - -## Non Goals -What will this project not accomplish? -- No front-end website or app -- No outside data interactions -- Non-city employee full login (dashboard, etc) -- Statistical or analytical endpoints - -## Minimum Viable Product -To use this product as quickly as possible we will be implementing the following features: -- User creation -- Contact creation -- Entity creation -- Contact->Entity linking -- Contact single-use login check-in ability - -## Components -This application will be broken down into several components. Each will be outlined here. - -### API -The API is the application for all intents and purposes. Use of the API and possible paths of use are defined in the flowchart below. -![API Flowchart](/docs/img/api-flowchart.png) - -### CI/CD -We will use TravisCI, Docker, Netlify, and AWS to provide constant code deployments and test coverage. -![CI/CD Pipeline](/docs/img/cicd-pipeline.png) - -### Data -This product makes use of [PostgreSQL](https://www.postgresql.org/) for the data layer and [Sequelize](https://sequelize.org/) for database interactions. The schema is outlined below -![Database Diagram](/docs/img/db-diagram.png) - -### Application Architecture -The overall application will have several components in support of the code. These will facilitate secure communication between any front end, our API, and the data layer. Additionally our architecture will be designed to be scalable for instances of heavy load. -![Application Architecture](/docs/img/architecture-diagram.png) - -## Roadmap -We estimate the API will be at v1.0.0 by the end of March. - -## Contact Info -Give as much, or as little, info as you want here. \ No newline at end of file diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 00000000..6a6fb30d --- /dev/null +++ b/docs/about.md @@ -0,0 +1,92 @@ +# About Bmore Responsive + +Here some more info about this project. + +## What is Bmore Responsive? + +A simple, flexible API to support emergency response coordination. Sample use cases include: + +- keeping track of local nursing home status and needs during a global pandemic +- identifying hospitals lacking power during a natural disaster +- assuring safety of hikers in a national park during a snow storm + +This system will make use of digital services and modern methodologies to automate and simplify parts of the check-in process +to help the municipality prioritize its call/check-in list and response plan. Additionally, the system will validate contact +information regularly during non-emergency times to ensure the municipality has the most up-to-date information for each entity. + + +## What Bmore Responsive Isn't? + +In order to stay focus on its primary goals, Bmore Responsive is **not** intended to: + +- Be a front-end website or app +- Provide statistical or analytical endpoints +- Be a robust questionnaire design tool + +## Roadmap + +The project team uses a [User Story Map](https://www.jpattonassociates.com/user-story-mapping/) to identify feature planned for future development. Here's our latest story map: + +![StoryMap](https://app.lucidchart.com/publicSegments/view/284f3228-4d57-476d-b00c-f6b8cbfa74f4/image.jpeg) +

Bmore Responsive User Story Map

+ +## Current Work + +We use GitHub issues to define and manage our work. The [list of open issues](https://github.com/CodeForBaltimore/Bmore-Responsive/issues) describes the work that is currently on our plate. [GitHub milestones](https://github.com/CodeForBaltimore/Bmore-Responsive/milestones) are occasionally used to represent features from the story map. Often several issues (user stories, bugs, tasks, etc) will be related to one feature. By relating these issues to a milestone, it makes it easy to view/track progress toward features on the story map. + +## Technology and Code + +This project will make exclusive use of open-source software, packages, and contributions. The application is built with the following +technologies: + +- Javascript (ES6) +- [Node.js](https://nodejs.org/en/) +- [Express.js](https://expressjs.com/) +- [Sequelize](https://sequelize.org/v3/) +- [Docker](https://www.docker.com/) +- [Terraform](https://www.terraform.io/) + +Please see our [Developer Intro](DevIntro.md) for a full breakdown of the project and workflows. + +Please see our [Best Practices](Best_Practices.md) for code standards, git standards, and other guidance for writing clean and well +documented code. + +## Contributing +When contributing to this repository, please first discuss the change you wish to make via issue, +email, slack, or any other method with the contributes of this repository, or Code for Baltimore, before making a change. + +Please note we have a [Code of Conduct](Code_of_Conduct.md), please follow it in all your interactions with the project. + +## Definition of Done + +Before any issue can be considered done and marked resolved, the following conditions must be met: + +- All Acceptance criteria listed in the issue are fulfilled +- The Postman collection on the branch passes all tests +- The Swagger doc completely and accurately aligns with the implementation of the API +- All documentation, especially wiki pages in `/docs/*.md`, aligns with updated code/solution +- All unit tests pass +- Unit test coverage, as measured by Codecov, is 80% +- No medium or major security vulnerabilities + +## Pull Request Process +1. Ensure you thoroughly fill out the pull request form presented when submitting the request. + This includes listing what work was done, what issues are resolved by that work, what tests + have been added, how to perform other tests or run the code, and other potentially relevant + notes. +2. Make sure that all elements of the *Definition of Done* (above) are met. Feel free to ask for help if needed. +3. If you are on the project team you may merge the Pull Request in once you have the sign-off of one other developer, or if you + do not have permission to do that, you may request the second reviewer to merge it for you. + +## Contact Us +The best ways to get in touch with us is via Slack. An active Slack link can be found on our website: + +***[codeforbaltimore.org](https://codeforbaltimore.org/)*** + +You can also reach out to the tech lead [Jason Anton](https://github.com/revjtanton) via email at [jason@codeforbaltimore.org](mailto:jason@codeforbaltimore.org). + +CodeForBaltimore welcomes anyone who is interested in helping with this project. You do not have to be an expert developer or located anywhere near Baltimore. Hit us up on Slack and let's talk. + +## Sources and Links +We are also building a front-end application called [Healthcare Rollcall](https://github.com/CodeForBaltimore/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 diff --git a/docs/img/favicon.ico b/docs/img/favicon.ico new file mode 100644 index 00000000..eb8b4976 Binary files /dev/null and b/docs/img/favicon.ico differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..20a9098b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,37 @@ +# Bmore-Responsive Wiki Home + +## What is Bmore-Responsive? + +A simple, flexible API to support emergency response coordination. Sample use cases include: + +- keeping track of local nursing home status and needs during a global pandemic +- identifying hospitals lacking power during a natural disaster +- assuring safety of hikers in a national park during a snow storm + +This system will make use of digital services and modern methodologies to automate and simplify parts of the check-in process +to help the municipality prioritize its call/check-in list and response plan. Additionally, the system will validate contact +information regularly during non-emergency times to ensure the municipality has the most up-to-date information for each entity. + +## What does it do? + +Bmore-Responsive provides the following primary features via a secure REST API: + +- Maintain set of Entities (could be hospitals, nursing homes, campers, etc) +- Maintain set of Contacts for Entities (people who can provide status/need info for entities) +- Capture of status/need information about Entities +- User account and role management to enable secure authentication and authorization +- Export of any data via CSV + +## How do I use it? + +You can begin using Bmore-Responsive in minutes by following our the steps in the [Quick Start Guide](QuickStart.md). If you have more advanced installation/configuration needs take a look at out [Slow Start Guide](SlowStart.md). + +Once you've installed the app, check out the [How To Use Guide](HowToUse.md) to understand the use the API directly or integrate a front end application. + +## How is it built? Can I contribute? + +Bmore-Responsive is an Open Source project developed mostly in node.js. You are welcome to fork the repo to customize for your own needs, but we'd welcome contributions to improve Bmore Responsive directly. + +For more technical detail on the solution and guidance on contributing, please see our [Developers' Guide](DevIntro.md). + +Maintained by [CodeForBaltimore](https://codeforbaltimore.org/) and supported by [CodeForAmerica](https://codeforamerica.org/) diff --git a/mkdocs.yml b/mkdocs.yml index 0131c82e..6e4bec53 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,17 @@ -site_name: Project Template -theme: +site_name: Bmore-Responsive Wiki + +nav: + - 'Home': 'index.md' + - 'For Users': + - 'Quick Start - Less than 10 min': 'QuickStart.md' + - 'Slow Start - Advanced Config': 'SlowStart.md' + - 'Users Guide': 'HowToUse.md' + - 'For Developers': + - 'Developer Overview': 'DevIntro.md' + - 'Best Practices': 'Best_Practices.md' + - 'For Everyone': + - 'About Bmore Responsive': 'about.md' + - 'Code of Conduct': 'Code_of_Conduct.md' + +theme: name: readthedocs -plugins: - - swagger -extra: - swagger_url: 'https://raw.githubusercontent.com/CodeForBaltimore/Bmore-Responsive/master/swagger.json' \ No newline at end of file diff --git a/sequelize/README.md b/sequelize/README.md index 9589e2fe..22b93070 100644 --- a/sequelize/README.md +++ b/sequelize/README.md @@ -1,34 +1,2 @@ # Sequelize -This directory contains scripts and config options to seed the database with dummy data. For information and documentation about Sequelize please see their official website https://sequelize.org/ - -## Migrations -Migrations are the scripts to create tables and initialize the database. Migrations can be written to run after the initial migration takes place. - -It is important to note that the migrations run in sequential order, so using a numbering system is important. It is also important to note that FK columns and relationships can be ***and should be*** defined as their own migrations. This is to prevent errors of columns being created when the parent table no longer exists. - -Individual migrations _can_ be reverted as per the Sequelize documentation. - -## Seeders -A seeder is a script to seed a particular set of data. As with Migrations these scripts run in order, so numbering is important. - -Because of FK constraints it is again important to note when data is seeded to prevent errors with FK constraints. Imports can be chained in a single seed script, and this may be useful and advised for seeded data that is related through a FK. - -## NPM commands -This repo has simplified a few of the Sequelize CLI options that would be commonly used by this project. -- `npm run db-create` will create the database and run all migrations. -- `npm run db-delete` will delete all tables and revert all migrations. -- `npm run db-seed` will run all seeders and populate all data. -- `npm run db-unseed` will delete all data in all tables and revert all seeders. - -# Casbin -User role management is being handled by [Casbin](https://casbin.org/). To facilitate this our migrations and seeding will replicate the `casbin_rule` table that would be generated by the casbin-sequelize package. We are then seeding as normal, however the field names are not straight-forward. They are defined as follows: -- `role` = The plain-text name of the role. _Example:_ `admin` -- `path` = The path the role has access to. _Example:_ `/user` -- `method` = The http method that can be hit. _Example_ `GET` - -For use and management of roles after seeding, please refer to the API spec or Casbin Node.js documentation. - -# Links and more information -To create new models, migrations, and seeders you _must_ use the Sequelize CLI commands. Full documentation is here https://sequelize.org/master/manual/migrations.html but here are a few useful commands: -- `npx sequelize-cli model:generate --name User --attributes firstName:string,lastName:string,email:string` - Creates a model under `/src/models` and a migration script. -- `npx sequelize-cli seed:generate --name demo-user` - Creates a seeder for the `User` model and migration previously setup. \ No newline at end of file +This directory contains scripts and config options to seed the database with dummy data. For more information about how Bmore-Responsive uses Sequelize, please see the project wiki. <>. For information and documentation about Sequelize please see their official website https://sequelize.org/