If you're looking to deploy on Kubernetes, see the :ref:`install on Kubernetes using Ansible <installation_kubernetes_ansible>` documentation.
Open Zaak can be deployed on a single machine like a dedicated server (DDS), virtual machine or virtual private server (VPS). The required hardware can be rented from a hosting provider or be provided in your environment. Please see :ref:`installation_hardware` to determine the hardware requirements.
This documentation describes the architecture, prerequisites and how to deploy Open Zaak on such a server. Additionally, it documents the possible configuration options.
Note
The default settings allow Open Zaak to be deployed to the same machine as Open Notificaties.
Architecture
The application is deployed as Docker (or Podman) containers, of which the images are available on Docker hub. Traffic is routed to the server, where the web server (nginx) handles TLS termination and proxies the requests to the application containers.
Data is stored in a PostgreSQL database. By default, the database is installed on the same machine (running on the host), but you can make use of a hosted database (Google Cloud, AWS, Azure or your own infrastructure). See the :ref:`installation_ansible_config_params` for more information.
You will only need Ansible tooling and nothing more on your own machine:
You can configure the Ansible playbook to install relevant services, do it manually, or have these pre-installed. You will need:
- a server with
root
privileges. We assume you can directly ssh to the machine asroot
user. If that's not the case, a user withsudo
will also work. Python 3 must be available on the server.
Note
Make sure there is enough space in /var/lib/docker
. You need at
least 8 GB to download all container images. We recommend placing the Docker
folder wherever you also want to store your documents that are uploaded via
the Documenten API.
Supported operating systems
Support for different Linux flavours is maintained in the Ansible collection used for deployment.
Currently the following OS flavours are supported:
- Debian: bookworm (12), bullseye (11), buster (10, actively supported), stretch (9)
- Ubuntu: bionic (18.04 LTS) - focal (20.04 LTS) and jammy (22.04 LTS) are not tested yet
- SUSE Enterprise Linux: 15 (actively supported)
- OpenSUSE: 15.1
- Red Hat and CentOS: 7, 8
You can either clone the https://github.com/open-zaak/open-zaak repository, or download and extract the latest ZIP: https://github.com/open-zaak/open-zaak/archive/main.zip
Python and a Python virtualenv
You will need to have at least Python 3.7 installed on your system. In the examples, we assume you have Python 3.7.
Create a virtualenv with:
[user@laptop]$ python3.7 -m venv env/
[user@laptop]$ source env/bin/activate
Make sure to install the deployment tooling. In your virtualenv, install the dependencies:
(env) [user@laptop]$ pip install -r deployment/requirements.txt
(env) [user@laptop]$ cd deployment/single-server
(env) [user@laptop]$ ansible-galaxy collection install -r requirements.yml
(env) [user@laptop]$ ansible-galaxy role install -r requirements.yml
Deployment is done with an Ansible playbook, performing the following steps:
- Install and configure PostgreSQL database server
- Install the Docker runtime
- Install the SSL certificate with Let's Encrypt
- Setup Open Zaak with Docker
- Install and configure nginx as reverse proxy
Note
Podman users should tweak the playbook and replace the appropriate docker roles with their podman variants.
Make sure the virtualenv is activated:
[user@laptop]$ source env/bin/activate
Navigate to the correct deployment directory:
(env) [user@laptop]$ cd deployment/single-server
Create the vars/open-zaak.yml
file - you can find an example in
vars/open-zaak.yml.example
. Generate a secret key using the
Django secret key generator and put the value between single quotes.
Configure the host by creating the hosts
file from the example:
(env) [user@laptop]$ cp hosts.example hosts
In the hosts
file, edit the open-zaak.gemeente.nl
to point to your actual
domain name. You must make sure that the DNS entry for this domain points to the
IP address of your server.
Warning
It's important to use the correct domain name, as the SSL certificate will be generated for this domain and only this domain will be allow-listed by Open Zaak!
If you are using a private DNS name, then no SSL certificate
can be created via Letsencrypt - make sure to disable it by setting
certbot_create_if_missing=false
or openzaak_ssl=false
if you don't
plan on using HTTPS at all.
Execute the playbook by running:
(env) [user@laptop]$ ansible-playbook open-zaak.yml
Hint
- If you have your secrets Ansible vault encrypted, make sure you have either:
- set the
ANSIBLE_VAULT_PASSWORD_FILE
environment variable, or - pass
--ask-vault-pass
flag toansible-playbook
.
- set the
- If you need to override any deployment variables (see
:ref:`installation_ansible_config_params`), you can pass variables to
ansible-playbook
using the syntax:--extra-vars "some_var=some_value other_var=other_value"
. - If you want to run the deployment from the same machine as where Open Zaak will
be running (ie. install to itself), you can pass
--connection local
toansible-playbook
. - If you cannot connect as
root
to the target machine, you can pass--user <user> --become --become-method=sudo --ask-become-pass
which will connect as user<user>
that needssudo
-rights on the target machine to install the requirements.
A full example might look like this:
(env) [user@laptop]$ ansible-playbook open-zaak.yml \
--user admin
--inventory my-hosts \ # Use inventory file ``my-hosts`` instead of ``hosts``.
--limit open-zaak.gemeente.nl \ # Only pick open-zaak.gemeente.nl from the inventory file.
--extra-vars "openzaak_ssl=false openzaak_db_name=open-zaak-test openzaak_db_username=open-zaak-test" \
--connection local \
--become \
--become-method=sudo \
--ask-become-pass
Note
You can run the deployment multiple times, it will not affect the final outcome. If you decide to change configuration parameters, you do not have to start from scratch.
Changing environment variables
The Open Zaak configuration is templated out to /home/openzaak/.env
on the host
machine. It's possible to modify environment variables here, but doing so will not
become effective immediately - you need to restart the containers:
[root@host]# docker restart openzaak-0 openzaak-1 openzaak-2
Make sure to do this for every replica - you can see what's running with docker ps
.
Warning
If you modify the .env
file and then apply the Ansible playbook again,
this will overwrite your changes!
After the initial deployment, some initial configuration is required. This configuration is stored in the database and is only needed once.
Create a superuser
A superuser allows you to perform all administrative tasks.
Log in to the server:
[user@laptop]$ ssh root@open-zaak.gemeente.nl
Create the superuser (interactive on the shell). Note that the password you type in will not be visible - not even with asterisks. This is normal.
This can also be automated, see :ref:`installation_provision_superuser`.
[root@open-zaak.gemeente.nl]# docker exec -it openzaak-0 src/manage.py createsuperuser Gebruikersnaam: demo E-mailadres: admin@open-zaak.gemeente.nl Password: Password (again): Superuser created successfully.
Configure Open Zaak Admin
See the :ref:`installation_configuration` on how to configure Open Zaak post-installation.
At deployment time, you can configure a number of parts of the deployment by
overriding variables. You can override variables on the command line (using the
-e "..."
syntax) or by overriding them in vars/secrets.yml
.
Note
Tweaking configuration parameters is considered advanced usage.
certbot_admin_email
: e-mail address to use to accept the Let's Encrypt terms and conditions.openzaak_ssl
: whether to use Let's Encrypt to create an SSL certificate for your domain. Set tofalse
if you want to use an existing certificate.
The default values can be found in in the Ansible role.
openzaak_db_port
: database port. If you are running multiple PostgreSQL versions on the same machine, you'll have to point to the correct port.openzaak_db_host
: specify the hostname if you're using a cloud database or a database on a different server.openzaak_db_name
: specify a different database name.openzaak_db_username
: specify a different database username.openzaak_db_password
: specify a different database username.openzaak_secret_key
: A Django secret key. Used for cryptographic operations - this may NOT leak, ever. If it does leak, change it.
Scaling
The openzaak_replicas
variable controls scaling on backend services. If
your hardware allows it, you can create more replicas. By default, 3 replicas
are running.
The format of each replica is:
name: openzaak-i
port: 800i
The port number must be available on the host - i.e. you may not have other services already listening on that port.
You may want to :ref:`customize the logging setup<installation_logging_customize>`. The default setup should be sufficient to get started though.
To be able to work with Open Zaak, a couple of things have to be configured first, see :ref:`installation_configuration` for more details.
Make sure you have the deployment tooling installed - see :ref:`the installation steps<installation_ansible_tooling>` for more details.
If you have an existing environment (from the installation), make sure to update it:
# fetch the updates from Github
[user@host]$ git fetch origin
# checkout the tag of the version you wish to update to, e.g. 1.0.0
[user@host]$ git checkout X.Y.z
# activate the virtualenv
[user@host]$ source env/bin/activate
# ensure all (correct versions of the) dependencies are installed
(env) [user@host]$ pip install -r requirements.txt
(env) [user@host]$ ansible-galaxy install -r requirements.yml
Open Zaak deployment code defines variables to specify the Docker image tag to use. This is synchronized with the git tag you're checking out.
Warning
Make sure you are aware of possible breaking changes or manual interventions by reading the :ref:`development_changelog`!
Next, to perform the upgrade, you run the open-zaak.yml
playbook just like with the
installation in :ref:`installation_ansible_playbook`:
(env) [user@laptop]$ ansible-playbook open-zaak.yml
Note
This will instruct the docker containers to restart using a new image. You may notice some brief downtime (order of seconds to minutes) while the new image is being downloaded and containers are being restarted.