Development environment

Prerequisites

You need the following libraries and/or programs:

Python – check the Dockerfile for the required version.
A Python virtual environment (created with Virtualenv or pyenv)
UV
PostgreSQL (with PostGIS) and GDAL – check the Dockerfile for the required version.
Node.js
npm

Navigate to the location where you want to place your project and clone it from github.
Create the database. The default database/postgres user/password that will be used is openarchiefbeheer (see src/openarchiefbeheer/conf/dev.py for the settings).
Activate your virtual environment.
Install the requirements uv pip install -r requirements/dev.txt.
Build the frontend (needed for the styling of the admin):
npm install npm run build
Run the migrations with src/manage.py migrate

Note

If you get an error about the django.contrib.gis module, you need to install the GDAL extension. To do this, you can either log into Postgres as superuser, connect to the database and run CREATE EXTENSION POSTGIS or you can give superuser rights to the openarchiefbeheer user. We recommend the former way.
Create a superuser to access the management interface:
```
src/manage.py createsuperuser
```
To set environment variables settings, create a .env file. You can use and modify the provided example:
```
cp dotenv.example .env
```

Generate the translation files:

./bin/make_translations.sh
src/manage.py compilemessages --locale nl

Run the development server with src/manage.py runserver

Optionally, you can load fixtures for the email templates and for the admin index configuration:

src/manage.py loaddata default_emails.json
src/manage.py loaddata default_admin_index.json

External Registers

To start Open Zaak, Open Klant and the Objects API with docker compose run the following command from the backend/docker-services folder:

sudo ./start_services.sh

It is possible to create demo data in these external services with this management command:

src/manage.py create_demo_data

To index the newly created zaken in OAB, make sure that you have celery running (from the backend folder run ./bin/celery_worker.sh) and then run:

src/manage.py resync_zaken

Running tests

This is how you can run the tests locally:

# Exclude E2E
src/manage.py tests openarchiefbeheer --no-input --exclude-tag=e2e

# Only E2E (see other section for the configuration needed for E2E tests)
src/manage.py tests openarchiefbeheer --no-input --tag=e2e

# Only VCR tests
src/manage.py tests openarchiefbeheer --no-input --tag=vcr

Tests running with PyTest can be run with:

pytest src/

To check test coverage:

coverage run --data-file=coverage_pytest -m pytest src/
coverage run --data-file=coverage_django src/manage.py test openarchiefbeheer --exclude-tag=e2e --exclude-tag=performance
coverage combine --data-file=coverage_combined coverage_django coverage_pytest
coverage xml --data-file=coverage_combined -o coverage.xml

The coverage.xml file can then, for example, be used in IDEs like VSCode with extension Coverage Gutters with ctrl+shift+7.

Docker

It is possible to start up a development docker environment with the file docker-compose.dev.yaml file. This does not support autoreload yet.

To start the environment:

docker compose -f docker-compose.dev.yaml up