From d9d1007ace5dc864aba92ca66326a4eeba68a3c8 Mon Sep 17 00:00:00 2001
From: Sonny Bakker <sonny871@hotmail.com>
Date: Fri, 29 Nov 2024 12:57:23 +0100
Subject: [PATCH] [#293] include documentation

---
 docs/installation/config.rst              |  8 +++
 docs/installation/index.rst               |  1 +
 docs/installation/setup_configuration.rst | 66 +++++++++++++++++++++++
 3 files changed, 75 insertions(+)
 create mode 100644 docs/installation/setup_configuration.rst

diff --git a/docs/installation/config.rst b/docs/installation/config.rst
index cb3813e3..f284fd89 100644
--- a/docs/installation/config.rst
+++ b/docs/installation/config.rst
@@ -129,3 +129,11 @@ 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.
+
+
+Initial configuration
+=====================
+
+Open Klant supports the ``setup_configuration`` management command, which allows
+configuration via yaml files. Further details using this command can be read at
+:ref:`installation_configuration_cli`.
diff --git a/docs/installation/index.rst b/docs/installation/index.rst
index 9264f40d..a3122eeb 100644
--- a/docs/installation/index.rst
+++ b/docs/installation/index.rst
@@ -16,3 +16,4 @@ this.
 
    config
    migration
+   setup_configuration
diff --git a/docs/installation/setup_configuration.rst b/docs/installation/setup_configuration.rst
new file mode 100644
index 00000000..fadf4215
--- /dev/null
+++ b/docs/installation/setup_configuration.rst
@@ -0,0 +1,66 @@
+.. _installation_configuration_cli:
+
+==============================
+Open Klant configuration (CLI)
+==============================
+
+After deploying Open Klant, it needs to be configured to be fully functional.
+You can get the full command documentation with:
+
+.. code-block:: bash
+
+    $ src/manage.py setup_configuration --help
+
+.. warning:: This command is declarative - if configuration is manually changed after
+   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
+has required specific variables, that should be prepared.
+Here is the description of all available configuration steps and the variables,
+used by each step.
+
+Token configuration
+----------------------
+
+Create a YAML configuration file with your settings:
+
+.. code-block:: yaml
+
+    tokens_config_enable: true
+
+    tokens_config:
+      group:
+        - identifier: token-1
+          contact_person: Person 1
+          email: person-1@example.com
+          organization: Organization XYZ # optional
+          application: Application XYZ # optional
+          administration: Administration XYZ # optional
+
+        - identifier: token-2
+          contact_person: Person 2
+          email: person-2@example.com
+
+.. note:: Invalid entries will be skipped and logged according to the configured
+   logging settings.
+
+Execution
+=========
+
+Open Klant configuration
+------------------------
+
+With the full command invocation, everything is configured at once. Each configuration step
+is idempotent, so any manual changes made via the admin interface will be updated if the command
+is run afterwards.
+
+.. code-block:: bash
+
+    $ 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.