Skip to content

Latest commit

 

History

History
250 lines (166 loc) · 9.58 KB

CONTRIBUTING.md

File metadata and controls

250 lines (166 loc) · 9.58 KB
Raw

Contributing

For Developers

Setup

Using GitHub Codespaces

GitHub Codespaces is enabled for this repository for everyone who is a member of the organization or acknowledged as an invited "Outside Collaborator".

You can learn more about using Codespaces from the official GitHub documentation.

ℹ️ When using the Codespaces environment, you should be provided all of the environment variables necessary to get up and running. However, if you find that any of them are not working as expected (please let us know!), you may need to manually update some of them via directions in the Configuration section below.

Using a Docker environment

We recommend using VS Code with the Microsoft "Remote Development" extension pack to quickly spin up a full-featured development environment using Docker on your local system:

  1. Follow the installation guide
  2. Then either:

⚠️ If you use the Docker environment, you will still need to configure a handful of environment variables that are described in the Configuration section below.

Using your local system

Prerequisites

If you are using a MacOS or Linux system, you can setup all of the prerequisites by running one convenient script:

script/bootstrap
Linux prerequisites

Here are some steps you can follow to install the prerequisites on RHEL, CentOS or Fedora Linux.

First, reset and install a more recent version of Node.js like version 16.

sudo yum module reset -y nodejs
sudo yum module install -y nodejs:16

Next, install the Node.js and Node.js Package Manager packages.

pkcon install -y nodejs
Node.js & npm

Ensure a modern version of Node.js (and npm) are installed.

Currently used versions in production:

  • Node.js @ 14.x
  • npm @ 6.x
PostgreSQL server

Ensure a PostgreSQL server is installed and running.

Currently used version in production:

  • PostgreSQL @ 13.x
Getting Started

  1. Clone the repository.

  2. If you are using a MacOS or Linux system, you can setup all of the prerequisites by running one convenient script:

script/bootstrap

If you can successfully run that script, you may skip ahead to Step 5.

Linux PostgreSQL server

Here are some steps you can follow to install the PostgreSQL relational database on RHEL, CentOS or Fedora Linux.

pkcon install -y postgresql-server
  1. Install the dependencies. From a terminal, navigate to the project's root directory and run:
npm install

ℹ️ This should should not be necessary if you successfully ran script/bootstrap.

  1. Create and seed the local PostgreSQL databases:
npm run db:create

followed by

npm run db:seed

ℹ️ This should should not be necessary if you successfully ran script/bootstrap.

  1. Ensure you have configured your environment.

  2. Run the tests to ensure everything is working as expected:

npm test
  1. Start the server:
# Simple approach
npm run dev

Configuration

Using the Google Civic Information API locally

  1. Using your preferred Google account, head to the Google API Console's Credentials page to create a new Project and API key. If you need a bit more guidance, refer to Google's guide.
  2. Hit the following URL, substituting your own API key in:
https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>

Chances are likely that you will receive a 403 response with an error message in the JSON response body explaining that you must enable the Google Civic Information API for your new Project. It will also provide a URL to visit to do just that (enable it), so please navigate to that. For reference, its format will be similar to:

https://console.developers.google.com/apis/api/civicinfo.googleapis.com/overview?project=<YOUR_PROJECT_ID>
  1. On the resulting page, click the "Enable" button.
  2. Revisit the URL from the earlier step, substituting your own API key in:
https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>

This time around, you should succeed with a JSON response body containing an elections array.

  1. Create a file called .env in the project's root directory, preferrably using the .env.example file as your template.
  2. Add a new key-value pair to the file containing your new API key, e.g.
# API key for the Google Civic API
CIVIC_API_KEY=<YOUR_API_KEY>
  1. Save the changes to the .env file.

Using the Lob API locally

  1. Login to your personal Heroku dashboard.
  2. Switch to the programequity team under the project dropdown (which probably defaulted to Personal).
  • ℹ️ If you do not see that team, you probably need to be added by a project administrator.
  1. Go into the backend application, currently named murmuring-headland-63935.
  2. Go into the "Settings" tab.
  3. In the "Config Vars" section, click the "Reveal Config Vars" button to expand the list of existing environment variables.
  4. Find the LOB_API_KEY and TEST_LOB_API_KEY variables.
  5. Create a file called .env in the project's root directory, preferrably using the .env.example file as your template.
  6. Add a set of new key-value pairs to the file containing the API keys with the values from the Heroku application, e.g.
# Production environment API key for the Lob API
LOB_API_KEY=<HEROKU_VARIABLE>

# Test environment API key for the Lob API
# This is only required for running the integration tests successfully!
TEST_LOB_API_KEY=<HEROKU_VARIABLE>
  1. Save the changes to the .env file.

Ignoring the Auth0 authentication locally

Although the authentication check is not required locally, the module in use still expects certain values to be passed in regardless of their validity.

  1. Create a file called .env in the project's root directory, preferrably using the .env.example file as your template.
  2. Add set of a new key-value pairs to the file with literal nonsense values, e.g.
SERVER_PORT=8080
CLIENT_ORIGIN_URL=http://localhost:8080
AUTH0_AUDIENCE=your_Auth0_identifier_value
AUTH0_DOMAIN=your_Auth0_domain
  1. Save the changes to the .env file.

Setting up Auth0 authentication locally

  1. Follow the steps for Ignoring the Auth0 authentication locally for configuring the .env file.
  2. Create a file called .env in the project's root directory, preferrably using the .env.example file as your template.
  3. Add set of a new key-value pairs to the file with literal nonsense values, e.g.
SERVER_PORT=8080
CLIENT_ORIGIN_URL=http://localhost:8080
AUTH0_AUDIENCE=
AUTH0_DOMAIN=
  1. Save the changes to the .env file.

The following instructions can also be found in this guide

  1. Sign up for an account at Auth0.
  2. Select personal when prompted with the type of account being created.
  3. Go to API dashboard and click Create API button.
  4. Add a Name to your API. It can be named anything you'd like.
  5. Set the Identifier value. http://localhost:8080/ is recommended. For more information see this guide
  6. Set AUTH0_AUDIENCE=http://localhost:8080/ or another Identifier value from the step above.
  7. Click on the "Test" tab.
  8. Locate the section called " Asking Auth0 for tokens from my application".
  9. Click on the cURL tab to show a mock POST request.
  10. Copy your Auth0 domain, which is part of the --url parameter value: tenant-name.region.auth0.com. For more information see this guide
  11. In .env, set AUTH0_DOMAIN value equal to domain value from step above.

Connecting to the production PostgreSQL database locally

⚠️ For trusted collaborators ONLY! ⚠️

  1. Using your authorized Heroku account, you can find the DATABASE_URL Config Var on our deployed Heroku app's "Settings" page.

  2. Create a file called .env in the project's root directory, preferrably using the .env.example file as your template.

  3. Add a new key-value pair to the file containing the Heroku DATABASE_URL value, e.g.

# PostgreSQL database connection string for production
DATABASE_URL=<OUR_HEROKU_DATABASE_URL>
  1. Save the changes to the .env file.
  2. When starting your local server, you must set your NODE_ENV environment variable to "production" in order for knex to connect to this Heroku production database, e.g.
NODE_ENV=production npm start