Getting started

The project is developed in Python using the Django framework. There are 3 sections below, focussing on developers, running the project using Docker and hints for running the project in production.

Installation

Prerequisites

You need the following libraries and/or programs:

Step by step

Developers can follow the following steps to set up the project on their local development machine.

  1. Navigate to the location where you want to place your project.

  2. Get the code:

git clone git@github.com:open-zaak/open-zaak.git
cd open-zaak

  1. At this point you can already built the Docker image and run Open Zaak. You can skip this if you don’t want that.

docker compose up

Note

Note: If you are using Git on Windows, line-endings might change in checked out files depending on your core.autocrlf setting in .gitconfig. This is problematic because files are copied into a Docker image, which runs on Linux. Specifically, the bin/docker_start.sh file is affected by this which causes the Docker container fail to start up.

  1. Install all required libraries:

virtualenv env  # or, python -m venv env
source env/bin/activate
uv pip install -r requirements/dev.txt

  1. Install the frontend libraries:

nvm use
npm install
npm run build

  1. Activate your virtual environment and create the statics and database:

source env/bin/activate
python src/manage.py migrate

  1. Create a superuser to access the management interface:

python src/manage.py createsuperuser

  1. You can now run your installation and point your browser to the address given by this command:

python src/manage.py runserver

Note: If you are making local, machine specific, changes, add them to src/openzaak/conf/includes/local.py. You can also set certain common variables in a local .env file. You can base these files on the example files included in the same directory.

Note: You can run watch-tasks to compile Sass to CSS and ECMA to JS using npm run watch. By default this will compile the files if they change.

Update installation

When updating an existing installation:

  1. Activate the virtual environment:

cd open-zaak
source env/bin/activate

  1. Update the code and libraries:

git pull
uv pip install -r requirements/dev.txt
nvm use
npm install
npm run build

  1. Update the statics and database:

python src/manage.py migrate

Test data for development purposes

There is a fixture available to configure a basic Catalogus, which can be used to get started quickly with making API requests. This fixture is loaded automatically when running with docker compose and when running with with runserver can be loaded with:

src/manage.py loaddata docker/fixtures/catalogi.json

To update this fixture, you can run:

bin/generate_development_fixtures.sh

Additional configuration for development purposes (also loaded with docker compose by default) can be loaded with:

src/manage.py setup_configuration --yaml-file docker/setup_configuration/data.yaml

Testsuite

To run the test suite:

python src/manage.py test openzaak

Configuration via environment variables

A number of common settings/configurations can be modified by setting environment variables, add them to your .env file or persist them in src/openzaak/conf/includes/local.py.

  • SECRET_KEY: the secret key to use. A default is set in dev.py

  • DB_NAME: name of the database for the project. Defaults to open-zaak.

  • DB_USER: username to connect to the database with. Defaults to open-zaak.

  • DB_PASSWORD: password to use to connect to the database. Defaults to open-zaak.

  • DB_HOST: database host. Defaults to localhost

  • DB_PORT: database port. Defaults to 5432.

  • SENTRY_DSN: the DSN of the project in Sentry. If set, enabled Sentry SDK as logger and will send errors/logging to Sentry. If unset, Sentry SDK will be disabled.

Settings

All settings for the project can be found in src/openzaak/conf. The file includes/local.py overwrites settings from the base configuration, and is only loaded for the dev settings.

Running background tasks

We use Celery as background task queue.

You can run celery worker(s) in a shell to activate the asynchronous task queue processing.

To start the background workers executing tasks:

DB_HOST=localhost ./bin/celery_worker.sh

To start flower for task monitoring:

DB_HOST=localhost ./bin/celery_flower.sh