RESTHeart 3.0 is the latest stable version.
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.
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
certpassword configuration properties. Refer to the java keystore documentation for that.
Specify the connection string URI with mongo-uri
More information on connection string on MongoDB documentation https://docs.mongodb.org/manual/reference/connection-string/
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
The default MongoDB settings are:
- no MongoDB authentication required
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 /
The security is configured by setting:
IDMthe Identity Manager responsible of authentication
access-managerthe 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.
idm: implementation-class: org.restheart.security.impl.SimpleFileIdentityManager conf-file: ../etc/security.yaml access-manager: implementation-class: org.restheart.security.impl.SimpleAccessManager conf-file: ../etc/security.yaml
They are configured via the
conf-file that specifies
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.
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:
enable-log-file: true to log messages to a file (default value:
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
The log file has a fixed size rolling policy.
As soon as it reaches 5Mb, its contented is zipped and saved.
static web resources can be bound to an URL and served directly by RESTHeart
whatis the path of the directory containing the resources; the path is either absolute (starting with /) or relative to the directory containing the RESTHeart jar
whereis the URI to bound
embeddedis 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
securedallows to put the resources under the RESTHeart security context.
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
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
secured property that allows to put the handler under the RESTHeart security context and the
args properties that are passed to the custom handler.
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-sizedefault value is
eager-cursor-allocation-linear-slice-widthdefault value is
eager-cursor-allocation-linear-slice-deltadefault value is
eager-cursor-allocation-linear-slice-heightsdefault value is
eager-cursor-allocation-random-max-cursorsdefault value is
eager-cursor-allocation-random-slice-min-widthdefault value is
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-encodingdefault value is
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-ttl(default value is
1000milliseconds, -1 means forever)
Limit the concurrent requests
To set a limit for the maximum number of concurrent requests being served
Undertow performance tuning
for more information refer to undertow documentation
2) the number of I/O threads created for non-blocking tasks. at least 2. suggested value: core*2
32) the number of threads created for blocking tasks (such as ones involving db access). suggested value: core*16
16384) 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
true) 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