v8 v7 v6 v5 v4 v3
Edit Page

Configuration RESTHeart

Update the admin password!

On first startup, RESTHeart creates the user admin with the default password secret. This user can execute any request.

Warning
 YOU MUST UPDATE THE DEFAULT PASSWORD! The admin role can execute any request because it’s configured as the root role in mongoAclAuthorizer.

To update it, run the following command:

$ curl -i -u admin:secret -X PATCH localhost:8080/users/admin -H "Content-Type: application/json" -d '{ "password": "my-strong-password" }'

Refer to User Management for more information on how to create new users, roles and permissions.

Default configuration

RESTHeart includes a default configuration, so you don’t need to specify a configuration file.

This command runs RESTHeart with the default configuration:

$ java -jar restheart.jar

This command prints the default configuration to the console:

$ java -jar restheart.jar -t

Configuration file

RESTHeart can also use a configuration file:

$ java -jar restheart.jar -t 2> restheart.yml # generate a configuration file with default values
$ java -jar restheart.jar restheart.yml
Note
 The default configuration works well in most cases. If you need to change a few options, the recommended approach is using the default configuration with the necessary overrides.

Modify the configuration with the RHO env var

The environment variable RHO allows you to modify and add any configuration option.

An example is:

$ RHO='/mclient/connection-string->"mongodb://127.0.0.1";/mongo/mongo-mounts[1]/where->"/api"' java -jar restheart.jar

or even:

$ RHO='/mclient/connection-string->"mongodb://127.0.0.1";/mongo/mongo-mounts[1]->{"where: "/api", "what": "mydb"}' java -jar restheart.jar

The following command with the -c option, prints the effective configuration, i.e. the default configuration with the RHO overrides applied.

$ RHO='/core/name->"***** test *****"' java -jar restheart.jar -c

INFO o.r.configuration.Configuration - Overriding configuration parameters from RHO environment variable:
INFO o.r.configuration.Configuration - /core/name -> ***** test *****

core: {name: '***** test *****', plugins-directory: plugins, base-url: null, io-threads: 0,
  worker-threads: -1, requests-limit: 1000, buffer-size: 16364, direct-buffers: true,
  force-gzip-encoding: false, allow-unescaped-characters-in-url: true}

The format is:

<xpath expression> -> JSON

The <xpath expression> selects the option to override or add.

So valid overrides are:

/core/name -> "production"
/mongo/mongo-mounts[1] -> {"where": "/api", "what": "mydb"}
/core/io-threads -> 8

The following are invalid:

/core/name -> production                     # missing quotes in JSON value
/mongo/mongo-mounts[1] -> {"where: "/api"    # invalid JSON object
core/io-threads -> 8                         # xpath expression does not start with /

Modify the configuration with an override file

A configuration override file can be specified with the -o option to modify the default configuration.

$ java -jar restheart.jar -o conf-overrides.conf
Tip
 the Example configuration files directory in the RESTHeart repository contains some examples in the different formats.

The override file can use four formats, .conf, .yml and .json, .jsonc (Json with comments).

Example override file in .conf format

This uses the same format as the RHO environment variable:

/core/name -> "default";
/http-listener -> {
    "enabled": true,
    "host": "localhost",
    "port": 8080
};

Example override file in .jsonc format

JSON format with keys as xpath expressions to select the options to override or add.

{
    "/core/name": "default",
    "/http-listener": {
        "enabled": true,
        "host": "localhost",
        "port": 8080
    }
}

Example override file in .yml format

YML format with keys as xpath expressions to select the options to override or add.

/core/name: default
/http-listener:
  enabled: true
  host: "localhost"
  port: 8080

Change the configuration in Docker container

You can modify the configuration of RESTHeart running in a Docker container in three ways.

1 - Using the RHO env variable

The following example uses the option -e RHO="…​" to override the configuration parameters /mclient/connection-string and /core/name.

$ docker run --rm  -p "8080:8080" -e RHO="/http-listener/host->'0.0.0.0';/mclient/connection-string->'mongodb://host.docker.internal';/core/name->'the-best-api-ever'" softinstigate/restheart

INFO  o.r.configuration.Configuration - Overriding configuration parameters from RHO environment variable:
INFO  o.r.configuration.Configuration - 	/http-listener/host -> 0.0.0.0
INFO  o.r.configuration.Configuration - 	/mclient/connection-string -> mongodb://host.docker.internal
INFO  o.r.configuration.Configuration - 	/core/name -> the-best-api-ever
.....
Note
 the RESTHeart Docker container defines the following RHO variable: 
ENV RHO='/mclient/connection-string->"mongodb://host.docker.internal";/http-listener/host->"0.0.0.0"'

When defining your RHO variable always set /http-listener/host→"0.0.0.0" and your /mclient/connection-string.

2 - Using a configuration override file

$ docker run --rm  -p "8080:8080" -e RHO="" -v /path/to/conf-overrides.conf:/opt/restheart/etc/conf-overrides.conf softinstigate/restheart -o etc/conf-overrides.conf

This mounts the host file /path/to/conf-overrides.conf into the container directory /opt/restheart/etc and executes RESTHeart with the -o option pointing to that file.

Warning
 RESTHeart Docker image defines the following RHO environment variable which has precedence over the configuration override file. To avoid the RHO of the Docker image to apply, you can add -e RHO="" to the docker run command. 
ENV RHO='/mclient/connection-string->"mongodb://host.docker.internal";/http-listener/host->"0.0.0.0"'

To avoid this, add -e RHO="" to your docker run command.

3 - Using a configuration file

The following commands add a configuration file to the container:

$ # generate the default configuration file in /tmp/restheart.yml (and edit it)
$ docker run --rm -p 8080:8080 -v /tmp/restheart.yml:/opt/restheart/etc/restheart.yml softinstigate/restheart -t 2> /tmp/restheart.yml

$ # run the RESTHeart container mounting the conf file as a volume
$ docker run --rm -p 8080:8080 -v /tmp/restheart.yml:/opt/restheart/etc/restheart.yml softinstigate/restheart etc/restheart.yml
Warning
 the RESTHeart Docker image defines the following RHO variable which will override the parameters in your configuration file: 
ENV RHO='/mclient/connection-string->"mongodb://host.docker.internal";/http-listener/host->"0.0.0.0"'

To avoid this, add -e RHO="" to your docker run command:

# generate a configuration file
$ docker run --rm -p 8080:8080  softinstigate/restheart -c 2> /tmp/restheart.yml
# run restheart with it
$ docker run --rm -p 8080:8080 -e RHO="" -v /tmp/restheart.yml:/opt/restheart/etc/restheart.yml softinstigate/restheart etc/restheart.yml