Skip to content
Snippets Groups Projects

DOC: merge README_CONFIGURATION.md and configuration.rst

Merged DOC: merge README_CONFIGURATION.md and configuration.rst
f-config-docs into dev
Merged Sina Rohde requested to merge f-config-docs into dev
Compare
and
1 file
+ 37
− 22
Compare changes
  • Side-by-side
  • Inline
src/doc/administration/configuration.rst
+ 37
− 22
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
@@ -39,8 +50,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,9 +67,11 @@ 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
-------------------------------------
## Changing the configuration at runtime
Remark:
Only when the server is in debug mode, the general configuration can be changed at runtime.