Page tree

RESTHeart 3.0 is the latest stable version.

Skip to end of metadata
Go to start of metadata


The configuration file format is yaml.

All settings are optional: when a setting is not specified, RESTHeart will try to start with its default value.


Listeners allow to specify the protocol, ip, port and to use.

The supported protocols are: http, https and ajp. You can setup a listener per protocol (up to 3).

RESTHeart uses basic authentication; usernames and passwords are sent over the net on each request.

Using the http listener is not secure: users credentials can be sniffed by a man-in-the-middle attack.

 Use the http listener only on trusted environments.


Configure SSL to enable the https listener.

RESTHeart comes with a self-signed certificate that makes straightforward enabling https.

Specify use-embedded-keystore: true to use it (this is the default setting).

Using the self-signed certificate leads to issues with some clients; for instance, with curl you need to specify the "--insecure" option or you'll get an error message.

To use your own certificate you need to import it (and eventually the CA certificates chain) into a java keystore and specify use-embedded-keystore: false and the keystore-file,keystore-password and certpassword configuration properties. Refer to the java keystore documentation for that.


Specify the connection string URI with mongo-uri


mongo-uri: mongodb://user:secret@

More information on connection string on MongoDB documentation

The mongo uri allows to specify several connection properties (Write Concern, Read Preference Options, etc) and use different authentication mechanisms (LDAP, Kerberos, etc).

For version 1.0 and before 

Specify the ip and port of MongoDB with mongo-servers. For MongoDB replica set, specify all your servers.

Provide MongoDB users credentials with mongo-credentials.

The default MongoDB settings are:

  • host:
  • port: 27017
  • no MongoDB authentication required


    - host: mongodb
      port: 27017
    - auth-db: mydb
      user: user
      password: secret

MongoDB resources

Use mongo-mounts to bind URls to MongoDB resources using the out-of-the-box URL rewrite feature.

In the following example:

  • the db mydb is bound to the URL /data/db
  • the collection mycoll is bound to URL /data/coll
  • the document mydoc is bound to URL /data/doc
  • all resources are bound starting from URL /


 - what: /mydb
   where: /data/db
 - what: /mydb/mycoll
   where: /data/coll
 - what: /mydb/mycoll/mydoc
   where: /data/doc
 - what: "*"
   where: /



The security is configured by setting:

  • IDM the Identity Manager responsible of authentication
  • access-manager the Access Manager responsible of authorization

The RESTHeart security is pluggable and you can provide you own implementation of both IDM and AM.

The provided default implementations of IDM and AM are SimpleFileIdentityManager and SimpleAccessManager.

 conf-file: ../etc/security.yaml
 conf-file: ../etc/security.yaml

They are configured via the conf-file that specifies users and permissions.

permissions are given to roles and are expressed as predicates on http requests. Please refer to undertow documentation for more information about predicates.

Assign permission to the special role $unauthenticated to enable requests on resources without requiring authentication.

 - userid: admim
   password: changeit
   roles: [admins]
 - userid: user
   password: changeit
   roles: [users]

 - role: admins
   predicate: path-prefix[path="/"]
 - role: $unauthenticated
   predicate: path-prefix[path="/publicdb/"] and method[value="GET"]
 - role: users
   predicate: path-prefix[path="/publicdb/"]


The security default value is "no IDM and no AM".

This means that:

  • If you don't specify the IDM, authentication is disabled and any user can do everything (including deleting all dbs!)
  • If you specify the IDM but no AM, any authenticated user can do everything (including deleting all dbs!)



enable-log-console: true to log messages to the console (default value: true)

enable-log-file: true to log messages to a file (default value: true)

log-file-path) to specify the log file path (default value: restheart.log in system temporary directory)

log-level to set the log level. Value can be OFF, ERROR, WARN, INFO, DEBUG, TRACE and ALL. (default value is INFO)

The log file has a fixed size rolling policy.

As soon as it reaches 5Mb, its contented is zipped and saved.


Static Resources

static web resources can be bound to an URL and served directly by RESTHeart

  • what is the path of the directory containing the resources; the path is either absolute (starting with /) or relative to the directory containing the RESTHeart jar
  • where is the URI to bound

  • embedded is true if the static resources are embedded directly in the RESTHeart jar. In this case, the path must be relative to the jar root directory
  • secured allows to put the resources under the RESTHeart security context.

 - what: browser
   where: /browser
   embedded: true
   secured: false


Application Logic

RESTHeart has a pipeline architecture where specialized undertow handlers are chained together to serve the requests.

In order to provide additional application logic, custom handlers pipes can be bound under the /_logic URL.

The custom handler must extends the class org.restheart.handlers.applicationlogic.ApplicationLogicHandler.

Use application-logic-mounts to configure custom handlers.

In the following example two built-in application logic handlers are defined:

  • PingHandler bound to /_logic/ping that implements a simple ping service
  • GetRoleHandler bound to /_logic/roles/mine that returns the current user authentication status and eventually its roles

Note the secured property that allows to put the handler under the RESTHeart security context and the args properties that are passed to the custom handler.



 - what: org.restheart.handlers.applicationlogic.PingHandler
   where: /ping
   secured: false
        msg: "ciao from the restheart team"
 - what: org.restheart.handlers.applicationlogic.GetRoleHandler
   where: /roles/mine
   secured: false
      url: /_logic/roles/mine
      send-challenge: false
      idm-conf-file: ../etc/security-integrationtest.yaml


Performance settings

Eager db cursors preallocation engine

In big collections, reading a far page involves skipping the db cursor for many documents resulting in a performance bottleneck. For instance, with default pagesize of 100, a GET with page=50.000 involves 500.000 skips on the db cursor. The eager db cursors preallocation engine boosts up performaces (in some use cases, up to 1000%).

  • eager-cursor-allocation-pool-size default value is 100.
  • eager-cursor-allocation-linear-slice-width default value is 1000.
  • eager-cursor-allocation-linear-slice-delta default value is 100.
  • eager-cursor-allocation-linear-slice-heights default value is [4,2,1].
  • eager-cursor-allocation-random-max-cursors default value is 20.
  • eager-cursor-allocation-random-slice-min-width default value is 1000.

Forcing gzip encoding

In order to save bandwidth RESTHeart can force requests to support the GZIP encoding (if not, requests will be rejected)

  • force-gzip-encoding default value is false.

Local cache

local-cache allows to cache the db and collection properties to dramatically improve performances. Without caching, a GET on a document would requires two additional queries to retrieve the db and the collection properties.

You have to pay attention to local caching only in case of a multi-node deployments (horizontal scalability). In this case a change in a db or collection properties would reflect on other nodes at worst after the TTL (cache entries time to live). In most of the cases Dbs and collections properties only change at development time.

  • local-cache-enabled (default value true)
  • local-cache-ttl (default value is 1000 milliseconds, -1 means forever)

Limit the concurrent requests

To set a limit for the maximum number of concurrent requests being served

  • requests-limit (default value100)

Undertow performance tuning

for more information refer to undertow documentation

  • io-threads (default value2) the number of I/O threads created for non-blocking tasks. at least 2. suggested value: core*2
  • worker-threads (default value32) the number of threads created for blocking tasks (such as ones involving db access). suggested value: core*16
  • buffer-size (default value16384) use 16k buffers for best performance - as in Linux 16k is generally the default amount of data that can be sent in a single write() call
  • buffers-per-region (default value20)
  • direct-buffers (default valuetrue) should the buffer pool use direct buffers, this instructs the JVM to use native (if possible) I/O operations on the buffers


Example configuration file

The full default configuration file can be seen at Default Configuration File

  • No labels