Skip to content

Developer Setup Guide

Prerequisites

  • Python3.12+
  • docker + docker compose
  • pre-commit

1. Setup your python virtual environment

You can use either uv or something like venv or pip.

uv sync

This will create a virtual environment at the root of the repo and install all dependencies and the package (with all code in the src folder installed in "editable" mode).

Using pip and venv

python3 -m venv .venv
source .venv/bin/activate
# The `-e .` flag installs the package in "editable" mode.
pip install -e .

Available commands

You can now run the cli tool and webAPI/server with the following commands.

divbase-cli
divbase-api # NOTE: We typically do not run the API like this, instead we use docker compose, keep reading below to see how.

2. Install pre-commit hooks

We also use pre-commit hooks. pre-commit runs on every commit.

pre-commit install

If you ever need to skip a hook for a specific commit you can use:

git commit --no-verify

Or consider updating the hook config inside .pre-commit-config.yaml.

We have a GH action that checks that all pre-commit hooks pass on every PR and commit to main.

3. CLI Setup

divbase-cli relies on 2 local files to preserve state between runs:

  1. A config file stored in your home directory at ~/.config/divbase/config.yaml. This config contains information about your DivBase projects and which divbase server (if any) you're logged into.
  2. A secrets file stored in your home directory at ~/.config/divbase/.secrets. This file contains your access/refresh tokens for the DivBase server you're logged into.

You can read the user guides for more information on how to setup the CLI tool for the first time use.

For convenience, we provide a local development setup script, but in order to run this you need the docker compose stack running (see next section).

Local development environment variable

To make local development easier when working on divbase-cli, you may want to set the environment variable: 

export DIVBASE_DEV=true
This will configure logging and set the cli to interact with the local docker compose instance of the divbase api (aka localhost:8000/api). This logic is handled by divbase_cli/cli_config.py. Look in there if you want more specific control over things like logging level etc... via environment variables.

4. Run DivBase server locally using docker compose watch

docker compose -f docker/divbase_compose.yaml down && docker compose -f docker/divbase_compose.yaml watch

This will deploy the API, job system and a MinIO (S3) instance locally. Using compose watch means changes in the /src folder will automatically be synced to the container and if needed trigger a restart or rebuild of them.

Once the backend is up and running you can then run divbase-cli commands against it or go to for example http://localhost:8000/api/v1/docs to test out some of API commands directly.

Login will not work on Safari/webkit browsers in local development

Webkit (browser Safari is based on) does not like setting a HTTP-only cookie as "secure" when using HTTP instead of HTTPS. In local dev when you connect to (http://)localhost you have a HTTP connection, so it refuses to set the cookie(s). The cookies being stored are the access + refresh token of the user.

Safari works fine for end users connecting to a deployed instance, as that will be via HTTPS.

We could add some logic along the lines of: if in local dev/test env; set cookie to not be secure, but for now, just easier to say use a diff browser for local dev.

The DivBase frontend is running on http://localhost:8000. The frontend is part of the FastAPI app deployment. All API routes are appended with /api/v1 to avoid collisions. The frontend uses Jinja2 templating.

5. Local development setup script

To help with setup, we provide a local development setup script which will:

  • Create users and projects on your locally running DivBase instance and add users with different roles to each project.
  • create a user config file with these projects added to it.
  • Upload some initial data to the different projects (sample metadata files and VCFs).

You can run the local_dev_setup script like this:

uv run scripts/local_dev_setup.py # make sure the compose stack is running

6. Extras

If using vscode you may want to consider some/all of the following for your .vscode/settings.json:

{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    },
    "editor.defaultFormatter": "charliermarsh.ruff"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[css]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "python.analysis.autoImportCompletions": true,
  "python.testing.unittestEnabled": false,
  "python.testing.pytestEnabled": true
}