+++ title = "Main" insert_anchor_links = "right" description = "Describes the configuration file and shows all default settings." weight = 10 template = "docs.html" +++ # Configuration Docspell's executables (restserver and joex) can take one argument – a configuration file. If that is not given, the defaults are used, overriden by environment variables. A config file overrides default values, so only values that differ from the defaults are necessary. The complete default options and their documentation is at the end of this page. Besides the config file, another way is to provide individual settings via key-value pairs to the executable by the `-D` option. For example to override only `base-url` you could add the argument `-Ddocspell.server.base-url=…` to the command. Multiple options are possible. For more than few values this is very tedious, obviously, so the recommended way is to maintain a config file. If these options *and* a file is provded, then any setting given via the `-D…` option overrides the same setting from the config file. At last, it is possible to configure docspell via environment variables if there is no config file supplied (if a config file *is* supplied, it is always preferred). Note that this approach is limited, as arrays are not supported. A list of environment variables can be found at the [end of this page](#environment-variables). The environment variable name follows the corresponding config key - where dots are replaced by underscores and dashes are replaced by two underscores. For example, the config key `docspell.server.app-name` can be defined as env variable `DOCSPELL_SERVER_APP__NAME`. It is also possible to specify environment variables inside a config file (to get a mix of both) - please see the [documentation of the config library](https://github.com/lightbend/config#standard-behavior) for more on this. # File Format The format of the configuration files can be [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md#hocon-human-optimized-config-object-notation), JSON or what this [config library](https://github.com/lightbend/config) understands. The default values below are in HOCON format, which is recommended, since it allows comments and has some [advanced features](https://github.com/lightbend/config#features-of-hocon). Please also see their documentation for more details. A short description (please check the links for better understanding): The config consists of key-value pairs and can be written in a JSON-like format (called HOCON). Keys are organized in trees, and a key defines a full path into the tree. There are two ways: ``` a.b.c.d=15 ``` or ``` a { b { c { d = 15 } } } ``` Both are exactly the same and these forms are both used at the same time. Usually the braces approach is used to group some more settings, for better readability. Strings that contain "not-so-common" characters should be enclosed in quotes. It is possible to define values at the top of the file and reuse them on different locations via the `${full.path.to.key}` syntax. When using these variables, they *must not* be enclosed in quotes. # Config Options The configuration of both components uses separate namespaces. The configuration for the REST server is below `docspell.server`, while the one for joex is below `docspell.joex`. You can therefore use two separate config files or one single file containing both namespaces. ## App-id The `app-id` is the identifier of the corresponding instance. It *must be unique* for all instances. By default the REST server uses `rest1` and joex `joex1`. It is recommended to overwrite this setting to have an explicit and stable identifier should multiple instances are intended. ``` bash docspell.server.app-id = "rest1" docspell.joex.app-id = "joex1" ``` ## Other options Please see the menu on the left for details about specific configuration options. # JVM Options The start scripts support some options to configure the JVM. One often used setting is the maximum heap size of the JVM. By default, java determines it based on properties of the current machine. You can specify it by given java startup options to the command: ``` $ ./docspell-restserver*/bin/docspell-restserver -J-Xmx1G -- /path/to/server-config.conf ``` This would limit the maximum heap to 1GB. The double slash separates internal options and the arguments to the program. Another frequently used option is to change the default temp directory. Usually it is `/tmp`, but it may be desired to have a dedicated temp directory, which can be configured: ``` $ ./docspell-restserver*/bin/docspell-restserver -J-Xmx1G -Djava.io.tmpdir=/path/to/othertemp -- /path/to/server-config.conf ``` The command: ``` $ ./docspell-restserver*/bin/docspell-restserver -h ``` gives an overview of supported options. It is recommended to run joex with the G1GC enabled. If you use java8, you need to add an option to use G1GC (`-XX:+UseG1GC`), for java11 this is not necessary (but doesn't hurt either). This could look like this: ``` ./docspell-joex-{{version()}}/bin/docspell-joex -J-Xmx1596M -J-XX:+UseG1GC -- /path/to/joex.conf ``` Using these options you can define how much memory the JVM process is able to use. This might be necessary to adopt depending on the usage scenario and configured text analysis features. Please have a look at the corresponding [section](@/docs/configure/file-processing.md#memory-usage). # Logging Docspell logs to stdout. This works well, when managed by systemd or similar tools. Logging can be configured in the configuration file or via environment variables. There are these settings: - `minimum-level` specifies the log level to control the verbosity. Levels are ordered from: *Trace*, *Debug*, *Info*, *Warn* and *Error* - `format` this defines how the logs are formatted. There are two formats for humans: *Plain* and *Fancy*. And two more suited for machine consumption: *Json* and *Logfmt*. The *Json* format contains all details, while the others may omit some for readability - `levels` optional _logger name_ to _level_ mappings to override the log level for specific loggers. If not mentioned here, everything is logged with `minimum-level`. The default settings for joex and restserver are the same and configure a minimum level of `Warn` and override some loggers with `Info`. # Default Config ## Rest Server {{ incl_conf(path="templates/shortcodes/server.conf") }} ## Joex {{ incl_conf(path="templates/shortcodes/joex.conf") }} ## Environment Variables Environment variables can be used when there is no config file supplied. The listing below shows all possible variables and their default values. {{ incl_conf(path="templates/shortcodes/config.env.txt") }}