Skip to content

Latest commit

 

History

History
110 lines (65 loc) · 5.97 KB

development.md

File metadata and controls

110 lines (65 loc) · 5.97 KB
Raw

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.

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

  1. 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

OpenSearch setup

  1. Run make init-opensearch setup the OpenSearch Container
  2. 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

Run the application

  1. Make sure you have Docker Desktop installed & running.
  2. Run make setup-local to install dependencies
  3. Run make init start to build the image and start the container.
  4. Navigate to localhost:8080/docs to access the Swagger UI.
  5. Run make run-logs to see the logs of the running API container
  6. Run make stop when you are done to delete the container.

Some Useful Commands

make test will run all of the tests. Additional arguments can be passed to this command which will be passed to pytest like so: make test args="tests/api/route -v" which would run all tests in the route folder with verbosity increased. See the Pytest Docs for more details on CLI flags you can set.

make clean-volumes will spin down the docker containers + delete the volumes.

make volume-recreate Deletes the volumes and then re-initializes the persistant portions of the stack. This can be useful to reset your DB, or fix any bad states your local environment may have gotten into.

See the Makefile for a full list of commands you can run.

The make console command initializes a Python REPL environment pre-configured with database connectivity. This allows developers to perform database queries, utilize factories for data generation, and interact with the application's models directly.

  • Writing a query: dbs.query(Opportunity).all()
  • Saving some factory generated data to the db: f.OpportunityFactory.create()

Docker and Native Development

Several components like tests, linting, and scripts can be run either inside of the Docker container, or outside on your native machine. Running in Docker is the default, but on some machines like the M1 Mac, running natively may be desirable for performance reasons.

You can switch which way many of these components are run by setting the PY_RUN_APPROACH env variable in your terminal.

  • export PY_RUN_APPROACH=local will run these components natively
  • export PY_RUN_APPROACH=docker will run these within Docker

Note that 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.

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.

Authentication

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.

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

Next steps

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