From e49556759d8d0bcc0f48b289c8da29073ca871b3 Mon Sep 17 00:00:00 2001 From: Steven Bal Date: Fri, 6 Dec 2024 11:32:42 +0100 Subject: [PATCH] :memo: [#200] Update docs for setup configuration changes --- .../installation/configuration/env_config.rst | 1 + .../configuration/opennotifs_config_cli.rst | 95 +++++-------------- src/nrc/conf/includes/base.py | 6 +- 3 files changed, 32 insertions(+), 70 deletions(-) diff --git a/docs/installation/configuration/env_config.rst b/docs/installation/configuration/env_config.rst index 4eca0904..ebb79cec 100644 --- a/docs/installation/configuration/env_config.rst +++ b/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)``. diff --git a/docs/installation/configuration/opennotifs_config_cli.rst b/docs/installation/configuration/opennotifs_config_cli.rst index 5ef75a99..0f9f3f60 100644 --- a/docs/installation/configuration/opennotifs_config_cli.rst +++ b/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. diff --git a/src/nrc/conf/includes/base.py b/src/nrc/conf/includes/base.py index fcccbdf0..5316d161 100644 --- a/src/nrc/conf/includes/base.py +++ b/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]``)", +)