Looking for Cloud Services or Professional Support? Check restheart.com

v7 v6 v5 v4 v3
Edit Page

Setup with Docker

The RESTHeart Docker tags

RESTHeart Docker images come in four different versions:

  • Standard multi-arch (FROM eclipse-temurin:17-jre)

  • Graalvm (FROM softinstigate/graalvm:latest)

  • distroless (FROM gcr.io/distroless/java17-debian11:latest)

  • native (FROM debian:bookworm-slim)

These are example tags:

Tag

Example

Description

<version>

latest, 7, 7.5, 7.5.0

The standard image. This is usually the one you want to use. Keep in mind it doesn’t support running JavaScript plugins. docker pull softinstigate/restheart:latest

<version>-distroless

latest-distroless, 7-distroless, 7.5-distroless, 7.5.0-distroless

Similar to the standard image, this image contains only RESTHeart and its runtime dependencies. It does not contain a package manager, shells or any other programs you would expect to find in a standard Linux distribution. docker pull softinstigate/restheart:latest-distroless

<version>-graalvm

latest-graalvm, 7-graalvm, 7.5-graalvm, 7.5.0-graalvm

RESTHeart running on the GraalVM that will let you JavaScript plugins. Check out the Plugins in JavaScript for more info. This is the biggest image (about 600Mbytes). docker pull softinstigate/restheart:latest-graalvm

<version>-native

latest-native, 7-native, 7.5-native, 7.5.0-native

RESTHeart built as a native binary. It is the smallest image with lightning-fast startup time. This is the perfect choice for deploying in a Kubernetes cluster. It can only execute JavaScript plugins. Check out Deploy Java plugins on RESTHeart Native for more info. docker pull softinstigate/restheart:latest-native

Run RESTHeart with Docker in standalone mode

Note
 standalone mode is available from RESTHeart 7.2

When you run RESTHeart in standalone mode, it switches to a different default configuration that turns off all plugins that rely on MongoDB. This means you won’t have access to the handy built-in features that make RESTHeart so great. But don’t worry, you’ll still be able to play with it and add your own custom plugins.

On OSX and Windows:

$ docker run -p 8080:8080 -e RHO="/fileRealmAuthenticator/users[userid='admin']/password->'secret';/http-listener/host->'0.0.0.0'" softinstigate/restheart -s

On Linux

$ docker run -p 8080:8080 -e RHO="/fileRealmAuthenticator/users[userid='admin']/password->'secret';/http-listener/host->'0.0.0.0'" softinstigate/restheart -s
Note
 the RHO environment variable sets the password for the user admin.

Run RESTHeart with Docker, MongoDB running on localhost

If MongoDB is not already running, the following command will start a replica set and initiate it (the replica set is not required but enables RESTHeart to support transactions and change streams). Note that the data path is /tmp/db.

$ mkdir -p /tmp/db && mongod --fork --syslog --replSet=foo -dbpath=/tmp/db && mongo --eval 'if (!rs.status().ok) rs.initiate();'

Run RESTHeart with:

On OSX and Windows:

$ docker run --rm -p "8080:8080" softinstigate/restheart

On Linux

$ docker run --rm -p "8080:8080" --add-host host.docker.internal:host-gateway softinstigate/restheart
Note
 This command relies on the docker support of host.docker.internal. If you are using an old docker version or a docker runtime that does not support it, than you need to configure the docker network accordingly (you can refer to the brilliant "From inside of a Docker container, how do I connect to the localhost of the machine?" on StackOverflow) or use one of the an alternative methods described in the further sections.

Run with docker-compose

To run both RESTHeart and MongoDB services you can use docker compose. Just copy and paste the following shell command:

$ curl https://raw.githubusercontent.com/SoftInstigate/restheart/master/docker-compose.yml --output docker-compose.yml
$ docker compose up
Tip
 Watch Docker / Docker Compose video.

Run both RESTHeart and MongoDB with Docker

1) Create a Docker network:

$ docker network create restheart-network

2) Run a MongoDB container

$ docker run -d --name mongodb --network restheart-network mongo:5.0

3) Run a RESTHeart container

$ docker run -d --rm --network restheart-network -p "8080:8080" -e RHO='/mclient/connection-string->"mongodb://mongodb"' softinstigate/restheart
$ http -b http://localhost:8080/ping

Greetings from RESTHeart!

Dockerfile

The "distroless" images are for special deployment requirements, where having the smallest possible image size and the very minimal security attack surface is required and their tag contains a distroless label. You usually don’t need these images unless you exactly know what you are doing.

Images tags ending with -native are created with the GraalVM Native Image technology starting from stable builds of the product, especially suited for high demanding environments, like Kubernetes. These are experimental and not fully documented yet, please contact us for questions.

What’s next