Merge branch 'f-config-docs' into 'dev'

DOC: merge README_CONFIGURATION.md and configuration.rst

See merge request !25

README_SETUP.md

@@ -118,7 +118,7 @@ server:
       - `INSERT_FILES_IN_DIR_ALLOWED_DIRS`: add mounted filesystems here that
         shall be accessible by CaosDB
     * Maybe set another `SESSION_TIMEOUT_MS`.
-    * See also [CONFIGURATION.rst](https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/src/doc/administration/configuration.rst)
+    * See also [CONFIGURATION.rst](src/doc/administration/configuration.rst)
 6. Copy `conf/core/usersources.ini.template` to `conf/ext/usersources.ini`.
     * You can skip this if you do not want to use an external authentication. 
       Local users (CaosDB realm) are always available.

src/doc/administration/configuration.rst

-Configuration
-=============
+Server Configuration
+====================
 
-The server is configured through configuration files. There are two directories with config files:
+Main Configuration File
+-----------------------
 
-``conf/core``
-   Upstream defaults are stored here.
-``conf/ext``
-   User specific configuration should be stored here, settings in ``ext`` override settings in
-   ``core``.  Additionally, configuration files may be stored in ``*.d`` directories here, named
-   after the original config file name.  For example, the general server configuration will be
-   assembled from ``conf/core/server.conf``, ``conf/ext/server.conf`` and any ``*.conf`` files found
-   in ``conf/ext/server.conf.d``.
+The server is configured through configuration files. The main file is the
+`server.conf`.
 
-Configuration files
--------------------
+The `server.conf` is a list of key-value pairs. A configuration file may
+contain empty lines, comment lines, and key-value lines.  Comment lines begin
+with a hash (`#`). Key-value lines must have the format `KEY_NAME=VALUE` or
+`KEY_NAME = VALUE`.
 
-In each of these directories, the server looks for the following files:
 
-``server.conf``
-   General server configuration options.  The possible configuration options are documented inside
-   the `default file
-   <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/server.conf>`__.
+The server default configuration is located at `./conf/core/server.conf`.
+Upstream defaults are stored here. The possible configuration options are
+documented inside the
+`default file <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/server.conf>`__.
+
+User specific configuration should be in `./conf/ext/` and  override settings
+in `./conf/core/`.
+
+The default configuration can be overriden by
+
+    1. the file ./conf/ext/server.conf
+
+    2. any file in ./conf/ext/server.conf.d/ in (approximately?) alphabetical order
+
+    3. environment variables with the prefix `CAOSDB_CONFIG_`
+
+in this order.
+
+Further Configuration Files
+---------------------------
+
+Further settings are to be set in files which are by default stored in `./conf/core/`:
 
 ``global_entity_permissions.xml``
-   :doc:`Permissions<../Permissions>` which are automatically set, based on user roles.  See the
+   :doc:`Permissions<../permissions>` which are automatically set, based on user roles.  See the
    `default file
    <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/global_entity_permissions.xml>`__.
 
@@ -39,8 +53,10 @@ In each of these directories, the server looks for the following files:
 
 ``authtoken.yaml``
    Configuration for dispensed authentication tokens, which can be used to authenticate to CaosDB
-   without the need of a user/password combination.  Possible use cases are server-side scripts or
-   initial setup after the server start.  There is more documentation inside the `template file
+   without the need of a user/password combination. One-time Authentication Tokens can be configure
+   to be issued for special purposes (e.g. a call of a server-side script or initial setup after the server start)
+   or to be written to a file on a regular basis. An example of a configuration is located at `./conf/core/authtoken.example.yaml`.
+   There is more documentation inside the `template file
    <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/authtoken.example.yaml>`__.
 
 ``cache.ccf``
@@ -54,6 +70,9 @@ In each of these directories, the server looks for the following files:
    <https://logging.apache.org/log4j/2.x/>`_.  The ``default`` file is always loaded, in debug mode
    the ``debug`` file iss added as well.
 
+The administrator may set the corresponding options in the main configuration
+file (`./conf/core/server.conf` and it's friends) to replace these special
+files with custom configuration.
 
 Changing the configuration at runtime
 -------------------------------------

src/doc/roles.md

@@ -10,7 +10,7 @@ users may have the same role, and there may be roles without any users.
 
 The user and their roles are always returned by the server in answers to requests
 and can thus be interpreted and used by clients.  The most important use though
-is [permission](Permissions) checking in the server: Access and
+is [permission](doc:`permissions`) checking in the server: Access and
 modification of
 entities can be controlled via roles, so that users of a given role are allowed
 or denied certain actions.  Incidentally, the permission to edit the permissions
@@ -32,4 +32,4 @@ There are some special roles, which are automatically assigned to users:
 
 Except for the `anonymous` role, these special roles are not returned by the
 server, but can nevertheless be used to define
-[permissions](Permissions).
+[permissions](doc:`permissions`).