v8 v7 v6 v5 v4 v3
Edit Page

Configuration

Update the admin password!

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

Warning
 YOU MUST UPDATE THE DEFAULT PASSWORD! The role admin can execute any request as it is set as the root role in the mongoAclAuthorizer configuration.

To update it, run the following command:

$ curl -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 has a default configuration and specifying a configuration file is not required.

The following command runs RESTHeart with the default configuration.

$ java -jar restheart.jar

The following 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 is fine most of the times. You just want to change few options and the suggested way is using the default configuration with the needed overrides.

Modify the configuration with the RHO env var

The environment variable RHO allows 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 than RHO` env 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

The configuration of RESTHeart running in a Docker container can be modified 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, just can 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, just can 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