RESTHeart is a modern backend for Web and Mobile apps, designed to radically simplify server-side development and deployment.


To run RESTHeart you need:

  • Java 11 (alternatively, you can just run it with Docker).
  • MongoDB (or any API-compatible database).

RESTHeart can work with any database compatible with the MongoDB API. It has been tested with MongoDB Community and Enterprise (v2, v3 and v4), Percona Server for MongoDB, Microsoft Azure Cosmos DB and Amazon DocumentDB.

For more information on how to install and run MongoDB check the Installation Tutorial and Manage MongoDB on MongoDB’s documentation.

Download and Install RESTHeart

To install RESTHeart and run it with Java you just have to download either the ZIP or the TAR.GZ file and uncompress it.

zip tgz

Then un-zip it

$ unzip

or un-tar it

$ tar -xzf restheart.tar.gz

The archive will uncompress in the restheart/ folder.

$ cd restheart

Configuration files are in the etc/ folder, while extensions are in the plugins/ folder. You’ll see the main restheart.jar file in the root.

See the whole directory tree:

├── etc/
│   ├── acl.yml
│   ├──
│   ├── restheart.yml
│   └── users.yml
├── plugins/
│   ├── restheart-mongodb.jar
│   └── restheart-security.jar
└── restheart.jar

Run RESTHeart

By default, RESTHeart is configured to look for a running MongoDB instance on localhost, port 27017.

  • RESTHeart needs at least the Java 11 Runtime Environment. It won’t even start with older versions of Java.

Within the restheart/ folder, execute the following command:

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

Check it works

To check that RESTHeart is up and running, open the URL http://localhost:8080/ping. You will see the message:

Greetings from RESTHeart!

Alternatively, you can open the above URL using a command line HTTP client like curl and httpie or a API client like Postman.

Run with Docker

If you prefer to run with containers, RESTHeart is also distributed as a public Docker image. In this case you don’t need to install Java, it is already packaged in the Docker image.

With docker-compose you can run both RESTHeart and a dedicated MongoDB instance with a single command!

# 1 - create a new directory
$ mkdir restheart && cd restheart

# 2 - download the restheart docker-compose file
$ curl --output docker-compose.yml

# 3 - run the stack
$ docker-compose up -d

Creating network "temp_restheart-backend" with the default driver
Creating volume "temp_restheart-mongo-volume" with default driver
Creating restheart-mongo ... done
Creating restheart       ... done

Again, to check that RESTHeart is up and running, just open the URL http://localhost:8080/ping.


As soon as RESTHeart is up and running, you can jump to the tutorial.

Source code

The full source code is available on GitHub.

RESTHeart is distributed under the terms of the OSI-approved AGPL v3 license. A commercial license is available upon request.