diff --git a/docs/admin/01_config.rst b/docs/admin/01_config.rst new file mode 100644 index 0000000000000000000000000000000000000000..b375ffb8b63d88993e47fa0fb96c16d8217571ee --- /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