Development¶

Our development process is focused on high quality and development comfort. We use tools that are proven to be the best in class.

There are two possible ways to develop your apps.

local development
development inside docker

You can choose one or use both at the same time. How to choose what method should you use?

Local development is much easier and much faster. You can choose it if you don’t have too many infrastructure dependencies. That’s a default option for the new projects.

Choosing docker development means that you already have a complex setup of different technologies, containers, networks, etc. This is a default option for older and more complicated projects.

Dependencies¶

We use uv to manage dependencies. So, please do not use virtualenv or pip directly. Before going any further, please, take a moment to read the official documentation about uv to know some basics.

If you are using docker then prepend docker compose run --rm web before any of those commands to execute them.

Please, note that you don’t need almost all of them with docker. You can just skip this sub-section completely. Go right to Development with docker.

Installing dependencies¶

You do not need to run any of these commands for docker based development, since it is already executed inside Dockerfile.

Please, note that uv will automatically create a .venv for this project. It will use your current python version. To install all existing dependencies run:

uv sync

To install dependencies for production use, you will need to run:

uv sync --no-dev

To install all dependencies, including docs:

uv sync --group docs

And to activate virtualenv created by uv run:

. .venv/bin/activate

Adding new dependencies¶

To add a new dependency you can run:

uv add django to install django as a production dependency
uv add --group dev pytest to install pytest as a development dependency
uv add --group docs some-sphinx-plugin to install some-sphinx-plugin as a documentation dependency

This command might be used with docker.

Updating uv version¶

The uv version is pinned in docker/django/Dockerfile via the COPY --from=ghcr.io/astral-sh/uv:<version> directive. When you want to update uv, bump the version tag there.

Development with docker¶

To start development server inside docker you will need to run:

export DOCKER_BUILDKIT=1 COMPOSE_DOCKER_CLI_BUILD=1 # enable buildkit
docker compose build
docker compose run --rm web python manage.py migrate
docker compose up

Running scripts inside docker¶

As we have already mentioned inside the previous section we use docker compose run to run scripts inside docker.

What do you need to know about it?

You can run anything you want: uv, python, sh, etc
Most likely it will have a permanent effect, due to docker volumes
You need to use --rm to automatically remove this container afterward

Note: docker commands do not need to use virtualenv at all.

Local development¶

When cloning a project for the first time you may need to configure it properly, see Django section for more information.

Note, that you will need to activate virtualenv created by uv before running any of these commands. Note, that you only need to run these commands once per project.

Local database¶

When using local development environment without docker, you will need a postgres up and running. To create new development database run (make sure that database and user names are correct for your case):

psql postgres -U postgres -f scripts/create_dev_database.sql

Then migrate your database:

python manage.py migrate

Running project¶

If you have reached this point, you should be able to run the project.

python manage.py runserver