diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c3d31c1..dcf1ee8 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/bin/generate_envvar_docs.sh b/bin/generate_envvar_docs.sh new file mode 100755 index 0000000..2a4c8aa --- /dev/null +++ b/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 diff --git a/docs/installation/configuration/env_config.rst b/docs/installation/configuration/env_config.rst index 8ab2818..c774bf5 100644 --- a/docs/installation/configuration/env_config.rst +++ b/docs/installation/configuration/env_config.rst @@ -4,145 +4,115 @@ Environment configuration reference =================================== + 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. + Available environment variables =============================== --------- + Required -------- -* ``DJANGO_SETTINGS_MODULE``: which environment settings to use. Available options: - * ``nrc.conf.production`` - * ``nrc.conf.staging`` - * ``nrc.conf.docker`` - * ``nrc.conf.dev`` - * ``nrc.conf.ci`` - -* ``SECRET_KEY``: secret key that's used for certain cryptographic utilities. You - should generate one via `miniwebtool`_ +* ``SECRET_KEY``: Secret key that's used for certain cryptographic utilities. You should generate one via `miniwebtool `_. +* ``ALLOWED_HOSTS``: a comma separated (without spaces!) list of domains that serve the installation. Used to protect against Host header attacks. Defaults to: ``(empty string)``. +* ``CACHE_DEFAULT``: redis cache address for the default cache (this **MUST** be set when using Docker). Defaults to: ``localhost:6379/0``. +* ``CACHE_AXES``: redis cache address for the brute force login protection cache (this **MUST** be set when using Docker). Defaults to: ``localhost:6379/0``. +* ``EMAIL_HOST``: hostname for the outgoing e-mail server (this **MUST** be set when using Docker). Defaults to: ``localhost``. -* ``ALLOWED_HOSTS``: a comma separated (without spaces!) list of domains that - serve the installation. Used to protect against ``Host`` header attacks. -**Docker** - -Additionally, the following optional envvars MUST be set/changed when running -on Docker, since ``localhost`` is contained within the container: - -* ``CACHE_DEFAULT`` -* ``CACHE_AXES`` -* ``EMAIL_HOST`` - --------- -Optional +Database -------- -* ``ENVIRONMENT``: An identifier for the environment, displayed in the admin depending on - the settings module used and included in the error monitoring (see ``SENTRY_DSN``). - The default is set according to ``DJANGO_SETTINGS_MODULE``. Good examples values are: - * ``production`` - * ``test`` - * ``ACME public`` - -* ``SITE_ID``: defaults to ``1``. The database ID of the site object. You usually - won't have to touch this. - -* ``DEBUG``: defaults to ``False``. Only set this to ``True`` on a local development - environment. Various other security settings are derived from this setting! - -* ``IS_HTTPS``: defaults to the inverse of ``DEBUG``. Used to construct absolute - URLs and controls a variety of security settings. - -* ``DB_HOST``: hostname of the PostgreSQL database. Defaults to ``localhost``, - unless you're using the ``docker`` environment, then it defaults to ``db``. - -* ``DB_USER``: username of the database user. Defaults to ``opennotificaties``, - unless you're using the ``docker`` environment, then it defaults to ``postgres``. - -* ``DB_PASSWORD``: password of the database user. Defaults to ``opennotificaties``, - unless you're using the ``docker`` environment, then it defaults to no password. - -* ``DB_NAME``: name of the PostgreSQL database. Defaults to ``opennotificaties``, - unless you're using the ``docker`` environment, then it defaults to ``postgres``. - -* ``DB_PORT``: port number of the database, defaults to ``5432``. +* ``DB_NAME``: name of the PostgreSQL database. Defaults to: ``nrc``. +* ``DB_USER``: username of the database user. Defaults to: ``nrc``. +* ``DB_PASSWORD``: password of the database user. Defaults to: ``nrc``. +* ``DB_HOST``: hostname of the PostgreSQL database. Defaults to ``db`` for the docker environment, otherwise defaults to ``localhost``. +* ``DB_PORT``: port number of the database. Defaults to: ``5432``. -* ``USE_X_FORWARDED_HOST``: whether to grab the domain/host from the ``X-Forwarded-Host`` - header or not. This header is typically set by reverse proxies (such as nginx, - traefik, Apache...). Default ``False`` - this is a header that can be spoofed and you - need to ensure you control it before enabling this. -* ``NUM_PROXIES``: the number of reverse proxies in front of Open Notificaties, as an - integer. This is used to determine the actual client IP adres. Defaults to 1, which - should be okay on Kubernetes when using an Ingress. - -* ``CACHE_DEFAULT``: redis cache address for the default cache. Defaults to - ``localhost:6379/0``. - -* ``CACHE_AXES``: redis cache address for the brute force login protection cache. - Defaults to ``localhost:6379/0``. +Cross-Origin-Resource-Sharing +----------------------------- -* ``EMAIL_HOST``: hostname for the outgoing e-mail server. Defaults to - ``localhost``. +* ``CORS_ALLOW_ALL_ORIGINS``: allow cross-domain access from any client. Defaults to: ``False``. +* ``CORS_ALLOWED_ORIGINS``: explicitly list the allowed origins for cross-domain requests. Example: http://localhost:3000,https://some-app.gemeente.nl. Defaults to: ``[]``. +* ``CORS_ALLOWED_ORIGIN_REGEXES``: same as ``CORS_ALLOWED_ORIGINS``, but supports regular expressions. Defaults to: ``[]``. +* ``CORS_EXTRA_ALLOW_HEADERS``: headers that are allowed to be sent as part of the cross-domain request. By default, Authorization, Accept-Crs and Content-Crs are already included. The value of this variable is added to these already included headers. Defaults to: ``[]``. -* ``EMAIL_PORT``: port number of the outgoing e-mail server. Defaults to ``25``. - Note that if you're on Google Cloud, sending e-mail via port 25 is completely - blocked and you should use 487 for TLS. -* ``EMAIL_HOST_USER``: username to connect to the mail server. Default empty. +Celery +------ -* ``EMAIL_HOST_PASSWORD``: password to connect to the mail server. Default empty. +* ``CELERY_RESULT_BACKEND``: the URL of the backend/broker that will be used by Celery to send the notifications. Defaults to: ``redis://localhost:6379/1``. +* ``PUBLISH_BROKER_URL``: the URL of the broker that will be used to actually send the notifications. Defaults to: ``amqp://guest:guest@localhost:5672/%2F``. +* ``CELERY_BROKER_URL``: the URL of the broker that will be used to actually send the notifications. Defaults to: ``amqp://127.0.0.1:5672//``. -* ``EMAIL_USE_TLS``: whether to use TLS or not to connect to the mail server. - Defaults to ``False``. Should be ``True`` if you're changing the ``EMAIL_PORT`` to - ``487``. -* ``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. +Elastic APM +----------- -* ``LOG_STDOUT``: whether to log to stdout or not. For Docker environments, defaults to - ``True``, for other environments the default is to log to file. +* ``ELASTIC_APM_SERVER_URL``: URL where Elastic APM is hosted. Defaults to: ``None``. +* ``ELASTIC_APM_SERVICE_NAME``: Name of the service for this application in Elastic APM. Defaults to ``nrc - ``. +* ``ELASTIC_APM_SECRET_TOKEN``: Token used to communicate with Elastic APM. Defaults to: ``default``. +* ``ELASTIC_APM_TRANSACTION_SAMPLE_RATE``: By default, the agent will sample every transaction (e.g. request to your service). To reduce overhead and storage requirements, set the sample rate to a value between 0.0 and 1.0. Defaults to: ``0.1``. -* ``EXTRA_VERIFY_CERTS``: a comma-separated list of paths to certificates to trust, empty - by default. 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``. -* ``LOG_NOTIFICATIONS_IN_DB``: indicates whether or not sent notifications should be saved to the database (default: ``False``). +Content Security Policy +----------------------- -* ``NOTIFICATION_NUMBER_OF_DAYS_RETAINED``: the number of days for which you wish to keep notifications (default: ``30``). +* ``CSP_EXTRA_DEFAULT_SRC``: Extra default source URLs for CSP other than ``self``. Used for ``img-src``, ``style-src`` and ``script-src``. Defaults to: ``[]``. +* ``CSP_REPORT_URI``: URI of the``report-uri`` directive. Defaults to: ``None``. +* ``CSP_REPORT_PERCENTAGE``: Percentage of requests that get the ``report-uri`` directive. Defaults to: ``0``. +* ``CSP_EXTRA_FORM_ACTION``: Add additional ``form-action`` source to the default . Defaults to: ``[]``. +* ``CSP_FORM_ACTION``: Override the default ``form-action`` source. Defaults to: ``['"\'self\'"']``. +* ``CSP_EXTRA_IMG_SRC``: Extra ``img-src`` sources for CSP other than ``CSP_DEFAULT_SRC``. Defaults to: ``[]``. +* ``CSP_OBJECT_SRC``: ``object-src`` urls. Defaults to: ``['"\'none\'"']``. ------- -Celery ------- -* ``CELERY_BROKER_URL``: the URL of the broker that will be used to actually send the notifications (default: ``amqp://127.0.0.1:5672//``). +Notifications +------------- -* ``CELERY_RESULT_BACKEND``: the backend where the results of tasks will be stored (default: ``redis://localhost:6379/1``) +* ``LOG_NOTIFICATIONS_IN_DB``: indicates whether or not sent notifications should be saved to the database. Defaults to: ``False``. +* ``NOTIFICATION_NUMBER_OF_DAYS_RETAINED``: the number of days for which you wish to keep notifications. Defaults to: ``30``. ------------------------------ -Cross-Origin-Resource-Sharing ------------------------------ -The following parameters control the CORS policy. +Optional +-------- -* ``CORS_ALLOW_ALL_ORIGINS``: allow cross-domain access from any client. Defaults to ``False``. +* ``SITE_ID``: The database ID of the site object. You usually won't have to touch this. Defaults to: ``1``. +* ``DEBUG``: Only set this to ``True`` on a local development environment. Various other security settings are derived from this setting!. Defaults to: ``False``. +* ``USE_X_FORWARDED_HOST``: whether to grab the domain/host from the X-Forwarded-Host header or not. This header is typically set by reverse proxies (such as nginx, traefik, Apache...). Note: this is a header that can be spoofed and you need to ensure you control it before enabling this. Defaults to: ``False``. +* ``IS_HTTPS``: Used to construct absolute URLs and controls a variety of security settings. Defaults to the inverse of ``DEBUG``. +* ``EMAIL_PORT``: port number of the outgoing e-mail server. Note that if you're on Google Cloud, sending e-mail via port 25 is completely blocked and you should use 487 for TLS. Defaults to: ``25``. +* ``EMAIL_HOST_USER``: username to connect to the mail server. Defaults to: ``(empty string)``. +* ``EMAIL_HOST_PASSWORD``: password to connect to the mail server. Defaults to: ``(empty string)``. +* ``EMAIL_USE_TLS``: whether to use TLS or not to connect to the mail server. Should be True if you're changing the ``EMAIL_PORT`` to 487. Defaults to: ``False``. +* ``DEFAULT_FROM_EMAIL``: The default email address from which emails are sent. Defaults to: ``nrc@example.com``. +* ``LOG_STDOUT``: whether to log to stdout or not. Defaults to: ``False``. +* ``LOG_LEVEL``: control the verbosity of logging output. Available values are ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO`` and ``DEBUG``. Defaults to: ``WARNING``. +* ``LOG_QUERIES``: enable (query) logging at the database backend level. Note that you must also set ``DEBUG=1``, which should be done very sparingly!. Defaults to: ``False``. +* ``LOG_REQUESTS``: enable logging of the outgoing requests. Defaults to: ``False``. +* ``SESSION_COOKIE_SAMESITE``: The value of the SameSite flag on the session cookie. This flag prevents the cookie from being sent in cross-site requests thus preventing CSRF attacks and making some methods of stealing session cookie impossible. Defaults to: ``Strict``. +* ``CSRF_COOKIE_SAMESITE``: The value of the SameSite flag on the CSRF cookie. This flag prevents the cookie from being sent in cross-site requests. Defaults to: ``Strict``. +* ``ENVIRONMENT``: An identifier for the environment, displayed in the admin depending on the settings module used and included in the error monitoring (see ``SENTRY_DSN``). The default is set according to ``DJANGO_SETTINGS_MODULE``. +* ``SUBPATH``: If hosted on a subpath, provide the value here. If you provide ``/gateway``, the component assumes its running at the base URL: ``https://somedomain/gateway/``. Defaults to an empty string. Defaults to: ``None``. +* ``RELEASE``: The version number or commit hash of the application (this is also sent to Sentry). +* ``NUM_PROXIES``: the number of reverse proxies in front of the application, as an integer. This is used to determine the actual client IP adres. On Kubernetes with an ingress you typically want to set this to 2. Defaults to: ``1``. +* ``CSRF_TRUSTED_ORIGINS``: A list of trusted origins for unsafe requests (e.g. POST). Defaults to: ``[]``. +* ``NOTIFICATIONS_DISABLED``: indicates whether or not notifications should be sent to the Notificaties API for operations on the API endpoints. Defaults to ``True`` for the ``dev`` environment, otherwise defaults to ``False``. +* ``DISABLE_2FA``: Whether or not two factor authentication should be disabled. Defaults to: ``False``. +* ``LOG_OUTGOING_REQUESTS_EMIT_BODY``: Whether or not outgoing request bodies should be logged. Defaults to: ``True``. +* ``LOG_OUTGOING_REQUESTS_DB_SAVE``: Whether or not outgoing request logs should be saved to the database. Defaults to: ``False``. +* ``LOG_OUTGOING_REQUESTS_DB_SAVE_BODY``: Whether or not outgoing request bodies should be saved to the database. Defaults to: ``True``. +* ``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)``. -* ``CORS_ALLOWED_ORIGINS``: explicitly list the allowed origins for cross-domain requests. - Defaults to an empty list. Example: ``http://localhost:3000,https://some-app.gemeente.nl``. -* ``CORS_ALLOWED_ORIGIN_REGEXES``: same as ``CORS_ALLOWED_ORIGINS``, but supports regular - expressions. -* ``CORS_EXTRA_ALLOW_HEADERS``: headers that are allowed to be sent as part of the cross-domain - request. By default, ``Authorization``, ``Accept-Crs`` and ``Content-Crs`` are already - included. The value of this variable is added to these already included headers. - Defaults to an empty list. --------------------- Initial configuration @@ -154,15 +124,14 @@ All these environment variables are described at :ref:`installation_configuratio Specifying the environment variables -==================================== +===================================== There are two strategies to specify the environment variables: * provide them in a ``.env`` file -* start the Open Notificaties processes (with uwsgi/gunicorn/celery) in a process +* start the component processes (with uwsgi/gunicorn/celery) in a process manager that defines the environment variables ---------------------- Providing a .env file --------------------- @@ -172,17 +141,14 @@ NOT *in* the ``src`` directory). The syntax is key-value: -.. code-block:: +.. code:: + + SOME_VAR=some_value + OTHER_VAR="quoted_value" - 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 Open Notificaties implementation will pick them up out of -the box. - -.. _miniwebtool: https://www.miniwebtool.com/django-secret-key-generator/ +to define the envvars. The component will pick them up out of the box. diff --git a/requirements/base.txt b/requirements/base.txt index e12bc7a..23d9d12 100644 --- a/requirements/base.txt +++ b/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 diff --git a/requirements/ci.txt b/requirements/ci.txt index a8d7939..69d4833 100644 --- a/requirements/ci.txt +++ b/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 diff --git a/requirements/dev.txt b/requirements/dev.txt index 2aae165..693959f 100644 --- a/requirements/dev.txt +++ b/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 diff --git a/src/nrc/conf/dev.py b/src/nrc/conf/dev.py index 061fef2..eb5102e 100644 --- a/src/nrc/conf/dev.py +++ b/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) diff --git a/src/nrc/conf/includes/base.py b/src/nrc/conf/includes/base.py index 48e2952..c78922f 100644 --- a/src/nrc/conf/includes/base.py +++ b/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 ) diff --git a/src/nrc/templates/open_api_framework/env_config.rst b/src/nrc/templates/open_api_framework/env_config.rst new file mode 100644 index 0000000..76894ed --- /dev/null +++ b/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 %} \ No newline at end of file