v8 v7 v6 v5 v4 v3
Edit Page

Setup

Tip
 The easiest way to run RESTHeart and MongoDB is with Docker, please go to 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 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.

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 has all the MongoDB plugins activated, giving you all the cool features like the REST, GraphQL, and Websocket APIs.

If you want to use the Websocket API and handle Transactions, you’ll need to run MongoDB as a Replica Set.

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

To get RESTHeart and MongoDB up and running, 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