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.

Note	`mongoAclAuthorizer` is the default ACL authorizer from RESTHeart starting v6.2. For previous releases, the `fileAclAuthorizer` was used. In this case the user password must be updated in the file `etc/users.yml`.

Configuration files

The main configuration file is restheart.yml which is parametrized using the {{{my-parameter}}} notation. The default.properties contains actual values for parameters defined into the YAML file. You pass these properties at startup, using the -e or --envFile parameter, like this:

$ java -jar restheart.jar etc/restheart.yml -e etc/default.properties

Tip

To connect RESTHeart to a remote MongoDB instance you have to edit the mongo-uri property, setting you own Connection String. For example, a MongoDB Atlas cluster connection string could be something like mongodb+srv://<username>:<password>@cluster0.mongodb.net/test?w=majority. Remember that RESTHeart internally uses the MongoDB Java driver, so you must follow that connection string format.

You have to restart the core restheart.jar process to reload a new configuration. How to stop and start the process depends on how it was started: either within a docker container or as a native Java process. In case of native Java, usually you have to kill the background java process but it depends on your operating system.

You can edit the YAML configuration file or create distinct properties file. Usually one set of properties for each deployment environment is a common practice.

Environment variables

It is possible to override any primitive type parameter in restheart.yml with environment variables.

Primitive types are:

String
Integer
Long
Boolean

The name of the shell environment variable is equal to a YAML parameter in restheart.yml, in uppercase and replacing - (dash) with _ (underscore).

To avoid conflicts with other variables, the environment variable name can be prefixed with RH_, RESTHEART_ or the legacy RESTHEART_SECURITY_ .

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

$ MONGO_URI="mongodb://127.0.0.1" java -jar restheart.jar etc/restheart.yml -e etc/default.properties

Tip	Have a look at the docker-compose.yml file for an example of how to export an environment variable if using Docker.

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'

Warning

Environment variables replacement works only with primitive types: it doesn’t work with YAML structured data in configuration files, like arrays or maps. It’s mandatory to use properties files and mustache syntax for that.

Tip	Watch Configuration video.

Change the configuration in Docker container

The configuration file restheart.yml and property file default.properties can modified in two ways.

If the configuration property to be changes is a scalar, you can use environment variables.

The following example uses -e RH_INSTANCE_NAME="the-best-api-ever" to override the configuration parameter instance-name.

$ docker run -d --rm  -p "8080:8080" -e RH_MONGO_URI='mongodb://host.docker.internal' -e RH_INSTANCE_NAME="the-best-api-ever" softinstigate/restheart

19:50:55.640 [main] WARN  org.restheart.Configuration - >>> Found environment variable 'RH_INSTANCE_NAME': overriding parameter 'instance-name' with value 'the-api'
 19:50:55.656 [main] INFO  org.restheart.Bootstrapper - Starting RESTHeart instance the-api-best-api-ever
 .....

If the property to be changed is of a complex type, the configuration file or properties file must be overridden with a Docker volume.

The following command overrides the property file in the container with the file /host/path/to/default.properties in the host machine.

$ docker run --rm -p 8080:8080 -e RH_MONGO_URI='mongodb://host.docker.internal' -v /host/path/to/default.properties:/opt/restheart/etc/default.properties softinstigate/restheart