.. _installation_env_config:

===================================
Environment configuration reference
===================================


Open Zaak can be ran both as a Docker container or directly on a VPS or
dedicated server. It relies on other services, such as database and cache
backends, which can be configured through environment variables.


Available environment variables
===============================


.. config-all-params::


Initial superuser creation
--------------------------

A clean installation of Open Zaak comes without pre-installed or pre-configured admin
user by default.

Users of Open Zaak can opt-in to provision an initial superuser via environment
variables. The user will only be created if it doesn't exist yet.

* ``OPENZAAK_SUPERUSER_USERNAME``: specify the username of the superuser to create. Setting
  this to a non-empty value will enable the creation of the superuser. Default empty.
* ``OPENZAAK_SUPERUSER_EMAIL``: specify the e-mail address to configure for the superuser.
  Defaults to ``admin@admin.org``. Only has an effect if ``OPENZAAK_SUPERUSER_USERNAME`` is set.
* ``DJANGO_SUPERUSER_PASSWORD``: specify the password for the superuser. Default empty,
  which means the superuser will be created *without* password. Only has an effect
  if ``OPENZAAK_SUPERUSER_USERNAME`` is set.

Advanced application server options
-----------------------------------

Open Zaak uses `uWSGI`_ under
the hood, which can be configured with a myriad of options. Most of these can be
provided as environment variables as well. The following option is one you may need with Open Zaak.

* ``UWSGI_HTTP_TIMEOUT`` - defaults to 60s. If Open Zaak does not complete the request
  within this timeout, then uWSGI will error out.

Initial configuration
---------------------

Open Zaak supports ``setup_configuration`` management command, which allows configuration via
environment variables.
All these environment variables are described at :ref:`installation_configuration_cli`.

.. _uWSGI: https://uwsgi-docs.readthedocs.io/en/latest/Options.html
.. _Selectie Lijst: https://selectielijst.openzaak.nl/


Specifying the environment variables
=====================================

There are two strategies to specify the environment variables:

* provide them in a ``.env`` file
* start the component processes (with uwsgi/gunicorn/celery) in a process
  manager that defines the environment variables

Providing a .env file
---------------------

This is the most simple setup and easiest to debug. The ``.env`` file must be
at the root of the project - i.e. on the same level as the ``src`` directory (
NOT *in* the ``src`` directory).

The syntax is key-value:

.. code::

   SOME_VAR=some_value
   OTHER_VAR="quoted_value"


Provide the envvars via the process manager
-------------------------------------------

If you use a process manager (such as supervisor/systemd), use their techniques
to define the envvars. The component will pick them up out of the box.