📝 [#200] Update docs for setup configuration changes

docs/installation/configuration/env_config.rst

@@ -110,6 +110,7 @@ Optional
 * ``LOG_OUTGOING_REQUESTS_MAX_AGE``: The amount of time after which request logs should be deleted from the database. Defaults to: ``7``.
 * ``SENTRY_DSN``: URL of the sentry project to send error reports to. Default empty, i.e. -> no monitoring set up. Highly recommended to configure this.
 * ``EXTRA_VERIFY_CERTS``: a comma-separated list of paths to certificates to trust, If you're using self-signed certificates for the services that Open Notificaties communicates with, specify the path to those (root) certificates here, rather than disabling SSL certificate verification. Example: ``EXTRA_VERIFY_CERTS=/etc/ssl/root1.crt,/etc/ssl/root2.crt``. Defaults to: ``(empty string)``.
+* ``OPENNOTIFICATIES_DOMAIN``: The domain for this Open Notificaties instance (``[host]:[port]`` or ``[host]``). Defaults to: ``(empty string)``.
 
 
 

docs/installation/configuration/opennotifs_config_cli.rst

@@ -5,11 +5,8 @@ Open Notificaties configuration (CLI)
 =====================================
 
 After deploying Open Notificaties, it needs to be configured to be fully functional. The
-command line tool ``setup_configuration`` assists with this configuration:
-
-* It uses environment variables for all configuration choices, therefore you can integrate this with your
-  infrastructure tooling such as init containers and/or Kubernetes Jobs.
-* The command can self-test the configuration to detect problems early on
+command line tool ``setup_configuration`` assist with this configuration by loading a
+YAML file in which the configuration information is specified.
 
 You can get the full command documentation with:
 
@@ -21,96 +18,56 @@ You can get the full command documentation with:
    running the command and you then run the exact same command again, the manual
    changes will be reverted.
 
-
 Preparation
 ===========
 
 The command executes the list of pluggable configuration steps, and each step
-requires specific environment variables, that should be prepared.
-Here is the description of all available configuration steps and the environment variables,
-use by each step.
+requires specific configuration information, that should be prepared.
+Here is the description of all available configuration steps and the shape of the data,
+used by each step.
 
-Sites configuration
--------------------
 
-Configure the domain where Open Notificaties is hosted
+Services configuration
+----------------------
 
-* ``SITES_CONFIG_ENABLE``: enable Site configuration. Defaults to ``False``.
-* ``OPENNOTIFICATIES_DOMAIN``:  a ``[host]:[port]`` or ``[host]`` value. Required.
-* ``OPENNOTIFICATIES_ORGANIZATION``: name of Open Notificaties organization. Required.
+TODO: add generated documentation for ``zgw_consumers.ServiceConfigurationStep``
 
-Authorization configuration
----------------------------
+Client credentials
+------------------
 
-Open Notificaties uses Open Zaak Authorisaties API to check authorizations
-of its consumers, therefore Open Notificaties should be able to request Open Zaak.
-Make sure that the correct permissions are configured in Open Zaak Autorisaties API.
+TODO: add generated documentation for ``JWTSecretsConfigurationStep``
 
-* ``AUTHORIZATION_CONFIG_ENABLE``: enable Authorization configuration. Defaults
-  to ``False``.
-* ``AUTORISATIES_API_ROOT``: full URL to the Authorisaties API root, for example
-  ``https://open-zaak.gemeente.local/autorisaties/api/v1/``. Required.
-* ``NOTIF_OPENZAAK_CLIENT_ID``: a client id, which Open Notificaties uses to request
-  Open Zaak, for example, ``open-notificaties``. Required.
-* ``NOTIF_OPENZAAK_SECRET``: some random string. Required.
 
-Open Zaak authentication configuration
---------------------------------------
+Autorisaties API configuration
+------------------------------
 
-Open Zaak published notifications to the Open Notificaties, therefore it should have access.
-Make sure that the correct permissions are configured in Open Zaak Autorisaties API.
+TODO: add generated documentation
 
-* ``OPENZAAK_NOTIF_CONFIG_ENABLE``: enable Open Zaak configuration. Defaults to ``False``.
-* ``OPENZAAK_NOTIF_CLIENT_ID``: a client id, which Open Zaak uses to request Open Notificaties,
-  for example, ``open-zaak``. Required.
-* ``OPENZAAK_NOTIF_SECRET``: some random string. Required.
 
-.. _installation_configuration_cli_retry:
+Notificaties configuration
+--------------------------
 
-Notification retry configuration
---------------------------------
+TODO: add generated documentation
 
-Open Notifications has a retry mechanism to guarantee notification delivery, this mechanism
-is described in :ref:`delivery_guarantees`. The parameters for this behavior can be configured via the
-following environment variables.
 
-* ``NOTIFICATION_RETRY_CONFIG_ENABLE``: enable Notification retry configuration. Defaults to ``False``.
-* ``NOTIFICATION_DELIVERY_MAX_RETRIES``: the maximum number of retries Celery will do if sending a notification failed.
-* ``NOTIFICATION_DELIVERY_RETRY_BACKOFF``: a boolean or a number. If this option is set to
-  ``True``, autoretries will be delayed following the rules of exponential backoff. If
-  this option is set to a number, it is used as a delay factor.
-* ``NOTIFICATION_DELIVERY_RETRY_BACKOFF_MAX``: an integer, specifying number of seconds.
-  If ``retry_backoff`` is enabled, this option will set a maximum delay in seconds
-  between task autoretries. By default, this option is set to 48 seconds.
+Sites configuration
+-------------------
 
-These settings can also later be changed via the admin interface, under ``Configuration > Notification component configuration``.
+TODO: add generated documentation
 
 Execution
 =========
 
-With the full command invocation, everything is configured at once and immediately
-tested. For all the self-tests to succeed, it's important that the configuration in the
-Open Zaak is done before calling this command.
-
-.. code-block:: bash
-
-    src/manage.py setup_configuration
-
+Open Notificaties configuration
+-------------------------------
 
-Alternatively, you can skip the self-tests by using the ``--no-selftest`` flag.
+With the full command invocation, all defined configuration steps are applied. Each step is idempotent,
+so it's safe to run the command multiple times. The steps will overwrite any manual changes made in
+the admin if you run the command after making these changes.
 
 .. code-block:: bash
 
-    src/manage.py setup_configuration --no-self-test
-
-
-``setup_configuration`` command checks if the configuration already exists before changing it.
-If you want to change some of the values of the existing configuration you can use ``--overwrite`` flag.
-
-.. code-block:: bash
-
-    src/manage.py setup_configuration --overwrite
-
+    src/manage.py setup_configuration
 
 .. note:: Due to a cache-bug in the underlying framework, you need to restart all
    replicas for part of this change to take effect everywhere.

src/nrc/conf/includes/base.py

@@ -161,4 +161,8 @@
 # Open Notificaties settings
 #
 
-OPENNOTIFICATIES_DOMAIN = config("OPENNOTIFICATIES_DOMAIN", "")
+OPENNOTIFICATIES_DOMAIN = config(
+    "OPENNOTIFICATIES_DOMAIN",
+    "",
+    help_text="The domain for this Open Notificaties instance (``[host]:[port]`` or ``[host]``)",
+)