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.
You need the following libraries and/or programs:
Python Virtualenv and Pip 20.0 or above
PostgreSQL 10.0 or above, with the PostGIS-extension
Node.js 16.0 or above
npm 8.0 or above
Docker 19.03 or above (and docker-compose)
Step by step
Developers can follow the following steps to set up the project on their local development machine.
Navigate to the location where you want to place your project.
Get the code:
$ git clone email@example.com:open-zaak/open-zaak.git $ cd open-zaak
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: 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.
Install all required libraries:
$ virtualenv env # or, python -m venv env $ source env/bin/activate $ pip install -r requirements/dev.txt
Install the front-end CLI tool gulp if you’ve never installed them before and install the frontend libraries:
$ npm install $ npm run build
Activate your virtual environment and create the statics and database:
$ source env/bin/activate $ python src/manage.py migrate
Create a superuser to access the management interface:
$ python src/manage.py createsuperuser
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
npm run watch. By default this will compile the files if they change.
When updating an existing installation:
Activate the virtual environment:
$ cd open-zaak $ source env/bin/activate
Update the code and libraries:
$ git pull $ pip install -r requirements/dev.txt $ npm install $ npm run build
Update the statics and database:
$ python src/manage.py migrate
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
SECRET_KEY: the secret key to use. A default is set in
DB_NAME: name of the database for the project. Defaults to
DB_USER: username to connect to the database with. Defaults to
DB_PASSWORD: password to use to connect to the database. Defaults to
DB_HOST: database host. Defaults to
DB_PORT: database port. Defaults to
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.
Testing with CMIS adapter enabled
The tests for Open Zaak with the CMIS adapter enabled use Alfresco as the Document
Management System. This is run with docker compose, using the compose file
docker-compose.ci.cmis.yml. In the folder
extension/, there are xml files
defining the custom models used. The file
contains the global properties that are required to run Alfresco.
The containers are launched with:
$ docker-compose -f docker-compose.ci.cmis.yml up -d
This creates a
volumes/ directory where all the logs and the data are stored.
You can run only the CMIS tests with:
$ python src/manage.py test src --tag cmis
In order to choose whether to test with the browser binding or the web service binding, the environment variable
can be set either to
Or run the test-suite without CMIS tests:
$ python src/manage.py test src --exclude-tag cmis
All settings for the project can be found in
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:
To start flower for task monitoring: