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 poetry 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 poetry 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 command for docker based development, since it is already executed inside Dockerfile.

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

poetry install

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

poetry install --only=main

To install all dependencies, including docs:

poetry install --with=docs

And to activate virtualenv created by poetry run:

poetry shell

Adding new dependencies¶

To add a new dependency you can run:

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

This command might be used with docker.

Updating poetry version¶

Package managers should also be pinned very strictly. We had a lot of problems in production because we were not pinning package manager versions.

This can result in broken lock files, inconsistent installation process, bizarre bugs, and missing packages. You do not want to experience that!

How can we have the same poetry version for all users in a project? That’s where [build-system] tag shines. It specifies the exact version of your poetry installation that must be used for the project. Version mismatch will fail your build.

When you want to update poetry, you have to bump it in several places:

pyproject.toml
docker/django/Dockerfile

Then you are fine!

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: poetry, 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 poetry 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