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

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

file description
etc/restheart-platform-core.yml parametric configuration file
etc/ default parameters values
etc/ run restheart-platform-core without restheart-platform-security
etc/ run restheart-platform-core in backward compatibility mode
etc/ used by the Docker container

Security configuration

file description
etc/restheart-platform-security.yml parametric configuration file
etc/ default parameters values
etc/ used by the Docker container

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/ was called etc/

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/
  • etc/

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.


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

property default description
Listeners section ajp at localhost:8009 listeners allow to specify the protocol, ip, port and to use
instance-name default name of this instance of resthart-platform-core
default-representation-format STANDARD representation format to use in case the rep query parameters is not specified
mongo-uri mongodb:// the MongoDB connection string
root-mongo-resource /restheart MongoDB resource to bind to the root URI /
log-level DEBUG log level
query-time-limit 0 (no limit) kill request with slow queries
aggregation-time-limit 0 (no limit) kill slow aggregations requests
io-threads 4 number of io thread, suggested value: core*2
worker-threads 16 number of worker threads, suggested value: core*16

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


section default value description
Listeners https at and http at value Listeners allow to specify the protocol, ip, port and to use
Proxied resources ajp:// The URL of restheart-platform-core and of any other proxied resource
SSL Configuration Use the insecure test self-signed certificate Allow configuring the certificate to be used by the https listener

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 file in etc/ folder contains the following properties:

## RESTHeart Configuration - development properties.
# Documentation:

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://

# 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/

Alternatively, pass the envfile path via RESTHEART_ENVFILE environment variable:

$ 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, and, 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://"

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://'

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>
    --envFile, --envfile, -e
      Environment file name
      Fork the process
      Default: false
    --help, -?
      This help message