Skip to content

Latest commit

 

History

History
129 lines (76 loc) · 6.4 KB

development.md

File metadata and controls

129 lines (76 loc) · 6.4 KB

Development

This application is dockerized. Take a look at Dockerfile to see how it works.

A very simple docker-compose.yml has been included to support local development and deployment.

Several components like tests, linting, and scripts can be run either inside of the Docker container, or outside on your machine.

Running in Docker is the default, but on some machines like the M1 Mac, running natively may be desirable for performance reasons.

Docker

This section covers development using Docker. There are a number of Docker commands included in the Makefile which are helpful for local development. Run make help for a list of commands.

Setup

Run make init && make run logs to start the local containers. The application will be available at http://localhost:8080 and API documentation at http://localhost:8080/docs.

This stands up the following services:

Seed data

Run make db-seed-local && populate-search-opportunities to create local data in the database and make it available in the API.

API Authenticaion

This API uses a very simple ApiKey authentication approach which requires the caller to provide a static key. This is specified with the API_AUTH_TOKEN environment variable.

User Authentication

Run make setup-env-override-file to create the override.env file which will include the necessary JWT keys for running user authentication within the app.

Mock Oauth2 Server

A mock Oauth2 server is defined and managed in the API's docker-compose.yml file. It creates a mock endpoint that is configured to work with the API to stand in for login.gov for local development, and is available at http://localhost:5001 when running the API containers.

Environment Variables

Most configuration options are managed by environment variables.

Environment variables for local development are stored in the local.env file. This file is automatically loaded when running. If running within Docker, this file is specified as an env_file in the docker-compose file, and loaded by a script automatically when running most other components outside the container.

Any environment variables specified directly in the docker-compose file will take precedent over those specified in the local.env file.

Troubleshooting

Errors in standing up the API can originate from an out of date container, database syncronization, or other issues with previously created services. Helper functions are available to rebuild:

  • db-check-migrations - check if migrations are out of sync
  • volume-recreate - delete all existing volumes and data
  • remake-backend - delete all data (volume-recreate) and load data (db-seed-local and populate-search-opportunities)

VSCode Remote Attach Container Debugging

The API can be run in debug mode that allows for remote attach debugging (currently only supported from VSCode) to the container.

  • Requirements:

    • VSCode Python extension
    • Updated Poetry with the debugpy dev package in pyproject.toml

  • See ./vscode/launch.json which has the debug config. (Named API Remote Attach)

  • Start the server in debug mode via make start-debug or make start-debug run-logs.

    • This will start the main-app service with port 5678 exposed.

  • The server will start in waiting mode, waiting for you to attach the debugger (see /src/app.py) before continuing to run.

  • Go to your VSCode debugger window and run the API Remote Attach option

  • You should now be able to hit set breakpoints throughout the API

Local (non-Docker)

Run export PY_RUN_APPROACH=local to run API and test functions locally when running commands in the Makefile. For example, make test or make format will run outside of Docker.

Note: even with the native mode, many components like the DB and API will only ever run in Docker, and you should always make sure that any implementations work within Docker.

Running in the native/local approach may require additional packages to be installed on your machine to get working.

Prerequisites

  1. Install the version of Python specified in pyproject.toml pyenv is one popular option for installing Python, or asdf.

    • If using pyenv run pyenv local <version> to ensure that version will be used in subsequent steps

  2. Ensure that python -V and python3 -V are picking up that version.

    • If not, run pyenv init - and/or restart your shell to ensure it was run automatically

  3. After installing and activating the right version of Python, install poetry and follow the instructions to add poetry to your path if necessary.

    curl -sSL https://install.python-poetry.org | python3 -

  4. You'll also need Docker Desktop

Note: All the following commands should be run from the /api directory.

Database setup: Run Migrations/Seeds

If you haven't done local development before you'll need to execute the migrations and seed the DB with data using the steps in database-local-usage.md

Services

Individual services can be run through Docker, which can be useful in concert with non-Docker application development:

  • OpenSearch

    • Run make init-opensearch setup the OpenSearch Container
    • Run make populate-search-opportunities to push data previously seeded in the DB into the search index

    If your DB or OpenSearch end up in an odd place, you can reset all the persistent storage using make volume-recreate.

  • Localstack (local s3)

    • Run make init-localstack

  • Mock OAuth server

    • Run make init-mock-oauth2

Next steps

Now that you're up and running, read the application docs to familiarize yourself with the application.