How to run RESTHeart 3 with Docker
Quick Start with Docker Compose
- If something is not working
- Modify the configuration for the RESTHeart container
Docker Image
Stop and restart

Docker

How to run RESTHeart 3 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.

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 https://raw.githubusercontent.com/SoftInstigate/restheart/3.11.x/docker-compose.yml --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:

localhost:8080/browser

NOTE: The HAL browser has been removed from RESTHeart 4, these instructions are for RESTHeart 3 only.

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         ./entrypoint.sh etc/resthe ...   Up      4443/tcp, 0.0.0.0:8080->8080/tcp
restheart-mongo   docker-entrypoint.sh --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 logs -f restheart
$ docker logs -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 https://raw.githubusercontent.com/SoftInstigate/restheart/master/Docker/etc/restheart.yml --output etc/restheart.yml
$ curl https://raw.githubusercontent.com/SoftInstigate/restheart/master/Docker/etc/security.yml --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
      volumes:
         - ./etc:/opt/restheart/etc:ro

Restart the containers:

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

Docker Image

Dockerfile

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