From 7063e58b7a627e4af1c772c9bbd62e0369791220 Mon Sep 17 00:00:00 2001
From: Dominik George <dominik.george@teckids.org>
Date: Fri, 29 Nov 2019 12:30:16 +0100
Subject: [PATCH] [Docs] Add general explanation of configuration files.
---
docs/admin/01_config.rst | 53 +++++++++++++++++++++++++
docs/admin/{01_ldap.rst => 02_ldap.rst} | 0
docs/admin/{02_psql.rst => 03_psql.rst} | 0
3 files changed, 53 insertions(+)
create mode 100644 docs/admin/01_config.rst
rename docs/admin/{01_ldap.rst => 02_ldap.rst} (100%)
rename docs/admin/{02_psql.rst => 03_psql.rst} (100%)
diff --git a/docs/admin/01_config.rst b/docs/admin/01_config.rst
new file mode 100644
index 000000000..b375ffb8b
--- /dev/null
+++ b/docs/admin/01_config.rst
@@ -0,0 +1,53 @@
+Configuration files and format
+==============================
+
+File locations and order
+------------------------
+
+BiscuIT is configured through text files in the directory `/etc/biscuit/`.
+You can place any file types there that are supported by the `Dynaconf`_
+configuration system (INI, YAML and TOML).
+
+Files are evaluated in alphabetical order, with later definitions
+overwriting earlier ones. Normally, there will be only one configuration
+file, but you can make up any structure you like. If you use multiple
+files, it might be a good idea to number them, e.g. `00_main.toml`,
+`01_myschool.toml`, `99_temporary.toml`.
+
+The TOML format is recommended and is the only format described in detail in
+BiscuIT's documentation. For all other formats, refer to the `Dynaconf`_
+documentation.
+
+Configuration file format (TOML)
+--------------------------------
+
+TOML file are simple text files that define variables, much like in Python
+(i.e. there are scalars, lists and dictionaries). BiscuIT structures its
+configuration by topic.
+
+A configuration file might look like this::
+
+ [default]
+ secret_key = "VerySecretKeyForSessionSecurity"
+
+ [default.http]
+ allowed_hosts = [ "biscuit.myschool.example.com", "localhost" ]
+
+ [default.database]
+ name = "biscuit"
+ user = "biscuit"
+ password = "SuperSecretPassword"
+
+ [default.caching]
+ memcached = { enabled = true, address = "127.0.0.1" }
+
+The `secret_key` setting above defines a single value. The following `http`
+section defines a table (cf. a dictionary) in one way, and you can see the
+second form of such a table in the `memcached` setting (we could as well
+have defined another section called `[default.caching.memcached]` and placed
+`enabled` and `address` below it as scalars).
+
+This can be a bit confusing, so this documentation will explain how to
+configure BiscuIT on a per-feature basis.
+
+.. _Dynaconf: https://dynaconf.readthedocs.io/en/latest/
diff --git a/docs/admin/01_ldap.rst b/docs/admin/02_ldap.rst
similarity index 100%
rename from docs/admin/01_ldap.rst
rename to docs/admin/02_ldap.rst
diff --git a/docs/admin/02_psql.rst b/docs/admin/03_psql.rst
similarity index 100%
rename from docs/admin/02_psql.rst
rename to docs/admin/03_psql.rst
--
GitLab