Configuration

Configuration files

Specifying the configuration files is optional; without them the processes run with the default configuration.

restheart-platform-core and restheart-platform-security are configured via configuration and properties files. Configuration files can be parametric and merged with a set of properties to get the final values.

$ java -jar restheart-platform-core.jar <configuration-file> -e <properties-file>
$ java -jar restheart-platform-security.jar <configuration-file> -e <properties-file>

Note: properties files for restheart-platform-security are available starting from Platform release 4.1.

It’s also possible to pass both the restheart-platform-core’s environment properties and configuration file respectively via the RESTHEART_ENVFILE and RESTHEART_CONFFILE environment variables or Java properties, for example:

$ export RESTHEART_ENVFILE=etc/restheart-platform-core.yml
$ export RESTHEART_CONFFILE=etc/core.properties

For RESTHeart Security use the equivalent RESTHEART_SECURITY_CONFFILE environment variable or Java property.

The RESTHeart Platform the configuration files are under the etc/ folder.

Core configuration

Security configuration

The configuration files are documented in details with inline comments.

Be aware that before 4.1.10 the properties files have a slightly different names (e.g. etc/core-bwcv3.properties was called etc/bwcv3.properties).

Updating configuration in Docker containers

The configuration files used by the Docker containers are:

• etc/restheart-platform-core.yml
• etc/restheart-platform-security.yml

The properties files used by the Docker containers are:

• etc/core-docker.properties
• etc/security-docker.properties

Important if a configuration or property file is modified, the containers must be rebuilt for changes to take effect:

$ docker-compose up --build

Important configuration options

The following tables highlights the most important configuration options.

Core

All the important configuration options of resthart-platform-core are defined in the properties file.

For security reasons RESTHeart by default binds only on localhost, so it won’t be reachable from external systems unless you edit the configuration. To accept connections from everywhere, you must set the listeners host to 0.0.0.0.

Security

Parametric configuration

Until version 4.0, only restheart-platform-core.yml can make use of parameters. This feature has also been extended to restheart-platform-security.yml starting from version 4.1.

It is possible to pass an optional properties file (following the Java Properties syntax) as a startup parameter, via a OS environment variable or via a Java property (which you can pass to the JVM with the “-D” command line parameter).

This has proven to be very useful when RESTHeart is deployed in several environments and the configuration files are just slightly different among the environments. In the past was necessary to copy and paste any modification on all the YAML configuration files, but now you can have a single parametric YAML file, with a set of small, different properties files for each environment.

For example, the core.properties file in etc/ folder contains the following properties:

## RESTHeart Configuration - development properties.
# Documentation: https://restheart.org/docs/v4/configuration

https-listener = false
https-host = localhost
https-port = 4443

http-listener = true
http-host = localhost
http-port = 8081

ajp-listener = true
ajp-host = localhost
ajp-port = 8009

instance-name = default
instance-base-url = http://localhost:8080

default-representation-format = STANDARD

mongo-uri = mongodb://127.0.0.1

# The MongoDB resource to bind to the root URI /
# The format is /db[/coll[/docid]] or '*' to expose all dbs
root-mongo-resource = /restheart

enable-log-console: true
log-level = INFO
enable-log-file: false
# with --fork use an absoulte path of a writable file
log-file-path: /var/log/restheart-platform-core.log

query-time-limit = 0
aggregation-time-limit = 0

#suggested value: core*2
io-threads: 4
#suggested value: core*16
worker-threads: 32

The restheart-platform-core.yml file contains the above parameters, expressed with the “Mustache syntax” (triple curly braces to indicate parametric values). Have a look at the below fragment for an example:

instance-name: {{{instance-name}}}

https-listener: {{{https-listener}}}
https-host: {{{https-host}}}
https-port: {{{https-port}}}

http-listener: {{{http-listener}}}
http-host: {{{http-host}}}
http-port: {{{http-port}}}

ajp-listener: {{{ajp-listener}}}
ajp-host: {{{ajp-host}}}
ajp-port: {{{ajp-port}}}

default-representation-format: {{{default-representation-format}}}

mongo-uri: {{{mongo-uri}}}

Beware that you must stop and run RESTHeart again to reload a new configuration.

Of course, you can decide which values in ``restheart-platform-core.yml` you want to become parametric or you can just use a static file.

To start RESTHeart and provide it with a properties file pass the --envfile command line parameter:

$ java -jar restheart-platform-core.jar etc/restheart-platform-core.yml --envfile etc/core.properties

Alternatively, pass the envfile path via RESTHEART_ENVFILE environment variable:

$ export RESTHEART_ENVFILE=etc/core.properties
$ java -jar restheart-platform-core.jar etc/restheart-platform-core.yml

This approach allows to share one single configuration file among several environments. For example, one could create core-dev.properties, core-test.properties and core-production.properties, one for each environment, with one single common restheart-platform-core.yml configuration file.

Environment variables

Is is possible to override any primitive type parameter in restheart-platform-core.yml with an environment variable. Primitive types are:

• String
• Integer
• Long
• Boolean

For example, the parameter mongo-uri in the YAML file can be overridden by exporting a MONGO_URI environment variable:

$ export MONGO_URI="mongodb://127.0.0.1"

The following log entry appears at the very beginning of logs during the startup process:

[main] WARN  org.restheart.Configuration - >>> Overriding parameter 'mongo-uri' with environment value 'MONGO_URI=mongodb://127.0.0.1'

A shell environment variable is equivalent to a YAML parameter in restheart-platform-core.yml, but it’s all uppercase and '-' (dash) are replaced with '_' (underscore).

Remember: environment variables replacement doesn’t work with YAML structured data in configuration files, like arrays or maps. You must use properties files and mustache syntax for that.

Command line parameters

To know the available CLI parameters, run RESTHeart with --help:

$ java -jar target/restheart.jar --help
Usage: java -Dfile.encoding=UTF-8 -jar -server restheart.jar [options]
      <Configuration file>
  Options:
    --envFile, --envfile, -e
      Environment file name
    --fork
      Fork the process
      Default: false
    --help, -?
      This help message