Skip to content

Latest commit

 

History

History
108 lines (73 loc) · 5.51 KB

CONTRIBUTING.md

File metadata and controls

108 lines (73 loc) · 5.51 KB
Raw

Contributing

We want to invite the developer community to contribute to our mission of promoting a culture of evidence-based and transparent policymaking. Please read the following instructions to start contributing to this project.

Installation

0. Clone this repository

git clone git@github.com:bayesimpact/encompass.git

1. Install Docker

Download and install Docker Community Edition (link).

2. Setup environment variables

In this project's root folder, add a file called .env with the following info (replacing ??? with real values):

MAPBOX_TOKEN=???
POSTGRES_URL=???
API_ROOT=http://localhost:8080
ENV=LOCAL
IS_AWS=FALSE
  • MAPBOX_TOKEN: API key provided by Mapbox for mapping.
  • POSTGRES_URL: URL for database used by the application. This might be localhost for development.

To use with an AWS RDS instance, the additional environment variables AWS_ACCESS_KEY and AWS_SECRET_KEY are required for using the AWS CLI. In addition, IS_AWS should be set to TRUE. This variable helps to initialize the database correctly when using an RDS instance. You will not need this environment variable if you are not using an RDS database.

All data required to initialize an RDS instance can be found in this S3 bucket.

3. Run the app

In your terminal, run:

docker-compose -f docker-compose.yml -f docker-compose.local.yml up backend frontend

Local Development

Three Docker containers are available for development:

  • Frontend: React/TypeScript app to fetch and visualize network adequacies.
  • Backend: Flask/uWSGI/Nginx-powered REST API to geocode providers and compute network adequacies.
  • Explorer: A container running Jupyter notebooks for easy exploration and model testing.
  • DB: A container running a Postgres server with the relevant GIS extensions.

Backend

docker-compose up backend
  • The API will then be accessible at localhost:8080
  • It provides the following REST routes (we document each route with its corresponding JSON-Schema definitions):
Method Route Request schema Response schema Description
GET /api/available-service-areas/ (none) Schema Fetches and returns all available service areas
POST /api/providers/ Schema Schema Geocodes, saves to the database, and returns (or, reads from the database if already defined) the given providers
POST /api/representative_points/ Schema Schema Computes representative points for the given service areas
POST /api/adequacies/ Schema Schema Computes adequacies for the given service areas against the given providers

Frontend

docker-compose -f docker-compose.yml -f docker-compose.local.yml up frontend

See frontend/README.md for more documentation.

Read more on how to contribute to the frontend

DB

docker-compose up db

This container will allow you to run a fully functioning local system with a POSTGRES_URL at db.local.

The database will be initialized but won't contain any data. There is some sample data for Los Angeles county included in this repository in the data/sample directory as well as a script to initialize the database and load the sample data. Simply run:

make initialize-local-db

Deploy

To pull the latest version and refresh the dockers, simply run make deploy in the main directory.

Remote Deployment

A sample Terraform configuration is provided in the /terraform directory. Further information is available here.

Sample CircleCI configuration is provided in the /.circleci directory. The default configurations are set up to run all tests and coverage on any branch and to update remote environments on specific branches. You can modify this configuration to match your own remote environment schema.

To use these CircleCI jobs for deployment, you'll need to set up keys in CircleCI to allow SSH access to your application servers. You'll also need to set the relevant environment variables up containing the DNS names for your application servers.

Remote Environment Overrides (SSL)

To enforce HTTPS on remote environments (by redirecting HTTP requests) you can use the remote override docker-compose file. This will run an Nginx server inside the frontend container to act as reverse proxy, which uses the ROOT_DOMAIN environment variable to determine where to redirect to.

Sample usage:

docker-compose -f docker-compose.yml -f docker-compose.remote.yml up -d frontend backend