v8 v7 v6 v5 v4 v3
Edit Page

Setup

Tip
 The easiest way to run RESTHeart and MongoDB is with Docker. See Setup with Docker

Download

Download the ZIP or TAR archive.

zip tgz

Un-zip or un-tar

# if you downloaded the tar.gz
$ tar -xzf restheart.tar.gz && cd restheart
# if you downloaded the zip
$ unzip restheart.zip && cd restheart

Requirements

RESTHeart only requires Java 21 or GraalVM >= 21.0.2 (v23.1.2 Java 21 based).

Run in standalone mode

When you run RESTHeart in standalone mode, it uses a different default configuration that disables all plugins that rely on MongoDB. This means you won’t have access to the built-in features that make RESTHeart powerful. However, you can still experiment with it and add your own custom plugins.

Use the option -s to run RESTHeart in standalone mode.

$ RHO="/fileRealmAuthenticator/users[userid='admin']/password->'secret'" java -jar restheart.jar -s
Note
 the RHO environment variable sets the password for the user admin. 
$ http -b http://localhost:8080/ping

Greetings from RESTHeart!

Run with MongoDB

RESTHeart’s default configuration activates all MongoDB plugins, providing features like the REST, GraphQL, and WebSocket APIs.

To use the WebSocket API and handle Transactions, you need to run MongoDB as a Replica Set.

Note
 RESTHeart is extensively tested with MongoDB v5.0, v6.0 and v7.0

To start RESTHeart and MongoDB, use these commands:

# start MongoDB as single instance Replica Set
$ mkdir -p /tmp/db && mongod --fork --syslog --replSet=foo -dbpath=/tmp/db && mongosh --quiet --eval 'if (!rs.isMaster().ismaster) rs.initiate();'
# start RESTHeart
$ java -jar restheart.jar

Directory structure

restheart
├── COMM-LICENSE.txt
├── LICENSE.txt
├── plugins
│   ├── restheart-graphql.jar
│   ├── restheart-mongoclient-provider.jar
│   ├── restheart-mongodb.jar
│   ├── restheart-polyglot.jar
│   └── restheart-security.jar
└── restheart.jar

Run as a daemon

To run RESTHeart as a daemon (i.e. fork) add the --fork parameter:

$ java -jar restheart.jar --fork

To see the logs you first need to enable file logging and set an absolute path to a log file. For example, check that /usr/local/var/log/restheart.log is writeable and then rerun it as follows:

$ RHO='/logging/log-to-file->true;/logging/log-file-path->"/usr/local/var/log/restheart.log";' java -jar restheart.jar --fork

CLI parameters

To know the available CLI parameters, run RESTHeart with --help:

$ java -jar restheart.jar -h

Usage: java -jar restheart.jar [-chstv] [--fork] [-o=RHO_FILE] [CONF_FILE]
      [CONF_FILE]            Main configuration file
  -c, --printConfiguration   Print the effective configuration to the standard
                               error and exit
      --fork                 Fork the process in background
  -h, --help                 This help message
  -o, --rho=RHO_FILE         Configuration overrides file
  -s, --standalone           Use an alternate configuration that disables all
                               plugins depending from MongoDb
  -t, --printConfigurationTemplate
                             Print the configuration template to the standard
                               error and exit
  -v, --version              Print product version to the output stream and exit

What’s next