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:

Python 3.11
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 git@github.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 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 using npm run watch. By default this will compile the files if they change.

Update installation

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
```

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.

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 docker/alfresco/alfresco-global.properties 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 CMIS_BINDING can be set either to BROWSER or WEBSERVICE.

Or run the test-suite without CMIS tests:

$ python src/manage.py test src --exclude-tag cmis

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:

$ ./bin/celery_worker.sh

To start flower for task monitoring:

$ ./bin/celery_flower.sh