Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

...

Quick-start

Docker

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.

...

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

Install Java 8 and MongoDB following the instructions for your specific operating system and make sure that their binaries are actually executable (so they are in your PATH env variable).

...

Info
RESTHeart has been tested with MongoDB version 3.2, 3.0, 2.6 and 2.4.

...

2. Install RESTHeart

To install RESTHeart just extract the content of the dowloaded package in the desired directory.

...

  • restheart.jar
  • 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.

...

Code Block
languagetext
themeMidnight
$ mongod --fork --syslog
about to fork child process, waiting until server is ready for connections.
forked process: 11471
child process started successfully, parent exiting

By default MongoDB starts listening for connections on 127.0.0.1:27017. 

...

4. Start the RESTHeart server

Run the RESTHeart server by typing java -server -jar restheart.jar.

...

To see the HAL user interface, now open your browser at: http://127.0.0.1:8080/browser

...

5. Enable MongoDB authentication

Info

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.

...

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.

...

Code Block
languagebash
$ java -server -Djavax.net.ssl.trustStore=rhTrustStore -Djavax.net.ssl.trustStorePassword=changeit -Djavax.security.auth.useSubjectCredsOnly=false -jar restheart.jar restheart.yml

...

5.2. MongoDB authentication with just enough permissions 
Anchor
auth-with-jep
auth-with-jep

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.

...

Info

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:

...