RESTHeart 3.0 is the latest stable version.
RESTHeart fits naturally a microservices architecture and a Docker image is available and fully maintained by us. Docker should be considered the best and easiest way to create a development or production environment with RESTHeart. The source code contains a docker-compose configuration which makes things straightforward. Please have a look at the Docker folder in the source code distribution. We are using RESTHeart running within Docker in production since a long time now, so we recommend it as the way to go.
Before switching to Docker we used Vagrant. A Vagrant box is available for creating a complete virtual development environment, using a Ubuntu 14.04 image with JDK 8, MongoDB 3 and the latest RESTHeart server. You can then skip section 2 to 6 and jump directly to section 7, in case you want to know how to change the default security settings. Unfortunately we don't fully maintain the Vagrant repository anymore, so it's up to you to update it to fit your purpose. Pull requests are welcome.
Please follow the next sections for a full local installation.
Run it on your host - what you need
If you don’t have them already, please download the following packages:
Most of the work must be done using a command line interface.
1. Install Java and MongoDB
To check Java and MongoDB, you should execute the following commands and you should get something like the below (output might vary depending on Java version and your OS):
2. Install RESTHeart
To install RESTHeart just extract the content of the dowloaded package in the desired directory.
You are interested in two files:
etc/restheart.yml<- an example configuration file
3. Start MongoDB
In pursuit of simplicity we are first going to start MongoDB without enabling authentication. We’ll see later how to enable it.
You can just start MongoDB by running the
mongod command from a shell prompt. It is configured by default to use the
/data/dbfolder, which must exist already or you have to create it beforehand. If you do not want to use the default data directory (i.e.,
/data/db), specify the path to the data directory using the
mongod --dbpath <path to data directory>. You might prefer to run the MongoDB process in background, using the
mongod --fork --syslog:
4. Start the RESTHeart server
Run the RESTHeart server by typing
java -server -jar restheart.jar.
This starts it with the default configuration, which is fine for MongoDB running on localhost, on default port and without authentication.
Convention over configuration
Different configuration options can be specified passing a configuration file as argument. Note that the configuration file path is either absolute or relative to the restheart.jar file location.
The configuration file can specify any option that will overwrite the default value: this way it is not required to specify all the possible options in the configuration file following the convention over configuration approach.
On Linux, OSX and Solaris you can run RESTHeart as a daemon process:
java -server -jar restheart.jar --fork. Note that this will force the console logging and the file logging to be turned off and on respectively, regardless the specified log configuration options.
HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API. Adopting HAL will make your API explorable, and its documentation easily discoverable from within the API itself. In short, it will make your API easier to work with and therefore more attractive to client developers. APIs that adopt HAL can be easily served and consumed using open source libraries available for most major programming languages. It’s also simple enough that you can just deal with it as you would any other JSON.
To see the HAL user interface, now open your browser at:
5. Enable MongoDB authentication
This section assumes using MongoDB 3.2. For other versions, the security configuration is similar but different. Rrefer to the MongoDB documentation for more information.
Start MongoDB with authentication and connect to the MongoDB instance from a client running on the same system. This access is made possible by the localhost exception. Again, you might prefer to run the MongoDB process in background, using the
In this section we will use the mongodb superuser role root that provides access to the all operations and all the resources.
However the best practice is to use a MongoDB user with restricted access. For instance, it could be restricted to use only a single DB in read only mode. For more information refer to MongoDB authentication with just enough permissions section.
Create the admin user. The procedure is different depending on MongoDB version.
We’ll use the restheart.yml example configuration file that comes with RESTHeart download package (you find it in the etc directory)
Find and modify the following section providing the user-name, password and authentication db (the db where the MongoDB user is defined, in our case ‘admin’).
Now start RESTHeart specifying the configuration file:
Test the connection opening the HAL browser at
Note that the example configuration file
etc/restheart.yml also enables the RESTHeart security. Opening the HAL browser page, you’ll be asked to authenticate. You can use of one of the credentials defined in
etc/security.yml file (try username = ‘a’ and password = ‘a’).
5.1 Connect RESTHeart to MongoDB over TLS/SSL
MongoDB clients can use TLS/SSL to encrypt connections to mongod and mongos instances.
To configure RESTHeart for TLS/SSL do as follows:
- create the keystore importing the public certificate used by mongod using keytool (with keytool, the java tool to manage keystores of cryptographic keys)
- specify the ssl option in the mongo-uri in the restheart yml configuration file:
- start restheart with following options:
5.2. MongoDB authentication with just enough permissions
In the previous examples we used a mongodb user with root role (or clusterAdmin and dbAdminAnyDatabase roles for version 2.4) for the sake of simplicity. This allows RESTHeart to execute any command on any mongodb resource.
On production environments a strong security isolation is mandatory.
In order to achieve it, the best practice is:
- use the mongo-mounts configuration option to restrict the resources exposed by RESTHeart;
- use a mongodb user with just enough roles: read or readWrite on mounted databases
The following example, creates a mongodb user with appropriate roles to expose the databases db1, db2 and db3 in read only mode.
To list the databases (i.e. GET /, the root resource) the listDatabases permission is needed. This permission is granted by the readWriteAnyDatabase role or you can create a custom role.
To allow deleting a database the dropDatabase permission is needed. This permission is granted by the dbAdmin role or you can create a custom role.
6. Clients Authentication and Authorization
Refert to Security section for detailed information about how enable, configure and customize clients authentication and authorization.
Additional resources for beginners
There are some introductory articles about RESTHeart from Compose.io:
- Building Instant RESTFul API's with MongoDB and RESTHeart
- Building Secure Instant API's with RESTHeart and Compose
- Launching RESTHeart into Production