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 here. 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 for more on this.

File Format🔗

The format of the configuration files can be HOCON, JSON or what this config library understands. The default values below are in HOCON format, which is recommended, since it allows comments and has some advanced features. 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.

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-0.42.0
/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.

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.