Public | Automated Build

Last pushed: 5 days ago
Short Description
RESTHeart, the REST API server for MongoDB.
Full Description

Docker image for RESTHeart

The latest stable release is 3.1

Note: this isn't anymore an automated build, images and tags are created and uploaded directly by Travis-CI during the Continuous Integration process.

Unfortunately the Docker Hub doesn't allow to re-link to a different Github repository, now images are created from here.


For 3.x.x tags the new Dockerfile is

FROM openjdk:8u111-jre-alpine

MAINTAINER SoftInstigate <>

RUN apk upgrade --update && apk add --update libstdc++ curl ca-certificates bash

WORKDIR /opt/restheart
COPY etc/* /opt/restheart/etc/
COPY /opt/restheart/
COPY restheart.jar /opt/restheart/

CMD ["etc/restheart.yml"]
EXPOSE 8080 4443


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 mongouri.

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 80:8080 --name restheart -v "$PWD"/etc:/opt/restheart/etc:ro softinstigate/restheart:3.0.3

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

1) Pull the MongoDB and RESTHeart images

  1. docker pull mongo:3.2
  2. docker pull softinstigate/restheart:3.0.3

We recommend to pull a specific MongoDB image, for example docker pull mongo:3.2. RESTHeart has been tested so far with MongoDB 2.6, 3.0, 3.2 and 3.4.

2) Run the MongoDB container

docker run -d --name mongodb mongo:3.2

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.2

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.

3) Run RESTHeart interactively

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

However, you will usually run it in background:

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

4) Check that is working:

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

docker logs restheart

5) 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:3.0.3 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:3.0.3 etc/restheart.yml -Dkey=value

Use docker-compose


RESTHeart fully embraces a microservices architecture. The quickest way to run RESTHeart + MongoDB both as docker containers is to use docker-compose.

The file docker-compose.yml defines a single microservice made of a RESTHeart and MongoDB instance configured to work together.
To start both services just type:

$ docker-compose up -d

Check that everything is fine:

$ docker-compose ps

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

Tail the logs of both services:

$ docker-compose logs -f

You can now create a database with curl or httpie

$ http -j -a admin:changeit PUT

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ETag, Auth-Token, Auth-Token-Valid-Until, Auth-Token-Location, X-Powered-By
Auth-Token: 7275cf59-4b51-4a44-aa34-f393c617bd16
Auth-Token-Location: /_authtokens/admin
Auth-Token-Valid-Until: 2016-06-11T09:08:50.859Z
Connection: keep-alive
Content-Length: 0
Date: Sat, 11 Jun 2016 08:53:50 GMT
ETag: 575bd19efca13600050d9581

GET the testdb

$ http -a admin:changeit

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ETag, Auth-Token, Auth-Token-Valid-Until, Auth-Token-Location, X-Powered-By
Auth-Token: 7275cf59-4b51-4a44-aa34-f393c617bd16
Auth-Token-Location: /_authtokens/admin
Auth-Token-Valid-Until: 2016-06-11T09:11:14.843Z
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 113
Content-Type: application/hal+json
Date: Sat, 11 Jun 2016 08:56:14 GMT
ETag: 575bd0fefca13600050d957d

    "_etag": {
        "$oid": "575bd0fefca13600050d957d"
    "_id": "testdb", 
    "_returned": 0, 
    "_size": 0, 
    "_total_pages": 0

See our API Tutorial for more.

Accessing the HAL Browser


Whenever the browser asks for credentials then use the following:

username: admin
password: changeit

Stop and start again

To stop the RESTHeart background daemon just issue

docker stop restheart

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

You can start it again with

docker start restheart

but it's not recommended: RESTHeart is a stateless service, best Docker practices would 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 if you delete it then you'll lose all data unless you attached to it a persistent volume. In this case you might prefer to start it again, so that your data is preserved, or ypu might prefer to attach a local Docker Volume to it.

To stop MongoDb issue

docker stop mongodb

To start MongoDb again

docker start mongodb

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

Next Steps

When you containers are up and running you can go to the official RESTHeart's Documentation.

Docker Pull Command
Source Repository

Comments (1)
17 days ago

The default config file for 3.1.3 image is incorrect. It probably comes from an older restheart version though the Dockerfile looks fine.
For me the problem is that the Checker interface is configured with outdated package. It is org.restheart.hal.metadata.singletons.Checker and it should be org.restheart.metadata.checkers.Checker.