Merge pull request #174 from open-zaak/feature/envvar-documentation

📝 [open-zaak/open-zaak#1649] Document envvars

.github/workflows/ci.yml

@@ -64,7 +64,7 @@ jobs:
       - name: Publish coverage report
         uses: codecov/codecov-action@v3
 
-  docs:
+  check-envvar-docs:
     runs-on: ubuntu-latest
     name: Documentation build
 
@@ -75,6 +75,17 @@ jobs:
           python-version: '3.11'
       - name: Install dependencies
         run: pip install -r requirements/dev.txt pytest
+      - name: Generate environment variable documentation using OAf and check if it was updated
+        run: |
+          bin/generate_envvar_docs.sh
+          changes=$(git diff docs/installation/configuration/env_config.rst)
+          if [ ! -z "$changes" ]; then
+              echo $changes
+              echo "Please update the environment documentation by running \`bin/generate_envvar_docs.sh\`"
+              exit 1
+          fi
+        env:
+          DJANGO_SETTINGS_MODULE: nrc.conf.ci
       - name: Build and test docs
         run: cd docs && pytest check_sphinx.py -v --tb=auto
 

bin/generate_envvar_docs.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+# Generates the documentation for environment variables
+src/manage.py generate_envvar_docs --file docs/installation/configuration/env_config.rst

requirements/base.txt

@@ -15,8 +15,6 @@ asgiref==3.8.1
     #   django-cors-headers
 asn1crypto==1.5.1
     # via webauthn
-async-timeout==4.0.3
-    # via redis
 attrs==24.2.0
     # via
     #   glom
@@ -79,6 +77,7 @@ django==4.2.15
     #   django-appconf
     #   django-axes
     #   django-cors-headers
+    #   django-csp
     #   django-filter
     #   django-formtools
     #   django-jsonform
@@ -114,6 +113,8 @@ django-axes==6.5.1
     # via open-api-framework
 django-cors-headers==4.4.0
     # via open-api-framework
+django-csp==3.8
+    # via open-api-framework
 django-filter==24.3
     # via
     #   commonground-api-common
@@ -236,7 +237,7 @@ mozilla-django-oidc-db==0.19.0
     # via open-api-framework
 notifications-api-common==0.2.2
     # via commonground-api-common
-open-api-framework==0.6.1
+open-api-framework==0.8.0
     # via -r requirements/base.in
 orderedmultidict==1.0.1
     # via furl

requirements/ci.txt

@@ -22,10 +22,6 @@ asn1crypto==1.5.1
     # via
     #   -r requirements/base.txt
     #   webauthn
-async-timeout==4.0.3
-    # via
-    #   -r requirements/base.txt
-    #   redis
 attrs==24.2.0
     # via
     #   -r requirements/base.txt
@@ -126,6 +122,7 @@ django==4.2.15
     #   django-appconf
     #   django-axes
     #   django-cors-headers
+    #   django-csp
     #   django-filter
     #   django-formtools
     #   django-jsonform
@@ -169,6 +166,10 @@ django-cors-headers==4.4.0
     # via
     #   -r requirements/base.txt
     #   open-api-framework
+django-csp==3.8
+    # via
+    #   -r requirements/base.txt
+    #   open-api-framework
 django-filter==24.3
     # via
     #   -r requirements/base.txt
@@ -242,6 +243,7 @@ django-solo==2.3.0
 django-two-factor-auth[phonenumberslite,webauthn]==1.16.0
     # via
     #   -r requirements/base.txt
+    #   django-two-factor-auth
     #   maykin-2fa
 django-webtest==1.9.10
     # via -r requirements/test-tools.in
@@ -396,7 +398,7 @@ notifications-api-common==0.2.2
     # via
     #   -r requirements/base.txt
     #   commonground-api-common
-open-api-framework==0.6.1
+open-api-framework==0.8.0
     # via -r requirements/base.txt
 orderedmultidict==1.0.1
     # via

requirements/dev.txt

@@ -24,10 +24,6 @@ asn1crypto==1.5.1
     # via
     #   -r requirements/ci.txt
     #   webauthn
-async-timeout==4.0.3
-    # via
-    #   -r requirements/ci.txt
-    #   redis
 attrs==24.2.0
     # via
     #   -r requirements/ci.txt
@@ -141,6 +137,7 @@ django==4.2.15
     #   django-appconf
     #   django-axes
     #   django-cors-headers
+    #   django-csp
     #   django-debug-toolbar
     #   django-extensions
     #   django-filter
@@ -186,6 +183,10 @@ django-cors-headers==4.4.0
     # via
     #   -r requirements/ci.txt
     #   open-api-framework
+django-csp==3.8
+    # via
+    #   -r requirements/ci.txt
+    #   open-api-framework
 django-debug-toolbar==3.2.4
     # via -r requirements/dev.in
 django-extensions==3.1.5
@@ -263,6 +264,7 @@ django-solo==2.3.0
 django-two-factor-auth[phonenumberslite,webauthn]==1.16.0
     # via
     #   -r requirements/ci.txt
+    #   django-two-factor-auth
     #   maykin-2fa
 django-webtest==1.9.10
     # via -r requirements/ci.txt
@@ -440,7 +442,7 @@ notifications-api-common==0.2.2
     # via
     #   -r requirements/ci.txt
     #   commonground-api-common
-open-api-framework==0.6.1
+open-api-framework==0.8.0
     # via -r requirements/ci.txt
 orderedmultidict==1.0.1
     # via

src/nrc/conf/dev.py

@@ -10,6 +10,7 @@
 os.environ.setdefault("IS_HTTPS", "no")
 os.environ.setdefault("RELEASE", "dev")
 os.environ.setdefault("ENVIRONMENT", "development")
+os.environ.setdefault("DISABLE_2FA", "True")
 
 os.environ.setdefault("DB_NAME", "opennotificaties")
 os.environ.setdefault("DB_USER", "opennotificaties")
@@ -50,10 +51,6 @@
 INTERNAL_IPS = ("127.0.0.1",)
 DEBUG_TOOLBAR_CONFIG = {"INTERCEPT_REDIRECTS": False}
 
-# None of the authentication backends require two-factor authentication.
-if config("DISABLE_2FA", default=True):  # pragma: no cover
-    MAYKIN_2FA_ALLOW_MFA_BYPASS_BACKENDS = AUTHENTICATION_BACKENDS
-
 # in memory cache and django-axes don't get along.
 # https://django-axes.readthedocs.io/en/latest/configuration.html#known-configuration-problems
 CACHES = {
@@ -84,4 +81,4 @@
 
 TEST_CALLBACK_AUTH = False
 
-ELASTIC_APM["DEBUG"] = config("DISABLE_APM_IN_DEV", default=True)
+ELASTIC_APM["DEBUG"] = config("DISABLE_APM_IN_DEV", default=True, add_to_docs=False)

src/nrc/conf/includes/base.py

@@ -58,7 +58,12 @@
 PROJECT_NAME = "Open Notificaties"
 SITE_TITLE = "API dashboard"
 
-LOG_NOTIFICATIONS_IN_DB = config("LOG_NOTIFICATIONS_IN_DB", default=False)
+LOG_NOTIFICATIONS_IN_DB = config(
+    "LOG_NOTIFICATIONS_IN_DB",
+    default=False,
+    help_text="indicates whether or not sent notifications should be saved to the database.",
+    group="Notifications",
+)
 
 
 ##############################
@@ -83,10 +88,21 @@
 # auth, avoiding having some set up MFA again in the project.
 
 # RabbitMQ
-BROKER_URL = config("PUBLISH_BROKER_URL", "amqp://guest:guest@localhost:5672/%2F")
+# TODO is this actually used?
+BROKER_URL = config(
+    "PUBLISH_BROKER_URL",
+    "amqp://guest:guest@localhost:5672/%2F",
+    help_text="the URL of the broker that will be used to actually send the notifications",
+    group="Celery",
+)
 
 # Celery
-CELERY_BROKER_URL = config("CELERY_BROKER_URL", "amqp://127.0.0.1:5672//")
+CELERY_BROKER_URL = config(
+    "CELERY_BROKER_URL",
+    "amqp://127.0.0.1:5672//",
+    help_text="the URL of the broker that will be used to actually send the notifications",
+    group="Celery",
+)
 CELERY_BEAT_SCHEDULE = {
     "clean-old-notifications": {
         "task": "nrc.api.tasks.clean_old_notifications",
@@ -99,7 +115,10 @@
 # Delete Notifications
 #
 NOTIFICATION_NUMBER_OF_DAYS_RETAINED = config(
-    "NOTIFICATION_NUMBER_OF_DAYS_RETAINED", 30
+    "NOTIFICATION_NUMBER_OF_DAYS_RETAINED",
+    30,
+    help_text="the number of days for which you wish to keep notifications",
+    group="Notifications",
 )
 
 #
@@ -119,34 +138,58 @@
     "nrc.config.notification_retry.NotificationRetryConfigurationStep",
 ]
 
+#
+# self-certifi
+#
+# To make sure this variable appears in the documentation
+config(
+    "EXTRA_VERIFY_CERTS",
+    "",
+    help_text=(
+        "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``."
+    ),
+)
+
 #
 # Open Notificaties settings
 #
 
 # Settings for setup_configuration command
 # sites config
-SITES_CONFIG_ENABLE = config("SITES_CONFIG_ENABLE", default=True)
-OPENNOTIFICATIES_DOMAIN = config("OPENNOTIFICATIES_DOMAIN", "")
-OPENNOTIFICATIES_ORGANIZATION = config("OPENNOTIFICATIES_ORGANIZATION", "")
+SITES_CONFIG_ENABLE = config("SITES_CONFIG_ENABLE", default=True, add_to_docs=False)
+OPENNOTIFICATIES_DOMAIN = config("OPENNOTIFICATIES_DOMAIN", "", add_to_docs=False)
+OPENNOTIFICATIES_ORGANIZATION = config(
+    "OPENNOTIFICATIES_ORGANIZATION", "", add_to_docs=False
+)
 # notif -> OZ auth config
-AUTHORIZATION_CONFIG_ENABLE = config("AUTHORIZATION_CONFIG_ENABLE", default=True)
-AUTORISATIES_API_ROOT = config("AUTORISATIES_API_ROOT", "")
-NOTIF_OPENZAAK_CLIENT_ID = config("NOTIF_OPENZAAK_CLIENT_ID", "")
-NOTIF_OPENZAAK_SECRET = config("NOTIF_OPENZAAK_SECRET", "")
+AUTHORIZATION_CONFIG_ENABLE = config(
+    "AUTHORIZATION_CONFIG_ENABLE", default=True, add_to_docs=False
+)
+AUTORISATIES_API_ROOT = config("AUTORISATIES_API_ROOT", "", add_to_docs=False)
+NOTIF_OPENZAAK_CLIENT_ID = config("NOTIF_OPENZAAK_CLIENT_ID", "", add_to_docs=False)
+NOTIF_OPENZAAK_SECRET = config("NOTIF_OPENZAAK_SECRET", "", add_to_docs=False)
 # OZ -> notif config
-OPENZAAK_NOTIF_CONFIG_ENABLE = config("OPENZAAK_NOTIF_CONFIG_ENABLE", default=True)
-OPENZAAK_NOTIF_CLIENT_ID = config("OPENZAAK_NOTIF_CLIENT_ID", "")
-OPENZAAK_NOTIF_SECRET = config("OPENZAAK_NOTIF_SECRET", "")
+OPENZAAK_NOTIF_CONFIG_ENABLE = config(
+    "OPENZAAK_NOTIF_CONFIG_ENABLE", default=True, add_to_docs=False
+)
+OPENZAAK_NOTIF_CLIENT_ID = config("OPENZAAK_NOTIF_CLIENT_ID", "", add_to_docs=False)
+OPENZAAK_NOTIF_SECRET = config("OPENZAAK_NOTIF_SECRET", "", add_to_docs=False)
 
 # setup configuration for Notification retry
 # Retry settings for delivering notifications to subscriptions
 NOTIFICATION_RETRY_CONFIG_ENABLE = config(
-    "NOTIFICATION_RETRY_CONFIG_ENABLE", default=True
+    "NOTIFICATION_RETRY_CONFIG_ENABLE", default=True, add_to_docs=False
+)
+NOTIFICATION_DELIVERY_MAX_RETRIES = config(
+    "NOTIFICATION_DELIVERY_MAX_RETRIES", None, add_to_docs=False
 )
-NOTIFICATION_DELIVERY_MAX_RETRIES = config("NOTIFICATION_DELIVERY_MAX_RETRIES", None)
 NOTIFICATION_DELIVERY_RETRY_BACKOFF = config(
-    "NOTIFICATION_DELIVERY_RETRY_BACKOFF", None
+    "NOTIFICATION_DELIVERY_RETRY_BACKOFF", None, add_to_docs=False
 )
 NOTIFICATION_DELIVERY_RETRY_BACKOFF_MAX = config(
-    "NOTIFICATION_DELIVERY_RETRY_BACKOFF_MAX", None
+    "NOTIFICATION_DELIVERY_RETRY_BACKOFF_MAX", None, add_to_docs=False
 )

src/nrc/templates/open_api_framework/env_config.rst

@@ -0,0 +1,17 @@
+{% extends "open_api_framework/env_config.rst" %}
+
+{% block intro %}
+Open Notificaties 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.
+{% endblock %}
+
+{% block extra %}
+---------------------
+Initial configuration
+---------------------
+
+Open Notificaties supports ``setup_configuration`` management command, which allows configuration via
+environment variables.
+All these environment variables are described at :ref:`installation_configuration_cli`.
+{% endblock %}