Run RESTHeart with Docker

Note that you need to know a bit of Docker and Docker Compose to follow these instructions. Alternatively, you can scroll down and read how to run RESTHeart directly on a server.

Docker is the best way to run RESTHeart.

Docker Stars Docker Pulls

PLease help us improving this documentation: if you encounter a problem, something you don’t understand or a typo, use this link to ask a question. You could also open a PR to directly fix the documentation on Github, if you want.

Quick Start with Docker Compose

Nothing is easier and faster than Docker Compose to run RESTHeart and MongoDB. However, this is neither a docker nor a docker-compose tutorial, so please refer to the official documentation.

Download the example docker-compose.yml

$ mkdir restheart && cd restheart
$ curl --output docker-compose.yml

The file docker-compose.yml defines a single micro-service made of a RESTHeart instance on port 8080 and a MongoDB instance configured to work together.

Start both services just typing:

$ docker-compose up -d

Open the the following URL:


Insert the default admin credentials, which are:

username: admin
password: changeit

You should then see the HAL Browser:

Note that by default docker-compose runs the latest RESTHeart release, which usually is a SNAPSHOT. If this is not what you want, then edit the docker-compose.yml file accordingly.

If everything is working as expected, then you can jump to the tutorial.

If something is not working

Check that docker containers are both up and running:

$ docker-compose ps

    Name                    Command               State                Ports
restheart         ./ etc/resthe ...   Up      4443/tcp,>8080/tcp
restheart-mongo --bin ...   Up      27017/tcp

Then you can tail the logs of both services, to spot any error:

$ docker-compose logs -f

Or you could tail the logs of individual services:

$ docker log -f restheart
$ docker log -f restheart-mongo

Modify the configuration for the RESTHeart container

Download the configuration files restheart.yml and security.yml in the etc directory.

$ mkdir etc
curl --output etc/restheart.yml
$ curl --output etc/security.yml

Edit the configuration files as needed. For instance, to change the admin user password edit etc/security.yml as follows:

    - userid: admin
      password: <your-password-here>
      roles: [users, admins]

Uncomment the following line in docker-compose.yml

      ### Uncoment below if you want to mount a local configuration folder
      ### to overwrite default restheart.yml and/or security.yml
         - ./etc:/opt/restheart/etc:ro

Restart the containers:

$ docker-compose stop
$ docker-compose up -d

Docker Image


The latest tag is automatically associated with SNAPSHOT maven builds on master branch. If you really want to run a stable docker image, please always pull a exact tag, like:

$ docker pull softinstigate/restheart:<tag>


  • The Dockefile is here.

How to Run

This section is useful if you want to run RESTHeart with docker but you already have an existing MongoDB container to connect to. Note that if instead you want to connect to a remote MongoDB instance then you must edit the restheart.yml configuration file and change the mongo-uri.

mongo-uri: mongodb://<remote-host>

You can then decide to rebuild the container itself with your version of this file or mount the folder as a volume, so that you can override the default configuration files. For example:

$ docker run -d -p 8080:8080 --name restheart -v "$PWD"/etc:/opt/restheart/etc:ro softinstigate/restheart

We strongly recommend to always add the tag to the image (e.g. softinstigate/restheart:<tag>), so that you are sure which version of RESTHeart you are running.

Pull the MongoDB and RESTHeart images

$ docker pull mongo:3.6
$ docker pull softinstigate/restheart:<tag>

Run the MongoDB container

If you are running RESTHeart 3.3 and above (latest tag) then MongoDB authentication is enabled by default and you must start the mongo container passing the admin username and password via command line:

$ docker run -d -e MONGO_INITDB_ROOT_USERNAME='restheart' -e MONGO_INITDB_ROOT_PASSWORD='R3ste4rt!' \
 --name mongodb mongo:3.6 --bind_ip_all --auth

If you change the MONGO_INITDB_ROOT_USERNAME or MONGO_INITDB_ROOT_PASSWORD then you need to change the mongo-uri in Docker/etc/restheart.yml accordingly and re-build the Docker image.

    mongo-uri: mongodb://restheart:R3ste4rt!@mongodb

RESTHeart < 3.3

If you are running RESTHeart 3.2 or below.

$ docker run -d --name mongodb mongo:3.6

To make it accessible from your host and add a persistent data volume:

$ docker run -d -p 27017:27017 --name mongodb -v <db-dir>:/data/db mongo:3.6

The <db-dir> must be a folder in your host, such as /var/data/db or whatever you like. If you don’t attach a volume then your data will be lost when you delete the container.

Run RESTHeart interactively

Remember to add always add an explicit tag to the image, as the latest tag is bound to SNAPSHOT releases and could be unstable.

Run in foreground, linking to the mongodb instance, mapping the container’s 8080 port to the 80 port on host:

$ docker run --rm -i -t -p 80:8080 --name restheart --link mongodb softinstigate/restheart

However, you will usually run it in background:

$ docker run -d -p 80:8080 --name restheart --link mongodb softinstigate/restheart

Check that is working

If it’s running in background, you can open the RESTHeart’s logs:

$ docker logs restheart

Pass arguments to RESTHeart and JVM

You can append arguments to docker run command to provide RESTHeart and the JVM with arguments.

For example you can mount an alternate configuration file and specify it as an argument

$ docker run --rm -i -t -p 80:8080 -v my-conf-file.yml:/opt/restheart/etc/my-conf-file.yml:ro --name restheart --link mongodb:mongodb softinstigate/restheart my-conf-file.yml

If you want to pass system properties to the JVM, just specify -D or -X arguments. Note that in this case you need to provide the configuration file as well.

    docker run --rm -i -t -p 80:8080 --name restheart --link mongodb:mongodb softinstigate/restheart etc/restheart.yml -Dkey=value

Stop and restart

To stop the RESTHeart background daemon:

$ docker stop restheart

or simply press CTRL-C if it is running in foreground.

Restart it with:

$ docker start restheart

note: RESTHeart is a stateless service; best Docker practices suggest to just delete the stopped container with docker rm restheart or to run it in foreground with the --rm parameter, so that it will be automatically removed when it exits.

The MongoDB container instead is stateful, so deleting leads to lose all data unless you attached a persistent Docker Volume.

To stop MongoDb:

$ docker stop mongodb

Restart it with:

$ docker start mongodb

Note that you must always stop RESTHeart before MongoDB, or you might experience data losses.

Manual installation

This section is about installing and configuring RESTHeart on “bare metal”, without Docker. It’s recommended only if you know well RESTHeart already and have very specific requirements.

If you don’t have them already, download the following packages:

Most of the work must be done using a command line interface.

RESTHeart works with Java versions from 8 to 11.

Install Java and MongoDB

Install Java 8 and MongoDB following the instructions for your specific operating system and make sure that their binaries are actually executable (so they are in your PATH env variable).

To check Java and MongoDB, you should execute the following commands and you should get something like the below (output might vary depending on Java, your OS and MongoDB versions):

$ java -version
java version "1.8.0_151"
Java(TM) SE Runtime Environment (build 1.8.0_151-b12)
Java HotSpot(TM) 64-Bit Server VM (build 25.151-b12, mixed mode)

$ mongod --version
db version v4.0.4

RESTHeart has been tested with MongoDB from version 2.4 to 4.0. More recently, integration tests are executed against versions 3.6 and 4.0.

Install RESTHeart

To install RESTHeart download the latest stable release package from github and just extract its the content in the desired directory.

You are interested in three files:

  • restheart.jar
  • etc/restheart.yml <- an example configuration file
  • etc/

Start MongoDB

In pursuit of simplicity we are first going to start MongoDB without enabling authentication. We’ll see later how to enable it.

You can just start MongoDB by running the mongod command from a shell prompt. It is configured by default to use the /data/dbfolder, which must exist already or you have to create it beforehand. If you do not want to use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option: mongod --dbpath <path to data directory>. You might prefer to run the MongoDB process in background, using the --fork parameter: mongod --fork --syslog:

$ mongod --fork --syslog
about to fork child process, waiting until server is ready for connections.
forked process: 11471
child process started successfully, parent exiting

# By default MongoDB starts listening for connections on

Run RESTHeart

As a quick-start, RESTHeart can be run without any external configuration file, only with its own internal default values. That tries connecting to a MongoDB instance running on the localhost:27017 mongo-uri:

$ java -Dfile.encoding=UTF-8 -server -jar restheart.jar

18:51:31.346 [main] WARN  org.restheart.Bootstrapper - No configuration file provided, starting with default values!
18:51:31.435 [main] INFO  org.restheart.Bootstrapper - Starting RESTHeart
    "Version": "3.7.0-SNAPSHOT",
    "Instance-Name": "default",
    "Configuration": "null",
    "Environment": "null",
    "Build-Time": "2019-01-22T17:39:01Z"
18:51:31.439 [main] INFO  org.restheart.Bootstrapper - Logging to file /var/folders/pk/56szmnfn5zlfxh2x6tkd5wqw0000gn/T/restheart.log with level INFO
18:51:31.439 [main] INFO  org.restheart.Bootstrapper - Logging to console with level INFO
18:51:31.819 [main] INFO  org.restheart.Bootstrapper - MongoDB connection pool initialized
18:51:31.819 [main] INFO  org.restheart.Bootstrapper - MongoDB version 3.6.7
18:51:31.819 [main] WARN  org.restheart.Bootstrapper - MongoDB is a standalone instance, use a replica set in production
18:51:31.819 [main] WARN  org.restheart.Bootstrapper - ***** No Identity Manager specified. Authentication disabled.
18:51:31.819 [main] WARN  org.restheart.Bootstrapper - ***** No access manager specified. users can do anything.
18:51:31.819 [main] INFO  org.restheart.Bootstrapper - Authentication Mechanism enabled
18:51:31.819 [main] INFO  org.restheart.Bootstrapper - Token based authentication enabled with token TTL 15 minutes
18:51:31.824 [main] INFO  org.restheart.Bootstrapper - HTTPS listener bound at
18:51:31.824 [main] INFO  org.restheart.Bootstrapper - HTTP listener bound at
18:51:31.825 [main] INFO  org.restheart.Bootstrapper - Local cache for db and collection properties enabled with TTL 1000 msecs
18:51:31.826 [main] INFO  org.restheart.Bootstrapper - Local cache for schema stores not enabled
18:51:31.961 [main] INFO  org.restheart.Bootstrapper - URL / bound to MongoDB resource *
18:51:32.047 [main] INFO  org.restheart.Bootstrapper - Embedded static resources browser extracted in /var/folders/pk/56szmnfn5zlfxh2x6tkd5wqw0000gn/T/restheart-7196941146163994258
18:51:32.055 [main] INFO  org.restheart.Bootstrapper - URL /browser bound to static resources /var/folders/pk/56szmnfn5zlfxh2x6tkd5wqw0000gn/T/restheart-7196941146163994258. Access Manager: false
18:51:32.076 [main] INFO  org.restheart.Bootstrapper - Allow unescaped characters in URL: true
18:51:32.244 [main] INFO  org.restheart.Bootstrapper - Pid file /var/folders/pk/56szmnfn5zlfxh2x6tkd5wqw0000gn/T/
18:51:32.244 [main] INFO  org.restheart.Bootstrapper - RESTHeart started

This default configuration is fine for MongoDB running on localhost, on default port and without any authentication.

Configuration options can be specified passing a configuration file and configuration properties as arguments.

$ java -Dfile.encoding=UTF-8 -server -jar restheart.jar restheart.yml --envFile

The configuration file path is either absolute or relative to the restheart.jar file location.

The configuration file can specify any option that will overwrite the default value: this way it is not required to specify all the possible options in the configuration file following a convention over configuration approach.

For more information about the configuration file format refer to Default Configuration File section.

On Linux, OSX and Solaris you can run RESTHeart as a daemon process

$ java -Dfile.encoding=UTF-8 -server -jar restheart.jar restheart.yml --envFile --fork

Note that this will force the console logging and the file logging to be turned off and on respectively, regardless the specified log configuration options.

We’ll now use the embedded HAL browser to check that everything is fine. The HAL browser allows you to surf the DATA API with your regular Web browser.

To see the HAL user interface, now open your browser at:

Enable MongoDB authentication

This section assumes using MongoDB 3.2 or later. For other versions, the security configuration is similar but different. Refer to the MongoDB documentation for more information.

Start MongoDB with authentication and connect to the MongoDB instance from a client running on the same system. This access is made possible by the localhost exception. Again, you might prefer to run the MongoDB process in background, using the --fork parameter.

$ mongod --fork --syslog --auth
$ mongo

In this section we will use the MongoDB superuser role root that provides access to the all operations and all the resources.

However the best practice is to use a MongoDB user with restricted access. For instance, it could be restricted to use only a single DB in read only mode. For more information refer to MongoDB authentication with just enough permissionssection.

Create the admin user. The procedure is different depending on MongoDB version.

> use admin
> db.createUser({
    user: "admin",
    pwd: "changeit",
    roles:[ "root" ]
We need to provide the MongoDB user authentication credentials in the RESTHeart configuration file: see docs. 

We’ll use the restheart.yml example configuration file that comes with RESTHeart download package (you find it in the etc directory)

$ vi etc/restheart.yml

Find and modify the following section providing the user-name, password and authentication db (the db where the MongoDB user is defined, in our case ‘admin’).

    mongo-uri: mongodb://admin:changeit@

Now start RESTHeart specifying the configuration file:

$ java -Dfile.encoding=UTF-8 -server -jar restheart.jar etc/restheart.yml

Test the connection opening the HAL browser at

Note that the example configuration file etc/restheart.yml also enables the RESTHeart security. Opening the HAL browser page, you’ll be asked to authenticate. You can use of one of the credentials defined in etc/security.yml file (try username = ‘a’ and password = ‘a’).

Connect RESTHeart to MongoDB over TLS/SSL

MongoDB clients can use TLS/SSL to encrypt connections to mongod and mongos instances.

To configure RESTHeart for TLS/SSL do as follows:

  • create the keystore importing the public certificate used by mongod using keytool (with keytool, the java tool to manage keystores of cryptographic keys)
$ keytool -importcert -file mongo.cer -alias mongoCert -keystore rhTrustStore

# asks for password, use "changeit"
  • specify the ssl option in the mongo-uri in the restheart yml configuration file:
    mongo-uri: mongodb://
  • start restheart with following options:
$ java -Dfile.encoding=UTF-8 -server -jar restheart.jar restheart.yml

MongoDB authentication with just enough permissions

In the previous examples we used a MongoDB user with root role for the sake of simplicity. This allows RESTHeart to execute any command on any MongoDB resource.

On production environments a strong security isolation is mandatory.

In order to achieve it, the best practice is:

  1. use the mongo-mounts configuration option to restrict the resources exposed by RESTHeart;
  2. use a MongoDB user with just enough roles: read or readWrite on mounted databases 

The following example, creates a MongoDB user with appropriate roles to expose the databases db1, db2 and db3 in read only mode.

> use admin
> db.createUser({user: "mongousr",
    pwd: "secret",
    roles: [{role: "readWrite", db: "db1"},
            {role: "readWrite", db: "db2"},
            {role: "read", db: "db3"}

To list the databases (i.e. GET /, the root resource) the listDatabases permission is needed. This permission is granted by the readWriteAnyDatabase role or you can create a custom role.

To allow deleting a database the dropDatabase permission is needed. This permission is granted by the dbAdmin role or you can create a custom role.