Installation

Install all dependencies in a VSCode Dev Container

If you use VSCode with Docker to develop in a container, the following VSCode Dev Container configuration will install all dependencies:

{
    "name": "Python 3",
    "image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
    "postCreateCommand": "sudo apt update && sudo apt install -y python3-dev libpq-dev graphviz && pipx install poetry && poetry install && poetry shell",
    "features": {
        "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
        "ghcr.io/rocker-org/devcontainer-features/quarto-cli:1": {}
    }
}

Simply create a .devcontainer folder in the root of the project and add a devcontainer.json file in the folder with the above content. VSCode may prompt you to install the Dev Container extension if you haven’t already, and/or to open the project in a container. If not, you can manually select “Dev Containers: Reopen in Container” from View > Command Palette.

Install development dependencies manually

Python and Docker

• Python 3.12 or higher
• Docker and Docker Compose

PostgreSQL headers

For Ubuntu/Debian:

sudo apt update && sudo apt install -y python3-dev libpq-dev

For macOS:

brew install postgresql

For Windows:

• No installation required

Python dependencies

1. Install Poetry

pipx install poetry

2. Install project dependencies

poetry install

3. Activate shell

poetry shell

(Note: You will need to activate the shell every time you open a new terminal session. Alternatively, you can use the poetry run prefix before other commands to run them without activating the shell.)

Install documentation dependencies manually

Quarto CLI

To render the project documentation, you will need to download and install the Quarto CLI for your operating system.

Graphviz

Architecture diagrams in the documentation are rendered with Graphviz.

For macOS:

brew install graphviz

For Ubuntu/Debian:

sudo apt update && sudo apt install -y graphviz

For Windows:

• Download and install from Graphviz.org

Set environment variables

Copy .env.example to .env with cp .env.example .env.

Generate a 256 bit secret key with openssl rand -base64 32 and paste it into the .env file.

Set your desired database name, username, and password in the .env file.

To use password recovery, register a Resend account, verify a domain, get an API key, and paste the API key into the .env file.

Start development database

docker compose up -d

Run the development server

Make sure the development database is running and tables and default permissions/roles are created first.

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Navigate to http://localhost:8000/

Lint types with mypy

mypy .