+ RESTHeart 8 is the current stable release. Switch documentation to v7
+
+{% elsif page.docs_version != null %}
+
+ We are currently updating the documentation for v8. For a comprehensive list of changes, please see the Upgrade to v8
{% endif %}
-
-
-
+
\ No newline at end of file
diff --git a/_layouts/docs-adoc.html b/_layouts/docs-adoc.html
index b5e19472..676426a6 100644
--- a/_layouts/docs-adoc.html
+++ b/_layouts/docs-adoc.html
@@ -11,7 +11,14 @@
v{{ page.docs_version }}
-
+
+ {% if page.docs_version == 8 %}
+ v8
+ {% else %}
+ v8
+ {% endif %}
+
+
{% if page.docs_version == 7 %}
v7
{% else %}
@@ -83,6 +90,8 @@
{% include docs-v5-sidebar.html %}
{% elsif page.docs_version == 6 %}
{% include docs-v6-sidebar.html %}
+ {% elsif page.docs_version == 7 %}
+ {% include docs-v7-sidebar.html %}
{% else %}
{% include docs-sidebar.html %}
{% endif %}
diff --git a/_layouts/docs.html b/_layouts/docs.html
index dac8c5ec..9a02fd76 100644
--- a/_layouts/docs.html
+++ b/_layouts/docs.html
@@ -12,7 +12,14 @@
v{{ page.docs_version }}
-
+
+ {% if page.docs_version == 8 %}
+ v8
+ {% else %}
+ v8
+ {% endif %}
+
+
{% if page.docs_version == 7 %}
v7
{% else %}
diff --git a/docs/index.adoc b/docs/index.adoc
index c520796a..14850ef4 100644
--- a/docs/index.adoc
+++ b/docs/index.adoc
@@ -1,10 +1,10 @@
---
-title: Get Started with RESTHeart v7
+title: Get Started with RESTHeart v8
layout: docs-adoc
menu: overview
---
-> *RESTHeart is a modern, JVM and GraalVM-based platform for building cloud-native HTTP microservices*
+> *RESTHeart is a cutting-edge platform for building cloud-native HTTP microservices, leveraging Java Virtual Threads for enhanced performance and scalability. It is built for the JVM and GraalVM.*
NOTE: An _HTTP microservice_ is a server-side, lightweight component that exposes an HTTP API. Clients interact with it only through HTTP requests, usually - but not exclusively - using JSON payloads, decoupling the client from the underlying technology and completely separating the presentation from the business logic.
diff --git a/docs/upgrade-to-v8.adoc b/docs/upgrade-to-v8.adoc
new file mode 100644
index 00000000..fa2715bf
--- /dev/null
+++ b/docs/upgrade-to-v8.adoc
@@ -0,0 +1,327 @@
+---
+title: Upgrade to RESTHeart v8
+layout: docs-adoc
+menu: overview
+---
+
+RESTHeart v8 introduces many new features, improvements, and changes.
+
+This page summarizes the new features and provides guidance on upgrading from previous versions.
+
+== Virtual Threads
+
+Java 21 introduces *Virtual Threads*, a feature detailed in http://openjdk.org/jeps/444[JEP 444]. These lightweight threads significantly boost performance and simplify concurrent programming.
+
+RESTHeart 8 harnesses `Executors.newVirtualThreadPerTaskExecutor()` to manage requests handled by services marked as blocking (with `RegisterPlugin(blocking = true)` by default), efficiently processing blocking services.
+
+Furthermore, RESTHeart 8 configures Undertow to use its `ThreadAwareByteBufferPool` for optimized resource allocation:
+
+- *Platform Threads:* Uses the `undertow.DefaultByteBufferPool` to efficiently pool resources.
+- *Virtual Threads:* Utilizes `NotPoolingByteBufferPool`, which avoids pooling to enhance performance given the distinct characteristics of virtual threads.
+
+=== Rationale
+
+> Virtual threads are lightweight, high-throughput threads that simplify the development, maintenance, and monitoring of concurrent applications.
+
+=== Configuration
+
+The following options manage virtual threads:
+
+```yaml
+# Specifies the initial number of platform carrier threads used for virtual threads in blocking operations.
+# Recommended value: 1.5 * number of cores.
+# If <= 0, it defaults to 1.5 times the system core count.
+workers-scheduler-parallelism: 0
+
+# Sets the maximum number of platform carrier threads for virtual threads in blocking operations.
+workers-scheduler-max-pool-size: 256
+```
+
+== Cookie Authentication
+
+Allows storing the auth token in a secure cookie and enables authentication from it.
+
+*Rationale*
+
+1. Using cookie authentication and JWT tokens effectively enables Single Sign-On.
+2. Typically, a client first authenticates using Basic Authentication and then uses the auth token returned in the first response for further requests. This auth token is usually stored in the local storage by web clients. The local storage is readable by JavaScript, thus exposing this approach to Cross-site Scripting (XSS) security attacks. Storing the auth token in a secure cookie avoids XSS.
+
+=== Overview
+
+Cookie Authentication allows the client browser to store an authentication token in a secure cookie. This mechanism enables authentication based on the stored cookie, allowing the client to remain authenticated across multiple requests without having to send credentials each time. The token is securely saved in the cookie, ensuring that sensitive data is protected and accessible only to the intended server.
+
+==== Configuration Options
+
+Cookie Authentication is disabled by default. To enable it, the following three plugins must be enabled and configured: `authCookieSetter`, `authCookieHandler`, and `authCookieRemover`.
+
+The cookie authentication mechanism can function using three different options:
+
+*Option 1: JWT Verified by `jwtAuthenticationMechanism`*
+This option is recommended if you also want to allow clients to authenticate via JWTs sent in the `Authorization` header (not stored in a cookie).
+
+```
+/tokenBasicAuthMechanism/enabled->true|false
+/jwtAuthenticationMechanism/enabled->true
+/jwtTokenManager/enabled->true
+/rndTokenManager/enabled->false
+```
+
+*Option 2: JWT Verified by `tokenBasicAuthMechanism`*
+Choose this option if you have multiple instances of RESTHeart verifying cookies, and JWT header-based authentication isn't required.
+
+```
+/tokenBasicAuthMechanism/enabled->true
+/jwtAuthenticationMechanism/enabled->false
+/jwtTokenManager/enabled->true
+/rndTokenManager/enabled->false
+```
+
+*Option 3: RGT Cookies (Randomly Generated Tokens)*
+For authentication via RGT cookies, enable these components:
+
+- *`tokenBasicAuthMechanism`*: Manages the basic authentication process.
+- *`rndTokenManager`*: Manages and validates randomly generated tokens for Basic Authentication cookies.
+
+```
+/tokenBasicAuthMechanism/enabled->true
+/jwtAuthenticationMechanism/enabled->false
+/jwtTokenManager/enabled->false
+/rndTokenManager/enabled->true
+```
+
+> *Note:* RGT cookies can only be verified by the RESTHeart instance that issued them. For multi-instance deployments, it is advisable to use JWT cookies instead.
+
+==== authCookieSetter
+
+This component is responsible for initiating a user's authenticated session by setting the authentication cookie.
+
+Activates when a URL includes the query parameter `?set-auth-cookie` and a user is authenticated, setting a cookie populated with a token generated by the enabled Token Manager.
+
+*Configuration*
+
+```yaml
+authCookieSetter:
+ enabled: false # Not enabled by default
+ name: rh_auth # The name of the cookie to be set
+ domain: localhost # The domain within which the cookie is valid
+ path: / # The cookie path, applicable to the entire domain
+ http-only: true # If true, enhances security by making the cookie inaccessible to JavaScript
+ same-site: true # Restricts the cookie to first-party contexts, preventing CSRF attacks
+ same-site-mode: strict # Strictly prevents the cookie from being sent along with cross-site requests
+ expires-ttl: 86400 # Defines the duration (in seconds, default 1 day) for which the cookie is valid
+```
+
+When using JWT tokens, the cookie can be updated by specifying both `?set-auth-cookie&renew-auth-token`. The query parameter `renew-auth-token` forces the `jwtTokenManager` to update the JWT.
+
+==== authCookieHandler
+
+Responsible for utilizing the authentication cookie to maintain authenticated sessions across requests.
+
+Reads the `rh_auth` cookie (actual cookie name is defined in authCookieSetter configuration), if available, and constructs an Authorization header. This allows for seamless continuation of sessions and supports both Basic and JWT authentication mechanisms.
+
+*Configuration*
+
+```yaml
+authCookieHandler:
+ enabled: false # Not enabled by default
+```
+
+==== authCookieRemover
+
+Handles the secure and explicit termination of authenticated sessions.
+
+Clears the authentication cookie in response to a `POST /logout` request. This effectively logs out the user by wiping the authentication cookie from the user's browser, ensuring the session is securely terminated.
+
+*Configuration*
+
+```yaml
+authCookieRemover:
+ enabled: false # Not enabled by default
+ secure: false # If the request to clean the cookie should be authenticated
+ defaultUri: /logout # The endpoint that triggers this service
+```
+
+=== Example usage
+
+This is an example of how a user might log in, make some requests, and then log out within a system using cookie authentication with the configuration described previously. This example assumes that the system is web-based and communicates over HTTP.
+
+==== Logging In
+
+The user submits their credentials (username and password) via Basic Authentication (`Authorization` header) from a form on a client application, which sends a GET request to the`/roles/{username}` endpoint, including the `?set-auth-cookie` query parameters
+
+```http
+GET /roles/{username}?set-auth-cookie HTTP/1.1
+Host: localhost
+Content-Type: application/json
+Authorization: Basic YWRtaW46c2VjcmV0
+```
+
+If the credentials are valid, the server responds by setting an `rh_auth` cookie containing the authentication token and returns a success response.
+
+```http
+HTTP/1.1 200 OK
+Set-Cookie: rh_auth="Basic YWRtaW46MmliNWFsaDFxajZ4eHY5aWlyOTZsejh1bnJjMHQzNWFucnEyYzh1cG12cHNpOGc3dDQ="; Version=1; Path=/; Domain=localhost; Secure; HttpOnly; Expires=Sat, 20 Apr 2024 11:53:00 GMT; SameSite=Strict
+Content-Type: application/json
+
+{
+ "authenticated": true,
+ "roles": [ "user-role" ]
+}
+```
+
+Note that the value of the cookie doesn't include the actual user credentials but uses the auth token generated by the enabled Token Manager.
+
+==== Making Authenticated Requests
+
+Once the cookie is set, the user can make subsequent requests to the server. The browser automatically includes the `rh_auth` cookie with each request to the domain.
+
+For example, if the user wants to access a protected resource, they might send a GET request to the server:
+
+```http
+GET /protected-resource HTTP/1.1
+Host: localhost
+Cookie: rh_auth="Basic YWRtaW46MmliNWFsaDFxajZ4eHY5aWlyOTZsejh1bnJjMHQzNWFucnEyYzh1cG12cHNpOGc3dDQ="
+```
+
+The server checks the cookie, validates the session, and if valid, responds with the requested data.
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": "Here is your protected resource data."
+}
+```
+
+==== Logging Out
+
+To log out, the user sends a POST request to the logout endpoint. This request doesn't need to include user credentials but should be made from the same domain to ensure the browser includes the authentication cookie.
+
+```http
+POST /logout HTTP/1.1
+Host: localhost
+Cookie: rh_auth=
+```
+
+The server processes the logout request and clears the authentication cookie by setting its value to null.
+
+```http
+HTTP/1.1 200 OK
+Set-Cookie: rh_auth=; path=/; domain=localhost; secure; HttpOnly; SameSite=Strict
+Content-Type: application/json
+```
+
+After this, the user is logged out, and their session is terminated. The cookie is invalidated, and any subsequent requests to the server that require authentication will fail until the user logs in again.
+
+== Programmatic Configuration of ACLs
+
+We want to extend defining security policy rules programmatically by allowing both inclusive and exclusive security policies through veto and permission predicates.
+
+Currently, RESTHeart allows defining a set of predicates via `PluginRegistry.getGlobalSecurityPredicates()` that must all resolve to `true` to allow the request. Under the hood, the global security predicates are enforced by the vetoer authorizer `GlobalPredicatesVetoer`.
+
+For clarity, recall that an Authorizer can be either a VETOER or an ALLOWER. A request is allowed when no VETOER denies it and any ALLOWER allows it.
+
+We want to extend and refactor this feature as follows:
+
+- Move the current logic from `PluginRegistry` to an `ACLRegistry` that can be injected with `@Inject("acl-registry")`
+- Rename global security predicates to "veto predicates" and rename the vetoer as `ACLRegistryVetoer`
+- Symmetrically add allow predicates and the corresponding allower authorizer `ACLRegistryAllower`
+
+*Rationale*
+
+By extending the definition of security policy rules programmatically, it will be possible to ship a secure service with its own security policy, avoiding the need to configure the ACL.
+
+As an example, the `RoleService` mapped to `/roles/{userid}` can be secured and allowed to be requested only if the path parameter `userid` matches the authenticated user id. Currently, this is not secured to avoid the need to configure the ACL and the authorization is checked in the service code.
+
+*Detailed documentation*
+
+The `ACLRegistry` can be injected with `@Inject("acl-registry")` and allows defining Access Control Lists (ACLs) programmatically:
+
+```java
+public interface ACLRegistry {
+ /**
+ * Registers a veto predicate that determines if a request should be denied.
+ * When the predicate evaluates to true, the request is immediately forbidden (vetoed).
+ * Additionally, a request will also be denied if it is not explicitly authorized by any
+ * allow predicates or any other active allowing authorizers.
+ *
+ * @param veto The veto predicate to register. This predicate should return true to veto (deny) the request,
+ * and false to let the decision be further evaluated by allow predicates or other authorizers.
+ */
+ public void registerVeto(Predicate> veto);
+
+ /**
+ * Registers an allow predicate that determines if a request should be authorized.
+ * The request is authorized if this predicate evaluates to true, provided that no veto predicates
+ * or other active vetoer authorizers subsequently deny the request. This method helps in setting up
+ * conditions under which requests can proceed unless explicitly vetoed.
+ *
+ * @param allow The allow predicate to register. This predicate should return true to authorize the request,
+ * unless it is vetoed by any veto predicates or other vetoing conditions.
+ */
+ public void registerAllow(Predicate> allow);
+
+ /**
+ * Registers a predicate that determines whether requests handled by the ACLRegistryAllower
+ * require authentication. This method is used to specify conditions under which authentication
+ * is mandatory. Typically, authentication is required unless there are allow predicates
+ * explicitly authorizing requests that are not authenticated.
+ *
+ * @param authenticationRequired The predicate to determine if authentication is necessary.
+ * It should return true if the request must be authenticated,
+ * otherwise false if unauthenticated requests might be allowed.
+ */
+ public void registerAuthenticationRequirement(Predicate> authenticationRequired);
+}
+```
+
+This registry is utilized by the `ACLRegistryVetoer` and `ACLRegistryAllower` authorizers to manage request permissions. The `ACLRegistryVetoer` denies requests based on veto predicates, while the `ACLRegistryAllower` grants permission to proceed with requests based on allow predicates.
+
+A request is permitted to proceed if it is not denied by any `ACLRegistryVetoer` and at least one `ACLRegistryAllower` approves it.
+
+*Example usage:*
+```java
+@Inject("acl-registry")
+ACLRegistry registry;
+
+@OnInit
+public void init() {
+ registry.registerVeto(r -> r.getPath().equals("/deny"));
+ registry.registerAllow(r -> r.getPath().equals("/allow"));
+}
+```
+
+== Lazy-load Request Content
+
+Up to RESTHeart v7, requests processed by the `MongoService` are designed to lazy-load their content. This means that the request body is only read when `MongoRequest.getContent()` is invoked for the first time.
+
+This lazy-loading approach significantly improves performance across various scenarios. For instance, it speeds up the request validation process and ensures that interceptors that don't need to access the content can execute faster.
+
+RESTHeart 8 extends this behavior to all request types.
+
+*Rationale*
+
+Optimizing request handling can enhance performance in cases where the request content is unnecessary. A common example includes situations where a request is denied due to insufficient permissions.
+
+*Detailed Documentation*
+
+The `ServiceRequest` class now features a new abstract method to read and parse the request content:
+
+```java
+/**
+ * Parses the content from the exchange and converts it into an instance of the specified type {@code T}.
+ *
+ * This method retrieves data from the exchange, interprets it according to the expected format, and converts
+ * this data into an object of type {@code T}.
+ *
+ * @return an instance of {@code T} representing the parsed content
+ * @throws IOException if an I/O error occurs
+ * @throws BadRequestException if the content doesn't conform to the expected format of type {@code T}
+ */
+public abstract T parseContent() throws IOException, BadRequestException;
+```
+
+`ServiceRequest.parseContent()` is called by `ServiceRequest.getContent()` on its first invocation. The parsed content is then cached and linked to the request, ensuring that any subsequent calls will reuse the already parsed content object.
+
+This approach makes handling request content more efficient by reducing unnecessary parsing and processing overhead.
\ No newline at end of file
diff --git a/docs/v7/auditing.adoc b/docs/v7/auditing.adoc
new file mode 100644
index 00000000..44b6bcf0
--- /dev/null
+++ b/docs/v7/auditing.adoc
@@ -0,0 +1,35 @@
+---
+title: Auditing
+layout: docs-adoc
+menu: setup
+---
+
+== Opentracing / zipkin headers support
+
+This implements issue link:https://github.com/SoftInstigate/restheart/issues/287[#287]
+
+It's a very slim implementation that fits most use-cases. Incoming headers are copied to the response. If there are no headers set, we'll generate some and send them back. The `X-B3-TraceId` will be written to the logs (by default inside of the [%thread] marks).
+
+This implementation makes it possible to correlate logged exceptions (in case this happens) with the corresponding request log, even when the thread handling the message is re-used shortly after.
+
+It handles all headers mentioned in link:https://github.com/openzipkin/b3-propagation[b3-propagation], as well as the uber-trace-id header that is used by Jaeger (see link:https://www.jaegertracing.io/docs/client-libraries/#trace-span-identity[trace-span-identity] to get broader support.
+
+=== Configuration
+
+`/mongo/metrics-gathering-level`: metrics gathering for which level? OFF => no gathering, ROOT => gathering at root level, DATABASE => at db level, COLLECTION => at collection level
+WARNING: use requests-log-level level 2 only for development purposes, it logs user credentials (Authorization and Auth-Token headers).
+
+Example `restheart.yml` fragment:
+
+[source,yml]
+----
+logging:
+ requests-log-trace-headers:
+ # - x-b3-traceid # vv Zipkin headers, see https://github.com/openzipkin/b3-propagation
+ # - x-b3-spanid
+ # - x-b3-parentspanid
+ # - x-b3-sampled # ^^
+ # - uber-trace-id # jaeger header, see https://www.jaegertracing.io/docs/client-libraries/#trace-span-identity
+ # - traceparent # vv opencensus.io headers, see https://github.com/w3c/distributed-tracing/blob/master/trace_context/HTTP_HEADER_FORMAT.md
+ # - tracestate # ^^
+----
\ No newline at end of file
diff --git a/docs/v7/clustering.md b/docs/v7/clustering.md
new file mode 100644
index 00000000..aa880ce2
--- /dev/null
+++ b/docs/v7/clustering.md
@@ -0,0 +1,69 @@
+---
+title: Clustering and Load Balancing
+layout: docs
+menu: setup
+---
+
+ -> JSON
+
+The `` selects the option to override or add.
+
+So valid overrides are:
+
+[source,bash]
+/core/name -> "production"
+/mongo/mongo-mounts[1] -> {"where": "/api", "what": "mydb"}
+/core/io-threads -> 8
+
+The following are invalid:
+
+[source,txt]
+/core/name -> production # missing quotes in JSON value
+/mongo/mongo-mounts[1] -> {"where: "/api" # invalid JSON object
+core/io-threads -> 8 # xpath expression does not start with /
+
+== Modify the configuration with an override file
+
+NOTE: override files are available from RESTHeart v7.1
+
+A configuration override file can be specified with the `-o` option to modify the default configuration.
+
+[source,bash]
+$ java -jar restheart.jar -o conf-overrides.conf
+
+TIP: the link:https://github.com/SoftInstigate/restheart/tree/master/examples/example-conf-files[Example configuration files] directory in the RESTHeart repository contains some examples in the different formats.
+
+The override file can use four formats, `.conf`, `.yml` and `.json`, `.jsonc` (Json with comments).
+
+*Example override file in `.conf` format*
+
+This uses the same format than `RHO`` env variable:
+
+[source,conf]
+----
+/core/name -> "default";
+/http-listener -> {
+ "enabled": true,
+ "host": "localhost",
+ "port": 8080
+};
+----
+
+*Example override file in `.jsonc` format*
+
+JSON format, with keys as xpath expressions to select the options to override or add.
+
+[source,jsonc]
+----
+{
+ "/core/name": "default",
+ "/http-listener": {
+ "enabled": true,
+ "host": "localhost",
+ "port": 8080
+ }
+}
+----
+
+*Example override file in `.yml` format*
+
+YML format, with keys as xpath expressions to select the options to override or add.
+
+[source,yml]
+----
+/core/name: default
+/http-listener:
+ enabled: true
+ host: "localhost"
+ port: 8080
+----
+
+== Change the configuration in Docker container
+
+The configuration of RESTHeart running in a Docker container can be modified in three ways.
+
+=== 1 - Using the `RHO` env variable
+
+The following example uses the option `-e RHO="..."` to override the configuration parameters `/mclient/connection-string` and `/core/name`.
+
+[source,bash]
+----
+$ docker run --rm -p "8080:8080" -e RHO="/http-listener/host->'0.0.0.0';/mclient/connection-string->'mongodb://host.docker.internal';/core/name->'the-best-api-ever'" softinstigate/restheart
+
+INFO o.r.configuration.Configuration - Overriding configuration parameters from RHO environment variable:
+INFO o.r.configuration.Configuration - /http-listener/host -> 0.0.0.0
+INFO o.r.configuration.Configuration - /mclient/connection-string -> mongodb://host.docker.internal
+INFO o.r.configuration.Configuration - /core/name -> the-best-api-ever
+.....
+----
+
+NOTE: the RESTHeart Docker container defines the following `RHO` variable:
+
+```
+ENV RHO='/mclient/connection-string->"mongodb://host.docker.internal";/http-listener/host->"0.0.0.0"'
+```
+
+When defining your `RHO` variable always set `/http-listener/host->"0.0.0.0"` and your `/mclient/connection-string`.
+
+=== 2 - Using a configuration override file
+
+[source,bash]
+$ docker run --rm -p "8080:8080" -e RHO="" -v /path/to/conf-overrides.conf:/opt/restheart/etc/conf-overrides.conf softinstigate/restheart -o etc/conf-overrides.conf
+
+This mounts the host file `/path/to/conf-overrides.conf` into the container directory `/opt/restheart/etc` and executes RESTHeart with the `-o` option pointing to that file.
+
+WARNING: RESTHeart Docker image defines the following `RHO` environment variable which has precedence over the configuration override file. To avoid the `RHO` of the Docker image to apply, you can add `-e RHO=""` to the `docker run` command.
+
+```
+ENV RHO='/mclient/connection-string->"mongodb://host.docker.internal";/http-listener/host->"0.0.0.0"'
+```
+
+To avoid this, just can add `-e RHO=""` to your `docker run` command.
+
+NOTE: override files are available from RESTHeart v7.1
+
+=== 3 - Using a configuration file
+
+The following commands add a configuration file to the container:
+
+[source,bash]
+----
+$ # generate the default configuration file in /tmp/restheart.yml (and edit it)
+$ docker run --rm -p 8080:8080 -v /tmp/restheart.yml:/opt/restheart/etc/restheart.yml softinstigate/restheart -t 2> /tmp/restheart.yml
+
+$ # run the RESTHeart container mounting the conf file as a volume
+$ docker run --rm -p 8080:8080 -v /tmp/restheart.yml:/opt/restheart/etc/restheart.yml softinstigate/restheart etc/restheart.yml
+----
+
+WARNING: the RESTHeart Docker image defines the following `RHO` variable which will override the parameters in your configuration file:
+
+```
+ENV RHO='/mclient/connection-string->"mongodb://host.docker.internal";/http-listener/host->"0.0.0.0"'
+```
+
+To avoid this, just can add `-e RHO=""` to your `docker run` command:
+
+```bash
+# generate a configuration file
+$ docker run --rm -p 8080:8080 softinstigate/restheart -c 2> /tmp/restheart.yml
+# run restheart with it
+$ docker run --rm -p 8080:8080 -e RHO="" -v /tmp/restheart.yml:/opt/restheart/etc/restheart.yml softinstigate/restheart etc/restheart.yml
+```
diff --git a/docs/v7/default-configuration.adoc b/docs/v7/default-configuration.adoc
new file mode 100644
index 00000000..5667961d
--- /dev/null
+++ b/docs/v7/default-configuration.adoc
@@ -0,0 +1,641 @@
+---
+title: Default Configuration
+layout: docs-adoc
+menu: setup
+---
+
+== Introduction
+
+This page presents the RESTHeart _default configuration_ splitting it in different sections.
+
+The default configuration applies when RESTHeart is started without specifying a configuration file:
+
+[source,bash]
+----
+$ java -jar restheart.jar
+----
+
+The default configuration template can be printed out with the following command:
+
+[source,bash]
+----
+$ java -jar restheart.jar -t
+----
+
+NOTE: The default configuration is fine most of the times. You just want to change few options and the suggested way is using the default configuration with the needed overrides. See link:http://127.0.0.1:4000/docs/configuration#modify-the-configuration-with-the-rho-env-var[modify the configuration with overrides]
+
+== Standalone configuration
+
+The default configuration enables several plugins that require MongoDB. If you are using RESTHeart without MongoDB an alternative default configuration can be used with the `-s` option, where `s` stands for _standalone_.
+
+NOTE: standalone configuration is available from RESTHeart v7.2
+
+This configuration enables the `fileRealmAuthenticator` and the `fileAclAuthorizer` and disables the MongoDB data APIs.
+
+It defines the user `admin` but the password must be set overriding the configuration. The following command sets the password of the `admin` user as `secret` using the `RHO` environment variable:
+
+[source,bash]
+----
+$ RHO="/fileRealmAuthenticator/users[userid='admin']/password->'secret'" java -jar core/target/restheart.jar -s
+----
+
+== Listeners
+
+[source,yml]
+----
+# RESTHeart Configuration File.
+## See https://restheart.org/docs/setup/#configuration-files
+
+---
+# HTTP Listener
+# WARNING: Using the http listener is not secure.
+http-listener:
+ enabled: true
+ host: localhost
+ port: 8080
+
+# HTTPS Listener
+https-listener:
+ enabled: false
+ host: localhost
+ port: 4443
+ # The https listener requires setting up a TLS certificate.
+ # See https://restheart.org/docs/security/tls/
+ keystore-path: null
+ keystore-password: null
+ certificate-password: null
+
+# AJP Listener
+ajp-listener:
+ enabled: false
+ host: localhost
+ port: 8009
+----
+
+== Authentication Mechanisms
+
+[source,yml]
+----
+# Auth Token Authentication
+# The verified token is generated by the enabled token manager
+# see https://restheart.org/docs/security/authentication#token-authentication
+tokenBasicAuthMechanism:
+ enabled: true
+
+# Basic Authentication
+# see https://restheart.org/docs/security/authentication#basic-authentication
+basicAuthMechanism:
+ enabled: true
+ authenticator: mongoRealmAuthenticator
+
+# JSON Web Token Authentication
+# see https://restheart.org/docs/security/authentication#jwt-authentication
+jwtAuthenticationMechanism:
+ enabled: false
+ algorithm: HS256
+ key: secret
+ base64Encoded: false
+ usernameClaim: sub
+ rolesClaim: null
+ fixedRoles:
+ # - jwt-role
+ issuer: restheart.org
+ audience: null
+
+# Digest Authentication
+# see https://restheart.org/docs/security/authentication#digest-authentication
+digestAuthMechanism:
+ # digest authentication is disabled by default
+ # because it requires the passwords to be stored in plaintext
+ # and mongoRealmAuthenticator hashes the passwords by default (bcrypt-hashed-password: true)
+ enabled: false
+ realm: RESTHeart Realm
+ domain: localhost
+ authenticator: mongoRealmAuthenticator
+
+# For development purposes. Always authenticate the request with the given user
+# see https://restheart.org/docs/security/authentication#identity-authentication
+identityAuthMechanism:
+ enabled: false
+ username: admin
+ roles:
+ - admin
+ - user
+----
+
+## Authenticators
+
+[source,yml]
+----
+# fileRealmAuthenticator defines users credentials and roles in a simple yml file.
+# see https://restheart.org/docs/security/authentication#file-realm-authenticator
+fileRealmAuthenticator:
+ enabled: false
+ #conf-file: ./users.yml
+ users:
+ - userid: admin
+ password: null
+ roles: [admin]
+
+# mongoRealAuthenticator authenticates users defined in a MongoDB collection.
+# see https://restheart.org/docs/security/authentication#mongo-realm-authenticator
+mongoRealmAuthenticator:
+ enabled: true
+ users-db: restheart
+ users-collection: users
+ prop-id: _id
+ prop-password: password
+ json-path-roles: $.roles
+ bcrypt-hashed-password: true
+ bcrypt-complexity: 12
+ enforce-minimum-password-strength: false
+ # Integer from 0 to 4
+ # 0 Weak （guesses < 3^10）
+ # 1 Fair （guesses < 6^10）
+ # 2 Good （guesses < 8^10）
+ # 3 Strong （guesses < 10^10）
+ # 4 Very strong （guesses >= 10^10）
+ minimum-password-strength: 3
+ create-user: true
+ create-user-document: '{"_id": "admin", "password": "$2a$12$lZiMMNJ6pkyg4uq/I1cF5uxzUbU25aXHtg7W7sD2ED7DG1wzUoo6u", "roles": ["admin"]}'
+ # create-user-document.password must be hashed when bcrypt-hashed-password=true
+ # default password is 'secret'
+ # see https://bcrypt-generator.com but replace initial '$2y' with '$2a'
+ cache-enabled: false
+ cache-size: 1000
+ cache-ttl: 60000
+ cache-expire-policy: AFTER_WRITE
+----
+
+== Authorizers
+
+[source,yml]
+----
+# fileAclAuthorizer authorizes requests according to the Access Control List defined in a YAML file.
+# see https://restheart.org/docs/security/authorization#file-acl-authorizer
+fileAclAuthorizer:
+ enabled: false
+ #conf-file: ./acl.yml
+ permissions:
+ - role: admin
+ predicate: path-prefix('/')
+ priority: 0
+
+# mongoAclAuthorizer authorizes requests according to the Access Control List defined in a MongoDB collection.
+# see https://restheart.org/docs/security/authorization#mongo-acl-authorizer
+mongoAclAuthorizer:
+ enabled: true
+ acl-db: restheart
+ acl-collection: acl
+ # clients with root-role can execute any request
+ root-role: admin
+ cache-enabled: true
+ cache-size: 1000
+ cache-ttl: 5000
+ cache-expire-policy: AFTER_WRITE
+
+# originVetoer protects from CSRF attacks by forbidding requests whose Origin header is not whitelisted
+# see https://restheart.org/docs/security/authorization#originvetoer
+originVetoer:
+ enabled: false
+ whitelist:
+ - https://restheart.org
+ - http://localhost
+ # optional list of paths for whose the Origin header
+ # is not checked. values can be absolute paths
+ # or patterns like /{var}/path/to/resource/*
+ # ignore-paths:
+ # - /{tenant}/bucket.files/{id}/binary
+ # - /coll/docid
+
+# fullAuthorizer authorizes all requests
+fullAuthorizer:
+ enabled: false
+ authentication-required: true
+----
+
+== Token Managers
+
+[source,yml]
+----
+# Token Manager
+# see https://restheart.org/docs/security/authentication#token-managers
+
+ # If a token-manager is configured, RESTHeart will use it to generate
+ # and verify auth tokens.
+ # If more than one token-manager are defined, the first one will be used
+ # The token is returned to the caller via auth-token header when the user
+ # autheticates successfully. The token can be used by Authentication Mechanisms.
+
+# rndTokenService generates auth tokens using a random number generator.
+rndTokenManager:
+ enabled: true
+ ttl: 15
+ srv-uri: /tokens
+
+# jwtTokenManager generates JWT auth tokens.
+# Use this in clustered deployments, since all nodes sharing the key
+# can verify the token independently
+jwtTokenManager:
+ enabled: false
+ key: secret
+ ttl: 15
+ srv-uri: /tokens
+ issuer: restheart.org
+ audience: null
+ # additional JWT claims from accounts properties
+ account-properties-claims:
+ # - foo # property name
+ # - /nested/property # xpath expr for nested properties
+----
+
+== Mongo Client Provider
+
+[source,yml]
+----
+# Provide the MongoClient via @Inject('mclient') and @Inject('mclient-reactive')
+mclient:
+ # see https://docs.mongodb.com/manual/reference/connection-string/
+ connection-string: mongodb://127.0.0.1
+----
+
+== MongoService: MongoDB REST and Websocket API
+
+[source,yml]
+----
+# MongoDB REST and Websocket API
+# see https://restheart.org/docs/tutorial
+mongo:
+ enabled: true
+ uri: /
+
+ # Use mongo-mounts to expose MongoDb resources binding them to API URIs.
+ #
+ # The parameter 'what' identifies the MongoDb resource to expose.
+ # The format is /db[/coll[/docid]]
+ # Use the wildcard '*' to expose all dbs.
+ #
+ # The parameter 'where' defines the URI to bind the resource to.
+ # It can be an absolute path (eg. /api) or path template (eg. /{foo}/bar/*).
+ # The values of the path templates properties are available:
+ # - in the 'what' property (e.g. what: /{foo}_db/coll)
+ # - programmatically from MongoRequest.getPathTemplateParamenters() method.
+ #
+ # It is not possible to mix absolute paths and path templates: 'where' URIs
+ # need to be either all absolute paths or all path templates.
+ #
+ # Examples:
+ # The following exposes all MongoDb resources.
+ # In this case the URI of a document is /db/coll/docid
+ #
+ # - what: "*"
+ # where: /
+ #
+ # The following binds the URI /database to the db 'db'
+ # In this case the URI of a document is /database/coll/docid
+ #
+ # - what: /db
+ # where: /database
+ #
+ # The following binds the URI /api to the collection 'db.coll'
+ # In this case the URI of a document is /api/docid
+ #
+ # - what: /db/coll
+ # where: /api
+ mongo-mounts:
+ - what: /restheart
+ where: /
+
+ # Default representation format https://restheart.org/docs/mongodb-rest/representation-format/#other-representation-formats
+ default-representation-format: STANDARD
+
+ # Default etag check policy https://restheart.org/docs/mongodb-rest/etag/#etag-policy
+ etag-check-policy:
+ db: REQUIRED_FOR_DELETE
+ coll: REQUIRED_FOR_DELETE
+ doc: OPTIONAL
+
+ # get collection cache speedups GET /coll?cache requests
+ get-collection-cache-enabled: true
+ get-collection-cache-size: 100
+ get-collection-cache-ttl: 10_000 # Time To Live, default 10 seconds
+ get-collection-cache-docs: 1000 # number of documents to cache for each request
+
+ # Check if aggregation variables use operators. https://restheart.org/docs/mongodb-rest/aggregations/#security-considerations
+ aggregation-check-operators: true
+
+ # default-pagesize is the number of documents returned when the pagesize query
+ # parameter is not specified
+ # see https://restheart.org/docs/read-docs#paging
+ default-pagesize: 100
+
+ # max-pagesize sets the maximum allowed value of the pagesize query parameter
+ # generally, the greater the pagesize, the more json serializan overhead occurs
+ # the rule of thumb is not exeeding 1000
+ max-pagesize: 1000
+
+ # local-cache allows to cache the db and collection properties to drammatically
+ # improve performaces. Without caching, a GET on a document would requires
+ # two additional queries to retrieve the db and the collection properties.
+ # Pay attention to local caching only in case of multi-node deployments (horizontal scalability).
+ # In this case a change in a db or collection properties would reflect on other
+ # nodes at worst after TTL milliseconds (cache entries time to live).
+ # In most of the cases Dbs and collections properties only change at development time.
+ local-cache-enabled: true
+ # TTL in milliseconds; specify a value < 0 to never expire cached entries
+ local-cache-ttl: 60000
+
+ # cache for JSON Schemas
+ schema-cache-enabled: true
+ # TTL in milliseconds; specify a value < 0 to never expire cached entries
+ schema-cache-ttl: 60000
+
+ # The time limit in milliseconds for processing queries. Set to 0 for no time limit.
+ query-time-limit: 0
+ # The time limit in milliseconds for processing aggregations. Set to 0 for no time limit.
+ aggregation-time-limit: 0
+
+ # Deprecated: it will be removed in RH v8.0
+ # use requestsMetricsCollector instead, see https://restheart.org/docs/monitoring
+ # see https://restheart.org/docs/mongodb-rest/monitoring
+ # OFF => no gathering, ROOT => gathering at root level, DATABASE => at db level, COLLECTION => at collection level
+ metrics-gathering-level: "OFF"
+----
+
+== MongoDB GraphQL Service
+
+[source,yml]
+----
+# MongoDB GraphQL API
+# see https://restheart.org/docs/mongodb-graphql/
+graphql:
+ uri: /graphql
+ db: restheart
+ collection: gql-apps
+ # app definitions are cached. this sets the time to live in msecs
+ app-def-cache-ttl: 10_000
+ # default-limit is used for queries that don't not specify a limit
+ default-limit: 100
+ # max-limit is the maximum value for a Query limit
+ max-limit: 1000
+ # The time limit in milliseconds for processing queries. Set to 0 for no time limit.
+ query-time-limit: 0
+ verbose: false
+----
+
+== Proxied resources
+
+[source,yml]
+----
+# Proxied resources - expose exrernal API with RESTHeart acting as a reverese proxy
+# see https://restheart.org/docs/proxy
+# options:#
+# - location (required) The location URI to bound to the HTTP proxied server.
+# - proxy-pass (required) The URL of the HTTP proxied server. It can be an array of URLs for load balancing.
+# - name (optional) The name of the proxy. It is required to identify 'restheart'.
+# - rewrite-host-header (optional, default true) should the HOST header be rewritten to use the target host of the call.
+# - connections-per-thread (optional, default 10) Controls the number of connections to create per thread.
+# - soft-max-connections-per-thread (optional, default 5) Controls the number of connections to create per thread.
+# - max-queue-size (optional, default 0) Controls the number of connections to create per thread.
+# - connections-ttl (optional, default -1) Connections Time to Live in seconds.
+# - problem-server-retry (optional, default 10) Time in seconds between retries for problem server.
+proxies:
+# - location: /anything
+# proxy-pass: https://httpbin.org/anything
+# name: anything
+----
+
+== Static Web Resources
+
+[source,yml]
+----
+# Static Web Resources - serve static files with RESTHeart acting a web server
+# see https://restheart.org/docs/static-resources
+static-resources:
+# - what: /path/to/resources
+# where: /static
+# welcome-file: index.html
+# embedded: false
+----
+
+== Other services
+
+[source,yml]
+----
+# Service to GET and DELETE (invalidate) the user auth token generated by the TokenManager
+authTokenService:
+ uri: /tokens
+
+# Simple ping service
+ping:
+ enabled: true
+ msg: Greetings from RESTHeart!
+
+# Returns the roles of the authenticated user
+roles:
+ uri: /roles
+
+# a global blacklist for mongodb operators in filter query parameter
+filterOperatorsBlacklist:
+ blacklist: [ "$where" ]
+ enabled: true
+
+# bruteForceAttackGuard defends from brute force password cracking attacks
+# by returning `429 Too Many Requests` when more than
+# `max-failed-attempts` requests with wrong credentials
+# are received in last 10 seconds from the same ip
+bruteForceAttackGuard:
+ enabled: false
+ # max number of failed attempts in 10 seconds sliding window
+ # before returning 429 Too Many Requests
+ max-failed-attempts: 5
+ # if true, the source ip is obtained from X-Forwarded-For header
+ # this requires that header beeing set by the proxy, dangerous otherwise
+ trust-x-forwarded-for: false
+ # when X-Forwarded-For has multiple values,
+ # take into account the n-th from last element
+ # e.g. with [x.x.x.x, y.y.y.y., z.z.z.z, k.k.k.k]
+ # 0 -> k.k.k.k
+ # 2 -> y.y.y.y
+ x-forwarded-for-value-from-last-element: 0
+----
+
+== Logging
+
+[source,yml]
+----
+# Logging
+# see https://restheart.org/docs/logging
+# Options:
+# - log-level: to set the log level. Value can be OFF, ERROR, WARN, INFO, DEBUG, TRACE and ALL. (default value is INFO)
+# - log-to-console: true => log messages to the console (default value: true)
+# - ansi-console: use Ansi console for logging. Default to 'true' if parameter missing, for backward compatibility
+# - log-to-file: true => log messages to a file (default value: false)
+# - log-file-path: to specify the log file path (default value: restheart.log in system temporary directory)
+# - packages: only messages form these packages are logged, e.g. [ "org.restheart", "com.restheart", "io.undertow", "org.mongodb" ]
+# - full-stacktrace: true to log the full stacktrace of exceptions
+# - requests-log-mode: 0 => no log, 1 => light log, 2 => detailed dump (use 2 only for development, it can log credentials)
+# - tracing-headers (default, empty = no tracing): add tracing HTTP headers (Use with %X{header-name} in logback.xml); see https://restheart.org/docs/auditing
+
+logging:
+ log-level: INFO
+ log-to-console: true
+ ansi-console: true
+ log-to-file: false
+ log-file-path: restheart.log
+ packages: [ "org.restheart", "com.restheart" ]
+ full-stacktrace: false
+ requests-log-mode: 1
+ tracing-headers:
+ # - x-b3-traceid # vv Zipkin headers, see https://github.com/openzipkin/b3-propagation
+ # - x-b3-spanid
+ # - x-b3-parentspanid
+ # - x-b3-sampled # ^^
+ # - uber-trace-id # jaeger header, see https://www.jaegertracing.io/docs/client-libraries/#trace-span-identity
+ # - traceparent # vv opencensus.io headers, see https://github.com/w3c/distributed-tracing/blob/master/trace_context/HTTP_HEADER_FORMAT.md
+ # - tracestate # ^^
+----
+
+== Metrics
+
+[source,yml]
+----
+# Metrics
+# see https://restheart.org/docs/metrics
+requestsMetricsCollector:
+ enabled: false
+ uri: /metrics
+ include: [ "/*" ]
+ exclude: [ "/metrics", "/metrics/*" ]
+
+jvmMetricsCollector:
+ enabled: false
+----
+== Core module configuration
+
+[source,yml]
+----
+# base configuration for core module
+core:
+ # The name of this instance. Displayed in log, also allows to implement instance specific custom code
+ name: default
+
+ # The directory containing the plugins jars.
+ # The path is either absolute (starts with /) or relative to the restheart.jar file
+ # Just add the plugins jar to plugins-directory and they will be automatically
+ # added to the classpath and registered.
+ plugins-directory: plugins
+
+ # Limit the scanning of classes annotated with @RegisterPlugin
+ # to the specified packages. It can speedup the boot time
+ # in case of huge plugin jars. It is usually not required.
+ # Use an empty array to not limit scanning.
+ # Alsways add the package org.restheart to the list
+ plugins-packages: []
+
+ # Set to true for verbose logging of jar scanning for plugins
+ plugins-scanning-verbose: false
+
+ # Optionally define the base url of this instance
+ # Useful when RESTHeart is mediated by a reverse proxy or an API gateway to determine the instance's correct URL
+ base-url: null
+
+ # Number of I/O threads created for non-blocking tasks. Suggested value: core*8.
+ # if <= 0, use the number of cores.
+ io-threads: 0
+
+ # Number of threads created for blocking tasks (such as ones involving db access). Suggested value: core*8
+ # if < 0, use the number of cores * 8. With 0 working threads, blocking services won't work.
+ worker-threads: -1
+
+ # Limit for the maximum number of concurrent requests being served
+ requests-limit: 1000
+
+ # 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
+ # Setting to 1024 * 16 - 20; the 20 is to allow some space for getProtocol headers, see UNDERTOW-1209
+ buffer-size: 16364
+
+ # Should the buffer pool use direct buffers, this instructs the JVM to use native (if possible) I/O operations on the buffers
+ direct-buffers: true
+
+ # In order to save bandwitdth, force requests to support the giz encoding (if not, requests will be rejected)
+ force-gzip-encoding: false
+
+ # true to allow unescaped characters in URL
+ allow-unescaped-characters-in-url: true
+----
+
+== Connection options
+
+[source,yml]
+----
+# Connection Options
+connection-options:
+ # Enable HTTP/2 support
+ # Note: HTTP2 as implemented by major browsers requires the use of TLS
+ # How to enable TLS https://restheart.org/docs/security/tls/
+ # How to check HTTP/2 protocol https://stackoverflow.com/a/54164719/4481670
+ ENABLE_HTTP2: true
+
+ # The maximum size of a HTTP header block, in bytes.
+ # If a client sends more data that this as part of the request header then the connection will be closed.
+ # Defaults to 1Mbyte.
+ MAX_HEADER_SIZE: 1048576
+
+ # The default maximum size of a request entity.
+ # Defaults to unlimited.
+ MAX_ENTITY_SIZE: -1
+
+ #The default maximum size of the HTTP entity body when using the mutiltipart parser.
+ # Generall this will be larger than MAX_ENTITY_SIZE
+ # If this is not specified it will be the same as MAX_ENTITY_SIZE
+ MULTIPART_MAX_ENTITY_SIZE: -1
+
+ # The idle timeout in milliseconds after which the channel will be closed.
+ # If the underlying channel already has a read or write timeout set
+ # the smaller of the two values will be used for read/write timeouts.
+ # Defaults to unlimited (-1).
+ IDLE_TIMEOUT: -1
+
+ # The maximum allowed time of reading HTTP request in milliseconds.
+ # -1 or missing value disables this functionality.
+ REQUEST_PARSE_TIMEOUT: -1
+
+ # The amount of time the connection can be idle with no current requests
+ # before it is closed;
+ # Defaults to unlimited (-1).
+ NO_REQUEST_TIMEOUT: -1
+
+ # The maximum number of query parameters that are permitted in a request.
+ # If a client sends more than this number the connection will be closed.
+ # This limit is necessary to protect against hash based denial of service attacks.
+ # Defaults to 1000.
+ MAX_PARAMETERS: 1000
+
+ # The maximum number of headers that are permitted in a request.
+ # If a client sends more than this number the connection will be closed.
+ # This limit is necessary to protect against hash based denial of service attacks.
+ # Defaults to 200.
+ MAX_HEADERS: 200
+
+ # The maximum number of cookies that are permitted in a request.
+ # If a client sends more than this number the connection will be closed.
+ # This limit is necessary to protect against hash based denial of service attacks.
+ # Defaults to 200.
+ MAX_COOKIES: 200
+
+ # The charset to use to decode the URL and query parameters.
+ # Defaults to UTF-8.
+ URL_CHARSET: UTF-8
+
+ # If this is true then a Connection: keep-alive header will be added to responses,
+ # even when it is not strictly required by the specification.
+ # Defaults to true
+ ALWAYS_SET_KEEP_ALIVE: true
+
+ # If this is true then a Date header will be added to all responses.
+ # The HTTP spec says this header should be added to all responses,
+ # unless the server does not have an accurate clock.
+ # Defaults to true
+ ALWAYS_SET_DATE: true
+----
\ No newline at end of file
diff --git a/docs/v7/enterprise-license.md b/docs/v7/enterprise-license.md
new file mode 100644
index 00000000..8d727142
--- /dev/null
+++ b/docs/v7/enterprise-license.md
@@ -0,0 +1,167 @@
+---
+title: Enterprise License
+layout: docs
+menu: setup
+---
+
+> {
+ return this.http.get>(`${this.url}?pagesize=5&page=${page}`);
+ }
+
+ public size(): Observable {
+ return this.http.get(`${this.url}/_size`);
+ }
+
+ public post(data: any): Observable {
+ const _data = {
+ message: data.message,
+ from: data.from
+ };
+
+ return this.http.post(this.url, _data);
+ }
+}
+----
+
+== Sending a Message Using cURL
+
+In this section, we'll demonstrate how to send a chat message using the API with `curl`. By sending a POST request to link:https://demo.restheart.org/messages[demo.restheart.org/messages^], you can interact with the chat application programmatically.
+
+To send a message, use the following cURL command:
+
+[source,bash]
+----
+$ curl -i -H "Content-Type: application/json" -X POST https://demo.restheart.org/messages/ -d '{"from":"you", "message":"RESTHeart rocks!!" }'
+
+HTTP/1.1 201 Created
+----
+
+++++
+{% include code-header.html
+ link="http://restninja.io/share/1fd808b1f51037c8b2b36d43d6bc315a0325029c/3"
+%}
+++++
\ No newline at end of file
diff --git a/docs/v7/faq.adoc b/docs/v7/faq.adoc
new file mode 100644
index 00000000..9220a8ad
--- /dev/null
+++ b/docs/v7/faq.adoc
@@ -0,0 +1,96 @@
+---
+title: RESTHeart FAQ
+layout: docs-adoc
+menu: overview
+---
+
+### What is RESTHeart?
+
+RESTHeart is a framework for building HTTP microservices that aims to empower developers with intuitive APIs out of the box. It is built for developers, with a focus on simplicity, speed and ease of use.
+
+It provides features commonly needed by applications like authentication/authorization and data management through MongoDB integration.
+
+It has a modular architecture where core functionality is provided by restheart-core, and additional features are implemented as plugins.
+
+'''
+
+### In which programming language is RESTHeart written?
+
+RESTHeart is primarily written in Java. Thanks to GraalVM, its SDK extends support to Java, Kotlin, JavaScript, and TypeScript. Implementing Hello World examples in any of these languages is straightforward.
+
+Furthermore, RESTHeart is available and can be built with custom plugins as a binary executable, allowing for additional flexibility.
+
+'''
+
+### Is it Open Source?
+
+Absolutely! RESTHeart is released under the AGPL Open Source License, along with an Enterprise License.
+
+The complete codebase is open source, and there are no distinctions in features between the AGPL and Enterprise License.
+
+The Enterprise License is specifically designed for organizations seeking extra assurances and professional support.
+
+'''
+
+### How does it support MongoDB?
+
+The MongoDB plugin exposes the full database capabilities through REST, GraphQL and Websockets with no backend code required. This cuts development time significantly.
+
+'''
+
+### What security features are supported?
+
+RESTHeart offers comprehensive authentication and authorization services, supporting various security schemes. It enables the management of users and permissions directly in MongoDB collections, eliminating the need for backend code. This streamlined approach significantly reduces development time.
+
+'''
+
+### Why restheart is classified as a low code framework?
+
+RESTHeart is classified as a low-code framework because it offers developers customizable APIs that are ready to go. It aims to empower developers with an intuitive framework that encompasses essential features, allowing them to build applications without the need to reinvent the wheel. RESTHeart provides pre-configured APIs that cover a broad range of functionality and are highly customizable to fit specific application needs. This approach reduces the amount of code developers need to write, streamlining the development process and making it easier and faster to build cloud-native HTTP microservices.
+
+'''
+
+### How can I extend the API?
+
+A plugin is a software component that extends the functionality of RESTHeart, allowing you to add additional features and capabilities to the basic API. RESTHeart supports the development of plugins in Java, Kotlin, and JavaScript.
+
+To add a plugin to RESTHeart, you need to follow these steps:
+
+1. Package your plugin as a JAR file for Java or Kotlin plugins, or as a JavaScript file and its companion package.json for JavaScript plugins.
+2. Copy the JAR or JavaScript plugin into the `./plugins` directory of your RESTHeart installation.
+3. Restart RESTHeart to apply the changes and load the plugin.
+
+Once the plugin is added and RESTHeart is restarted, it will be automatically detected and integrated into the RESTHeart framework, extending its functionality according to the features implemented in the plugin.
+
+Please note that for JavaScript plugins, you need to run RESTHeart on GraalVM or on RESTHeart native.
+
+'''
+
+### What categories of plugins are available?
+
+There are four types of plugins in RESTHeart:
+
+1. `Service`: These plugins extend the API by adding web services.
+2. `Interceptor`: These plugins snoop and modify requests and responses at different stages of the request lifecycle.
+3. `Initializer`: These plugins execute initialization logic at system startup time.
+4. `Provider`: These plugins provide objects to other plugins via the `@Inject` annotation.
+
+Additionally, it is also possible to develop security plugins to customize the security layer.
+
+'''
+
+### What about performances?
+
+In RESTHeart performance is a priority with support for huge throughput, horizontal scaling, and GraalVM for better performance in containers.
+
+It is designed for microservices deployment in Docker/Kubernetes and can run as a standalone JAR, native binary or Docker image.
+
+'''
+
+### Does the SDK provide a Dependency Injection feature?
+
+Yes! Dependency injection in RESTHeart works by using the `@Inject` and `@OnInit` annotations in conjunction with provider classes.
+
+To implement dependency injection, a provider class must implement the `Provider` interface and be annotated with `@RegisterPlugin`. The provider class provides the object that will be injected into other classes.
+
+Overall, dependency injection in RESTHeart allows for the easy injection of provided objects into other classes, reducing the need for manual object creation and management.
\ No newline at end of file
diff --git a/docs/v7/graalvm.md b/docs/v7/graalvm.md
new file mode 100644
index 00000000..fbdaea96
--- /dev/null
+++ b/docs/v7/graalvm.md
@@ -0,0 +1,193 @@
+---
+title: GraalVM
+layout: docs
+menu: setup
+---
+
+
+
+ true
+
+ %d{HH:mm:ss.SSS} [%thread] %highlight(%-5level) %logger{36} - %msg%n %throwable{short}
+
+
+
+
+
+
+----
+
+IMPORTANT: the default configuration logs messages only from the packages `org.restheart` and `com.restheart`. If you are developing a plugin, you'll need to modify the configuration to get log messages from your classes.
+
+The following command executes RESTHeart overriding the configuration to enable logging from the classes of the package `com.foo.bar` and its sub-packages:
+
+[source,bash]
+----
+$ RHO='/logging/packages -> [ "org.restheart", "com.restheart", "com.foo.bar" ]' java -jar restheart.jar
+----
+
+== Logging configuration
+
+The default logging configuration follows:
+
+[source,yml]
+----
+# Logging
+# see https://restheart.org/docs/logging
+# Options:
+# - log-level: to set the log level. Value can be OFF, ERROR, WARN, INFO, DEBUG, TRACE and ALL. (default value is INFO)
+# - log-to-console: true => log messages to the console (default value: true)
+# - ansi-console: use Ansi console for logging. Default to 'true' if parameter missing, for backward compatibility
+# - log-to-file: true => log messages to a file (default value: false)
+# - log-file-path: to specify the log file path (default value: restheart.log in system temporary directory)
+# - packages: only messages form these packages are logged, e.g. [ "org.restheart", "com.restheart", "io.undertow", "org.mongodb" ]
+# - full-stacktrace: true to log the full stackstrace of exceptions
+# - requests-log-mode: 0 => no log, 1 => light log, 2 => detailed dump (use 2 only for development, it can log credentials)
+# - tracing-headers (default, empty = no tracing): add tracing HTTP headers (Use with %X{header-name} in logback.xml); see https://restheart.org/docs/auditing
+
+logging:
+ log-level: INFO
+ log-to-console: true
+ ansi-console: true
+ log-to-file: false
+ log-file-path: restheart.log
+ packages: [ "org.restheart", "com.restheart" ]
+ full-stacktrace: false
+ requests-log-mode: 1
+ tracing-headers:
+ # - x-b3-traceid # vv Zipkin headers, see https://github.com/openzipkin/b3-propagation
+ # - x-b3-spanid
+ # - x-b3-parentspanid
+ # - x-b3-sampled # ^^
+ # - uber-trace-id # jaeger header, see https://www.jaegertracing.io/docs/client-libraries/#trace-span-identity
+ # - traceparent # vv opencensus.io headers, see https://github.com/w3c/distributed-tracing/blob/master/trace_context/HTTP_HEADER_FORMAT.md
+ # - tracestate # ^^
+----
+
+== Specify a custom LogBack configuration
+
+To define a different LogBack configuration, set the property `logback.configurationFile`, as follows:
+
+[source,bash]
+$ java -Dlogback.configurationFile=./logback.xml -jar restheart.jar
+
+== Custom LogBack with docker compose
+
+To use a custom LogBack configuration when running RESTHeart with docker compose:
+
+1. override the `entrypoint` to specify the `logback.configurationFile` JVM property
+2. mount the custom `logback.xml` configuration file into the docker image using `volume`
+
+Replace the `restheart` service definition in the link:https://github.com/SoftInstigate/restheart/blob/master/docker-compose.yml[docker-compose.yml] with the following:
+
+[source,yml]
+----
+ restheart:
+ image: softinstigate/restheart:latest
+ container_name: restheart
+ # override the entrypoint to specify the logback.configurationFile JVM property
+ entrypoint: [ "java", "-Dfile.encoding=UTF-8", "-Dlogback.configurationFile=etc/logback.xml", "-server", "-jar", "restheart.jar", "etc/restheart.yml"]
+ # mount the custom `logback.xml` configuration file
+ volumes:
+ - ./etc/logback.xml:/opt/restheart/etc/logback.xml:ro
+ command: ["--envFile", "/opt/restheart/etc/default.properties"]
+ environment:
+ RHO: >
+ /mclient/connection-string->"mongodb://mongodb";
+ /http-listener/host->"0.0.0.0";
+ depends_on:
+ - mongodb
+ - mongodb-init
+ ports:
+ - "8080:8080"
+----
+
+== Example: print the full stack trace
+
+The following command sets the configuration option `/logging/full-stacktrace` to `true` to configure the logback appender to log the full stack trace of exceptions
+
+[source,bash]
+----
+$ RHO='/logging/full-stacktrace->true' java -jar restheart.jar
+----
+
+NOTE: `/logging/full-stacktrace` is available from RESTHeart 7.2.0. For previous releases you need to specify a custom `logback.xml` configuration file.
+
+== Example: enable logging from the MongoDB driver
+
+To enable logging from the MongoDB driver, override the configuration option `/logging/packages` as follows:
+
+[source,bash]
+----
+$ RHO='/logging/packages -> [ "org.restheart", "com.restheart", "org.mongodb" ]' java -jar restheart.jar
+----
+
+== Example: log trace headers
+
+Trace headers allow to trace a request context propagation across service boundaries. See for reference link:https://github.com/openzipkin/b3-propagation[b3-propagation]
+
+Too enable log trace headers first override the `/logging/equests-log-trace-headers` configuration options
+
+Then a custom `logback.xml` with the following `pattern` (note that it includes `%X{x-b3-traceid}`) must be used:
+
+[source,xml]
+----
+
+
+
+ true
+
+ %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread / %X{x-b3-traceid}] %-5level %logger{36} - %msg%n
+
+
+
+
+
+
+----
+
+[source,bash]
+----
+$ RHO='/logging/requests-log-trace-headers -> [ "x-b3-traceid", "uber-trace-id", "traceparent" ]' java -Dlogback.configurationFile=./logback.xml -jar restheart.jar
+----
+
+NOTE: Watch link:https://www.youtube.com/watch?v=dzggm7Wp2fU&t=1152s[Logging]
\ No newline at end of file
diff --git a/docs/v7/mongodb-graphql/complex-app-example.adoc b/docs/v7/mongodb-graphql/complex-app-example.adoc
new file mode 100644
index 00000000..791805d2
--- /dev/null
+++ b/docs/v7/mongodb-graphql/complex-app-example.adoc
@@ -0,0 +1,310 @@
+---
+title: A Complex GraphQL App
+layout: docs-adoc
+menu: mongodb
+---
+
+:page-liquid:
+
+== Before running the tutorial
+
+This tutorial assume:
+
+- RESTHeart Platform running on the localhost with the default configuration: the database *restheart* is bound to `/`, the user *admin* exists with default password *secret*, *gql-apps* is the collection, within `restheart` database, reserved to GraphQL apps definitions and the GraphQL service is reachable at `/graphql`.
+- The `sample-mflix` database (see link:/docs/mongodb-rest/sample-data[Load Sample Data into MongoDB]) is stored in the MongoDB instance associated to RESTHeart.
+
+NOTE: *Execute on rest ninja* doesn't work with Safari because it requires HTTPS. Since configuring HTTPS requires a valid certificate and takes some time to link:/docs/security/tls/[configure], we suggest to just use Chrome or Firefox for this tutorial.
+
+
+## Create the GraphQL app
+
+To create the *gql-apps* collection, run the following:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/cf0d3d9a0f811cf5d6921ad66fcf49cbad852a5a/0"
+%}
+++++
+
+[source, http]
+PUT /gql-apps HTTP/1.1
+
+To upload the example GraphQL app definition, run the following:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/cb7df9b7270fd8eb1657b925f3f8c7e2277af350/1"
+%}
+++++
+
+[source,http]
+POST /gql-apps HTTP/1.1
+
+[.text-muted]
+*Request body*
+[source,json]
+----
+{
+ "_id": "mflix-gql-def",
+ "descriptor": {
+ "name":"MFlix",
+ "description":"GraphQL App example using MongoDB sample_mflix dataset",
+ "enabled": true,
+ "uri":"mflix"
+ },
+ "schema": "type Stats { year: Int moviesNum: Int } type Comment{ _id: ObjectId user: User movie: Movie text: String date: DateTime}type Movie{ _id: ObjectId title: String year: Int runtime: Int released: DateTime poster: String plot: String fullPlot: String lastUpdate: String filmType: String directors: [String] imdbRate: Float imdbVotes: Int countries: [String] genres: [String] tomatoesRate: Float tomatoesReviewsNum: Int comments(startDate: DateTime = \"-9223372036854775808\", endDate: DateTime = \"9223372036854775807\", sort: Int = 1, skip: Int = 0, limit: Int = 0): [Comment] relatedMovies: [Movie]}type Session{ _id: ObjectId user: User jwt: String} type Theater{ theaterId: Int location: BsonDocument} type User{ _id: ObjectId name: String email: String comments(startDate: DateTime = \"-9223372036854775808\", endDate: DateTime = \"9223372036854775807\", sort: Int = 1, skip: Int = 0, limit: Int = 0): [Comment]}type Query{ MoviesByTitle(title: String!): [Movie] MoviesByYear(year: Int!, sort: Int = 1, skip: Int = 0, limit: Int = 0): [Movie] UserByEmail(email: String!): [User] StatsByTomatoesRateRange(min: Float max: Float = 10): [Stats] MoviesByTomatoesRateRange(min: Float, max: Float, sort: Int = 1, skip: Int = 0, limit: Int = 0):[Movie] TheatersByCity(city: String!, sort: Int = 1, skip: Int = 0, limit: Int = 0): [Theater] AllMovies(limit: Int = 10, skip: Int = 0): [Movie]}",
+ "mappings": {
+ "Comment": {
+ "user": {
+ "db":"sample_mflix",
+ "collection":"users",
+ "find": { "email": { "$fk":"email" } },
+ "dataLoader": { "batching": true, "caching": true }
+ },
+ "movie": {
+ "db":"sample_mflix",
+ "collection":"movies",
+ "find": { "_id": { "$fk":"movie_id" } },
+ "dataLoader": { "batching": true, "caching": false, "maxBatchSize": 30 }
+ }
+ },
+ "Movie": {
+ "imdbRate":"imdb.rating",
+ "imdbVotes":"imdb.votes",
+ "tomatoesRate":"tomatoes.viewer.rating",
+ "tomatoesReviewsNum":"tomatoes.viewer.numReviews",
+ "lastUpdate":"lastupdated",
+ "fullPlot":"fullplot",
+ "filmType":"type",
+ "comments": {
+ "db":"sample_mflix",
+ "collection":"comments",
+ "find": { "$and": [{ "movie_id": { "$fk":"_id" } }, { "date": { "$gte": { "$arg":"startDate" }, "$lt": { "$arg":"endDate" } } }] },
+ "sort": { "date": { "$arg":"sort" } },
+ "skip": { "$arg":"skip" },
+ "limit": { "$arg":"limit" }
+ }
+ },
+ "Session": {
+ "user": {
+ "db":"sample_mflix",
+ "collection":"user",
+ "find": { "email": { "$fk":"user_id" } }
+ }
+ },
+ "User": {
+ "comments": {
+ "db":"sample_mflix",
+ "collection":"comments",
+ "find": { "email": { "$fk":"email" } },
+ "sort": { "_id": { "$arg":"sort" } },
+ "skip": { "$arg":"skip" },
+ "limit": { "$arg":"limit" }
+ }
+ },
+ "Query": {
+ "StatsByTomatoesRateRange": {
+ "db": "sample_mflix",
+ "collection": "movies",
+ "stages": [
+ { "$match": { "imdb.rating": { "$gte": { "$arg":"min" }, "$lte": { "$arg":"max" } }, "year": { "$type": "int" } } },
+ { "$group": { "_id": "$year", "moviesNum": { "$count": {} } } },
+ { "$project": { "_id": 0, "year": "$_id", "moviesNum": 1} },
+ { "$sort": { "year": 1 } }
+ ]
+ },
+ "MoviesByTitle": {
+ "db":"sample_mflix",
+ "collection":"movies",
+ "find": { "title": { "$arg":"title" } }
+ },
+ "MoviesByYear": {
+ "db":"sample_mflix",
+ "collection":"movies",
+ "find": { "year": { "$arg":"year" } },
+ "sort": { "_id": { "$arg":"sort" } },
+ "skip": { "$arg":"skip" },
+ "limit": { "$arg":"limit" }
+ },
+ "UserByEmail": {
+ "db":"sample_mflix",
+ "collection":"users",
+ "find": { "email": { "$arg":"email" } }
+ },
+ "MoviesByTomatoesRateRange": {
+ "db":"sample_mflix",
+ "collection":"movies",
+ "find": { "tomatoes.viewer.rating": { "$gte": { "$arg":"min" }, "$lt": { "$arg":"max" } } },
+ "sort": { "tomatoes.viewer.rating": { "$arg":"sort" }, "_id": 1 },
+ "skip": { "$arg":"skip" },
+ "limit": { "$arg":"limit" }
+ },
+ "TheatersByCity": {
+ "db":"sample_mflix",
+ "collection":"theaters",
+ "find": { "location.address.city": { "$arg":"city" } },
+ "sort": { "location.address.city": { "$arg":"sort" } },
+ "skip": { "$arg":"skip" },
+ "limit": { "$arg":"limit" }
+ },
+ "AllMovies": {
+ "db":"sample_mflix",
+ "collection":"movies",
+ "find": { },
+ "sort": { "_id_": -1 },
+ "skip": { "$arg":"skip" },
+ "limit": { "$arg":"limit" }
+ }
+ }
+ }
+}
+----
+
+== query with `application/json`
+
+To execute a GraphQL request to *Mflix* app with *Content-Type* `application/json`, run the following:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/e2aed3eb5867ee201b0bee790e3924a16da2219b/0"
+%}
+++++
+
+[source,http]
+POST /graphql/mflix HTTP/1.1
+
+[.text-muted]
+*Request body*
+[source,json]
+----
+{
+ "query":"query exampleOperation($year: Int!, $limit: Int = 0){MoviesByYear(year: $year, limit: $limit){ title comments{ text user{name} date} tomatoesRate}}",
+ "variables":{
+ "year":2008,
+ "limit":2
+ }
+}
+----
+
+++++
+{% include code-header.html
+ type="Response"
+%}
+++++
+
+[source,json]
+----
+{
+ "data": {
+ "MoviesByYear": [
+ {
+ "title": "The Bank Job",
+ "comments": [
+ {
+ "text": "Pariatur voluptatibus placeat quo architecto soluta non...",
+ "user": {
+ "name": "Shireen Baratheon"
+ },
+ "date": {
+ "$date": 954044557000
+ }
+ },
+ {
+ "text": "Facilis ea voluptatem et velit rerum animi corrupti...",
+ "user": {
+ "name": "Lisa Russo"
+ },
+ "date": {
+ "$date": 976465077000
+ }
+ }
+ ],
+ "tomatoesRate": 3.5
+ },
+ {
+ "title": "The Flyboys",
+ "comments": [],
+ "tomatoesRate": 3.6
+ }
+ ]
+ }
+}
+----
+
+== query with `application/graphql`
+
+To execute a GraphQL request to *Mflix* app with *Content-Type* `application/graphql`, run the following:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/705cbffaa3daca184dde2958b15ffd5563faab46/0"
+%}
+++++
+
+[source,http]
+POST /graphql/mflix HTTP/1.1
+
+[.text-muted]
+*Request body*
+[source,graphql]
+----
+{
+ MoviesByTomatoesRateRange(min: 3.8, max: 4.5, limit: 3, skip: 20, sort: -1){
+ title
+ comments {
+ text
+ user { name }
+ }
+ tomatoesRate
+ }
+}
+----
+
+++++
+{% include code-header.html
+ type="Response"
+%}
+++++
+
+[source,json]
+----
+{
+ "data": {
+ "MoviesByTomatoesRateRange": [
+ {
+ "title": "The Wages of Fear",
+ "comments": [
+ {
+ "text": "Commodi accusamus totam eaque sunt. Nihil reiciendis commodi molestiae esse...",
+ "user": {
+ "name": "Doreah"
+ }
+ }
+ ],
+ "tomatoesRate": 4.4
+ },
+ {
+ "title": "Chicago Deadline",
+ "comments": [
+ {
+ "text": "Nihil itaque a architecto. Illo veritatis totam at quibusdam. Doloremque...",
+ "user": {
+ "name": "Patricia Good"
+ }
+ }
+ ],
+ "tomatoesRate": 4.4
+ },
+ {
+ "title": "The Passion of Joan of Arc",
+ "comments": [],
+ "tomatoesRate": 4.4
+ }
+ ]
+ }
+}
+----
diff --git a/docs/v7/mongodb-graphql/graphql-apps.adoc b/docs/v7/mongodb-graphql/graphql-apps.adoc
new file mode 100644
index 00000000..b874ac91
--- /dev/null
+++ b/docs/v7/mongodb-graphql/graphql-apps.adoc
@@ -0,0 +1,638 @@
+---
+title: GraphQL API
+layout: docs-adoc
+menu: mongodb
+---
+
+== Overview
+
+The `restheart-graphql` plugin exposes a read-only (no mutations and subscription) GraphQL API for inquiring MongoDB resources.
+
+The GraphQL API works side by side with the REST API to build modern applications.
+
+== Configuration
+
+For each GraphQL application you need to define a so called *GraphQL app definition*. This is a JSON document to be created by default in the `/graphql` collection.
+
+The GraphQL plugin default configuration follows:
+ It also allows to specify the collection that holds the app definitions.
+
+[source,yml]
+----
+graphql:
+ uri: /graphql
+ db: restheart
+ collection: gql-apps
+ # app definitions are cached. this sets the time to live in msecs
+ app-def-cache-ttl: 10_000
+ # default-limit is used for queries that don't not specify a limit
+ default-limit: 100
+ # max-limit is the maximum value for a Query limit
+ max-limit: 1000
+ # The time limit in milliseconds for processing queries. Set to 0 for no time limit.
+ query-time-limit: 0
+ verbose: false
+----
+
+The GraphQL application can be dynamically created and updated by simply creating or updating the related document in MongoDB.
+
+== GraphQL App Definition
+
+A GraphQL application definition is composed by three sections:
+
+[source,json]
+----
+{
+ "descriptor": "...",
+ "schema": "...",
+ "mappings": "..."
+}
+----
+
+== Descriptor
+
+Here you can specify:
+
+- `name`: GraphQL application name.
+- `description`: GraphQL application description.
+- `enabled`: can be `true` or `false`.
+- `uri`: specifies at which endpoint your GraphQL application is reachable (e.g. `/graphql/uri`). If the `uri` parameter is missing the application's name is used instead.
+
+[source,json]
+----
+{
+ "descriptor": {
+ "name": "MyApp",
+ "description": "my first test GraphQL application",
+ "enabled": true,
+ "uri": "myapp"
+ },
+ "schema": "...",
+ "mappings": "..."
+}
+----
+
+== Schema
+
+This section must contain GraphQL application's schema written with *Schema Definition Language* (SDL). For example:
+
+[source,json]
+----
+{
+ "descriptor": "...",
+ "schema": "type User{name: String surname: String email: String posts: [Post]} type Post{text: String author: User} type Query{users(limit: Int = 0, skip: Int = 0)}",
+ "mappings": "..."
+}
+----
+
+NOTE: In order the schema to be a valid, it must contain the type *Query*.
+
+== Mappings
+
+GraphQL types are connected to MongoDB data through mappings.
+
+Mappings are applicable to a range of types, including Object, Query, `enum`, `interfaces`, and `union`.
+
+=== Field to Field mapping
+
+You can map a GraphQL Object field with a specific MongoDB document field or with an element of a MongoDB array. To map nested fields use the **dot-notation**.
+
+An example follows:
+
+[source,json]
+----
+{
+ "descriptor": "...",
+ "schema": "...",
+ "mappings":{
+ "User": {
+ "name": "firstName",
+ "phone": "contacts.phone",
+ "email": "contacts.emails.0",
+ },
+ "Post": "...",
+ "Query": "..."
+ }
+}
+----
+
+In this configuration:
+
+The `name` field is linked to the MongoDB document's `firstName` field.
+The `phone` field is associated with the `phone` field within the nested `contacts` document.
+The `email` field is connected to the first element of the `emails` array within the nested `contacts` document.
+
+NOTE: if you don't explicitly define a mapping for a field, RESTHeart will automatically map it to the MongoDB document field with the same name.
+
+=== Field to Query mapping
+
+You can establish a mapping between a GraphQL Object field and a MongoDB query using the following parameters:
+
+- `db` (String): The name of the database.
+- `collection` (String): The name of the collection.
+- `find` (Document): The selection filter using query operators such as `$in`, `$and`, `$or`, and others.
+- `sort` (Document): The order in which the query returns matching documents.
+- `skip` (Document or Integer): The number of documents to skip among those resulting from the query.
+- `limit` (Document or Integer): The maximum number of documents to return among those resulting from the query.
+
+NOTE: It's important to note that unlimited queries are not allowed. If the query doesn't specify a `limit`, the service configuration's `default-limit` is applied. Additionally, the limit cannot exceed the `max-limit`.
+
+=== Field to Aggregation mapping
+
+You can link a GraphQL Object field with a MongoDB aggregation using the following parameters:
+
+- `db` (String): The name of the database.
+- `collection` (String): The name of the collection.
+- `stages` (Array): An array of aggregation stages.
+
+Similar to field-to-query mapping, you can utilize `$arg` and `$fk` operators within aggregation stages. In reference to the previous mapping example, the following aggregation stages are possible:
+
+[source,json]
+----
+"Query": {
+ "countPostsByCategory": {
+ "db": "restheart",
+ "collection": "users",
+ "stages": [
+ { "$group": { "_id": "$category", "count": { "$count": {} } } }
+ ]
+ }
+ }
+----
+
+And the Query in the GraphQL schema will now have the following field:
+
+[source,graphql]
+----
+type Stats {
+ _id: String
+ count: Int
+}
+
+type Query {
+ countPostsByCategory: [Stats]
+}
+----
+
+==== Optional Stages
+
+Starting from RESTHeart v7.6, field-to-aggregation mapping can include optional stages that are executed only when one or more arguments are specified. This feature enables the handling of optional GraphQL arguments.
+
+NOTE: Optional Stages are available from RESTHeart v7.6.
+
+Optional Stages in field-to-aggregation mapping are similar to Optional Stages in regular aggregations. The main difference lies in the conditional operators used. In field-to-aggregation mapping, the optional stage operator is `$ifarg`, whereas in regular aggregations, it is `$ifvar`.
+
+For a more in-depth understanding of how to use optional stages in both field-to-aggregation mapping and regular aggregations, please refer to the link:/docs/mongodb-rest/aggregations#optional-stages[Aggregation documentation].
+
+=== Mappings operators
+
+_Field to Query_ and _Field to Aggregation_ mappings provide the flexibility to employ the `$arg` and `$fk` operators:
+
+- `$arg`: This operator enables the utilization of GraphQL arguments within mappings, enhancing dynamic query or aggregation generation.
+- `$fk`: It allows the specification of the document field responsible for holding a relation. It enables traversing related documents.
+
+For instance, consider the following GraphQL schema:
+
+[source,graphql]
+----
+type User {
+ id: Int!
+ name: String
+ posts: [Post]
+}
+
+type Post {
+ id: Int!
+ text: String
+ category: String
+ author: User
+}
+
+type Query {
+ usersByName(_name: String!, _limit: Int = 0, _skip: Int = 0): [Users]
+}
+----
+
+with MongoDB data organized in the two collections `users` and `posts`:
+
+**USERS**
+[source,json]
+----
+{
+ "_id": "foo",
+ "firstName": "Foo",
+ "lastName": "Bar",
+ "contacts": { "phone": "+39113", "emails": ["foo@domain.com", "f.bar@domain.com"] },
+ "posts_ids": [ 1, 2 ]
+}
+----
+
+**POSTS**
+[source,json]
+----
+[
+ { "_id": 1,
+ "text": "Lorem ipsum dolor sit amet",
+ "category": "front-end",
+ "author_id": "foo"
+ },
+ { "_id": 2,
+ "text": "Lorem ipsum dolor sit amet",
+ "category": "back-end",
+ "author_id": "foo"
+ }
+]
+----
+
+The possible mappings are:
+
+[source,json]
+----
+{
+ "descriptor": "...",
+ "schema": "...",
+ "mappings": {
+ "User": {
+ "posts": {
+ "db": "restheart",
+ "collection": "posts",
+ "find": { "_id": { "$in": { "$fk": "posts_ids" } } }
+ }
+ },
+ "Post": {
+ "author": {
+ "db": "restheart",
+ "collection": "user",
+ "find": { "_id": { "$fk": "author_id" } }
+ }
+ },
+ "Query": {
+ "usersByName": {
+ "db": "restheart",
+ "collection": "users",
+ "find": { "name": { "$arg": "_name" } },
+ "limit": { "$arg": "_limit" },
+ "skip": { "$arg": "_skip" },
+ "sort": { "name": -1 }
+ }
+ }
+ }
+}
+----
+
+As a result of using these mapping operators:
+
+- When given a `User`, their posts are represented by the MongoDB documents within the `posts` collection. These documents have an `_id` field value that matches any of the `_id` values within the `posts_ids` array in the `User`'s document.
+
+- When given a `Post`, its author is identified by the MongoDB document within the `users` collection. This document has an `_id` field value that matches the `author_id` within the `Post`'s document.
+
+- For the `userByName` GraphQL field, the MongoDB documents being queried are those within the `users` collection with a `name` field equal to the value specified in the `_name` GraphQL argument. Furthermore, you can specify that you want to return a maximum of `_limit` documents, skip the first `_skip` documents, and have them sorted by name in reverse order.
+
+NOTE: the `$fk` and `$arg` operators allow the usage of dot notation to traverse document fields.
+
+NOTE: the `$arg` operator allows dot notation from RESTHeart v7.6 onwards.
+
+=== Dot Notation support for `$arg` and `$fk`
+
+The `$fk` and `$arg` operator can utilize dot notation to access nested properties.
+
+NOTE: Dot Notation support for `$arg` is available from RESTHeart v7.6
+
+The Dot Notation support for `$arg` feature enables the handling of `InputTypes`. The following example will clarify:
+
+[source,graphql]
+----
+input Filters {
+ type: String
+ author: String
+}
+
+type Query {
+ getPosts(filters: Filters!): [Post]
+}
+----
+
+The Query mapping can use the dot notation as follows to cope the `Filters InputType`:
+
+[source,json]
+{ "mappings": {
+ "Query": {
+ "getPosts": {
+ "db": "restheart",
+ "collection": "the-posts",
+ "find": { "author": { "$arg": "filters.author" }, "type": { "$arg": "filters.type" } }
+ }
+ }
+}
+
+=== Arguments with Default Values
+
+The `$arg` operator can specify a default value. This default value is utilized when an optional argument is not provided in the GraphQL Query.
+
+NOTE: Arguments with Default Values are available from RESTHeart v7.6.
+
+Arguments with Default Values in GraphQL mappings are similar to those in regular aggregations. The primary distinction lies in the operators used. In GraphQL mappings, the operator is `$arg`, whereas in regular aggregations, it is `$var`.
+
+For example, the following code specifies the default value `Andrea` for the argument `name`: `{"$arg": [ "name", "Andrea"]}`.
+
+For a more comprehensive understanding of how to use arguments with default values, please refer to the link:/docs/mongodb-rest/aggregations#variables-with-default-values[Aggregation documentation].
+
+=== The `rootDoc` argument
+
+NOTE: `rootDoc` is available from RESTHeart v7.6
+
+TIP: more details about this feature are available on github link:https://github.com/SoftInstigate/restheart/issues/469[issue 469]
+
+The `{"$arg": "rootDoc"}` argument is a versatile tool that can be employed in both _Field to Query_ and _Field to Aggregation_ mappings.
+
+It enables the utilization of properties from the root document when crafting queries and aggregations.
+
+The root document, in this context, is the first document retrieved from the source.
+
+To provide a clear example, let's consider a document from the collection `authors-and-posts`:
+
+The example is implemented in test link:https://github.com/SoftInstigate/restheart/blob/master/core/src/test/java/karate/graphql/rootDoc/rootDoc.feature[rootDoc.feature]
+
+[source,json]
+----
+ {
+ "_id": "bar",
+ "sub": {
+ "posts": [
+ { "content": "ping", "visible": true },
+ { "content": "pong", "visible": true },
+ { "content": "invisible", "visible": false }
+ ]
+ }
+}
+----
+
+And the following GraphQL schema. Note that the field `post` has the argument `visible`.
+
+[source,graphql]
+----
+type User {
+ _id: String
+ posts(visible: Boolean): [Post]
+}
+type Post {
+ content: String
+}
+type Query {
+ users: [User]
+}
+----
+
+In order to filter the nested posts objects according to the argument `visible` we can make use of field to aggregation mapping:
+
+[source,json]
+----
+{
+ "User": {
+ "posts": {
+ "db": "restheart",
+ "collection": "authors-and-posts",
+ "stages": [
+ { "$match": { "_id": { "$arg": "rootDoc._id" } } },
+ { "$unwind" : "$sub.posts" },
+ { "$replaceRoot": {"newRoot": "$sub.posts"} },
+ { "$match": { "visible": { "$arg": "visible" } } }
+ ]
+ }
+ }
+}
+----
+
+The field to aggregation mapping selects the root user using the `rootDoc` and filters the objects in the nested array `sub.posts` that match the argument `visible`.
+
+=== Enum mappings
+
+NOTE: available from v7.2
+
+Enum type mappings serve to define the correspondence between values in MongoDB and the corresponding enum values.
+
+However, it's essential to note that enum mappings are optional. When omitted, it is assumed that the value in the database is identical to the string representation of the enum value.
+
+For instance, consider the following `enum`:
+
+[source,graphql]
+----
+enum Level { ENTRY, MEDIUM, ADVANCED }
+----
+
+Can be mapped to numeric values as follows:
+
+[source,json]
+----
+"Level": {
+ "ENTRY": 0,
+ "MEDIUM": 1,
+ "ADVANCED": 2
+}
+----
+
+NOTE: An example GraphQL application that uses `enum` is link:https://github.com/SoftInstigate/restheart/blob/master/core/src/test/java/karate/graphql/enum-union-interface/enumTestApp.json[enumTestApp.json] used in the test link:https://github.com/SoftInstigate/restheart/blob/master/core/src/test/java/karate/graphql/enum-union-interface/enum.feature[enum.feature]
+
+=== Interface mappings
+
+NOTE: available from v7.2
+
+An interface in GraphQL is an abstract type that specifies a particular set of fields that any concrete type implementing the interface must include.
+
+To determine which concrete type a value belongs to when querying against the interface, a _TypeResolver_ must be defined in the interface mappings.
+
+Let's consider an example involving an interface and concrete objects:
+
+[source,graphql]
+----
+interface Course { _id: ObjectId, title: String }
+type InternalCourse implements Course { _id: ObjectId, title: String }
+type ExternalCourse implements Course { _id: ObjectId, title: String, deliveredBy: String }
+type Query { AllCourses: [Course] }
+----
+
+The following mappings defines the _TypeResolver_ using the `$typeResolver` keyword.
+
+[source,json]
+----
+"Course": {
+ "$typeResolver": {
+ "InternalCourse": "not field-exists(deliveredBy)",
+ "ExternalCourse": "field-exists(deliveredBy)"
+ }
+}
+----
+
+The `$typeResolver` serves as an object that establishes a mapping between the names of concrete types (such as `InternalCourse` and `ExternalCourse`) and corresponding predicates. These predicates are evaluated against a document, and if a predicate returns `true`, the GraphQL type associated with that predicate is used to represent the document.
+
+This mechanism allows for dynamic determination of the GraphQL type for a document based on the conditions defined in the predicates. It's a powerful way to handle polymorphism and resolve the actual type of objects when querying against an interface.
+
+`$typeResolver` can use the following predicates:
+
+[cols="1,3"]
+|===
+|*predicate*|*description*
+|`and` | boolean `and` operator
+|`or` | boolean `or` operator
+|`not` | boolean `not` operator
+|`field-exists` | checks if the type document contains the specified keys. Dot notation and multiple keys are permitted as in `field-exists(foo.bar, bar.foo)`
+|`field-eq` | checks if the specified type key is equal to a value. The key can use the dot notation and the value can be any JSON as in `field-eq(field=foo.bar, value='{ "n": 1 }')`.
+|`value-eq` | checks if the type value is equal to the given argument. The argument can be any JSON as in `value-eq('{ "n": 1 }')`.
+|===
+
+
+WARNING: the value of the `field-eq` predicate must be valid JSON. In particular pay attention to string values that require two quotes as in `field-eq(field=foo, value='"bar"')`.
+
+==== Examples of `field-eq` predicates
+
+[cols="1,1"]
+|===
+|*predicate*|*condition*
+|`field-eq(field=n, value=100)`|field `n` equals number `100`
+|`field-eq(field=n, value='"100"')`|field `n` equals string `"100"`
+|`field-eq(field=b, value=true)`|field `b` equals boolean value `true`
+|`field-eq(field=o, value='{ "bar": 1 }')`|field `o` equals JSON Object `{ "bar": 1 }`
+|`field-eq(field=s, value='"foo"')`|field `s` equals string `"foo"`
+|===
+
+NOTE: An example GraphQL application that uses `interface` is link:https://github.com/SoftInstigate/restheart/blob/master/core/src/test/java/karate/graphql/enum-union-interface/interfaceTestApp.json[interfaceTestApp.json] used in the test link:https://github.com/SoftInstigate/restheart/blob/master/core/src/test/java/karate/graphql/enum-union-interface/interface.feature[interface.feature]
+
+=== Union mappings
+
+NOTE: available from v7.2
+
+Union types in GraphQL are similar to interfaces in that they represent a way to include multiple types in a single field. However, unlike interfaces, union types do not specify any fields that the types within the union must have in common.
+
+With union types, you can specify that a field can return values of different types, and you can use this construct when you want to retrieve data that doesn't share a common set of fields but still needs to be represented as a single field in your schema. This is particularly useful for scenarios where you have different types of data that can be queried together under one field, even if they have different structures.
+
+[source,graphql]
+----
+union Course = InternalCourse | ExternalCourse
+type InternalCourse { _id: ObjectId, title: String }
+type ExternalCourse { _id: ObjectId, title: String, deliveredBy: String }
+----
+
+As for interfaces, a _TypeResolver_ must be defined in the union mappings to decide which type a concrete value belongs to.
+
+The format for union's `$typeResolver` is identical to interface's.
+
+NOTE: An example GraphQL application that uses `union` is link:https://github.com/SoftInstigate/restheart/blob/master/core/src/test/java/karate/graphql/enum-union-interface/unionTestApp.json[unionTestApp.json] used in the test link:https://github.com/SoftInstigate/restheart/blob/master/core/src/test/java/karate/graphql/enum-union-interface/union.feature[union.feature]
+
+== Bson types
+
+All primitive GraphQL types have been mapped to corresponding BSON types plus a set of custom GraphQL scalars types have been added:
+
+[cols="1,1,3"]
+|===
+|*GraphQL type*|*Bson Type*|*Example*
+|`Boolean` |`BsonBoolean` |`true`
+|`String` |`BsonString` |`"foo"`
+|`Int` |`BsonInt32` |`1`
+|`Long` |`BsonInt64` |`{ "$numberLong": "10000000000000000000" }`
+|`Float` |`BsonDouble` |`{ "$numberDouble": "1.0" }`
+|`Decimal128` |`BsonDecimal128` |`{ "$numberDecimal": "123.456" }`
+|`ObjectId` |`BsonObjectId` |`{ "$oid": "618d18d6d058286395bb5567" }`
+|`Timestamp` |`BsonTimestamp` |`{ "$timestamp": {"t": 1, "i": 1} }`
+|`DateTime` |`BsonDate` |`{ "$date": 1639666957000 }`
+|`Regex` |`BsonRegex` |`{ "$regex": "", "$options": "" }`
+|`BsonDocument` |`BsonDocument` |`{ "any": 1, "possible": 1, "document": 1 }`|
+|===
+
+=== Example
+
+The following GraphQL type `User` defines the property `_id` to be of type `ObjectId`
+
+[source,graphql]
+----
+type User {
+ _id: ObjectId
+ name: String
+ surname: String
+ email: String
+ posts: [Post]
+}
+----
+
+== Queries
+
+In order to make a query you can use HTTP request with POST method and both content-type `application/json` and `application/graphql`. For instance:
+
+=== `application/json`
+
+[source,http]
+----
+POST /graphql/ HTTP/1.1
+Host:
+Content-Type: application/json
+----
+
+[.text-muted]
+*Request body*
+[source,json]
+----
+{
+ "query": "query test_operation($name: String){ userByName(_name: $name){name posts{text}} }",
+ "variables": { "name": "..." },
+ "operationName": "..."
+}
+----
+
+=== `application/graphql`
+
+
+[source,http]
+----
+POST /graphql/ HTTP/1.1
+Host:
+Content-Type: application/graphql
+----
+
+[.text-muted]
+*Request body*
+[source,grahpql]
+----
+{
+ userByName(_name: "...") {
+ name
+ posts {
+ text
+ }
+ }
+}
+----
+
+## Limitations
+
+The GraphQL service has the following limitations:
+
+- **Read-only API**: mutations are not supported; the GraphQL API is only intended for simplifying data fetching. To write data, the REST API must be used.
+
+## Response
+
+Starting from RESTHeart v7.6, the GraphQL API always responds with the content type `application/graphql-response+json`, following the link:https://github.com/graphql/graphql-over-http/blob/main/spec/GraphQLOverHTTP.md[GraphQL Over HTTP specs].
+
+**Possible Response Codes:**
+
+[cols="1,4", options="header"]
+|===
+| *HTTP Status Code* | *Description*
+
+| 200
+| A valid GraphQL response has been generated, even if it contains errors (partial data).
+
+| 400
+| The request is invalid (e.g., incorrect JSON, malformed GraphQL query, non-existent fields in selection, etc.) or when the response only contains errors (i.e., `data: null`).
+
+| 404
+| The GraphQL app does not exist.
+
+| 405
+| Incorrect method used (not POST or OPTIONS).
+
+| 408
+| Request timed out due to the `query-time-limit` option.
+
+| 500
+| Connection error with MongoDB.
+
+|===
diff --git a/docs/v7/mongodb-graphql/index.adoc b/docs/v7/mongodb-graphql/index.adoc
new file mode 100644
index 00000000..70c3b7c8
--- /dev/null
+++ b/docs/v7/mongodb-graphql/index.adoc
@@ -0,0 +1,28 @@
+---
+title: GraphQL API Overview
+layout: docs-adoc
+menu: mongodb
+---
+
+The `restheart-graphql` plugin provides a read-only GraphQL API for MongoDB, complementing the REST API for modern applications.
+
+Queries are made through HTTP POST requests with `application/json` or `application/graphql` content types, and responses are in `application/graphql-response+json` format.
+
+Key Points:
+
+- *Supports all GraphQL types*: `type`, `query`, `enum`, `interface`, `union`, and `input`.
+- GraphQL applications require a JSON document, the *GraphQL app definition*, stored in the `/graphql` collection.
+- App definition includes *Descriptor* (app name, description, enabled status, URI), *Schema* (GraphQL SDL), and *Mappings* (connecting types to MongoDB data).
+- Mappings include *Field-to-Field* (mapping GraphQL to MongoDB fields), *Field-to-Query* (connecting GraphQL Object field to MongoDB query), and *Field-to-Aggregation* (linking GraphQL Object field to MongoDB aggregation stages).
+- Mappings leverage `$arg` and `$fk` *operators* for flexibility in handling GraphQL arguments and traversing related documents.
+- Support for features like *Optional Stages*, *Arguments with Default Values*, and `*rootDoc` Argument* for crafting queries and aggregations.
+- Extends GraphQL typing system for *MongoDB data types* (e.g., `BsonObjectId`, `BsonDocument`).
+- Provide automatically schema fetching for *query autocompletion and syntax checking* in popular clients like Postman and Insomnia.
+- Provide an *optimization feature* that mitigates the N+1 requests problem.
+
+[.mt-4]
+.Try It Yourself!
+****
+[.text-center]
+Why not put your knowledge into practice? link:/docs/mongodb-graphql/tutorial[Follow the GraphQL RESTHeart Tutorial]!
+****
diff --git a/docs/v7/mongodb-graphql/optimization.adoc b/docs/v7/mongodb-graphql/optimization.adoc
new file mode 100644
index 00000000..611ae9ca
--- /dev/null
+++ b/docs/v7/mongodb-graphql/optimization.adoc
@@ -0,0 +1,172 @@
+---
+title: GraphQL API
+layout: docs-adoc
+menu: mongodb
+---
+
+## The N+1 problem
+
+It's well known that every GraphQL service suffers of *N+1 requests problem*.
+
+In our case this problem arises every time that a relation is mapped through the `$fk` operator with a MongoDB query.
+
+For example, given the following GraphQL schema:
+
+[source,graphql]
+----
+type User {
+ id: Int!
+ name: String
+ posts: [Post]
+}
+
+type Post {
+ id: Int!
+ text: String
+ author: User
+}
+
+type Query {
+ posts(_limit: Int = 0, _skip: Int = 0): [Post]
+}
+----
+
+mapped with:
+
+[source,json]
+----
+{
+ "descriptor": "...",
+ "schema": "...",
+ "mappings": {
+ "User": {
+ "posts": {
+ "db": "restheart",
+ "collection": "posts",
+ "find": {
+ "_id": {
+ "$in": {
+ "$fk": "posts_ids"
+ }
+ }
+ }
+ }
+ },
+ "Post": {
+ "author": {
+ "db": "restheart",
+ "collection": "user",
+ "find": {
+ "_id": {
+ "$fk": "author_id"
+ }
+ }
+ }
+ },
+ "Query": {
+ "posts": {
+ "db": "restheart",
+ "collection": "posts",
+ "limit": {
+ "$arg": "_limit"
+ },
+ "skip": {
+ "$arg": "_skip"
+ }
+ }
+ }
+ }
+}
+----
+
+then, executing the GraphQL query:
+
+[source,graphql]
+----
+{ posts(_limit: 10) {
+ text
+ author {
+ name
+ }
+ }
+}
+----
+
+RESTHeart will execute:
+
+- a MongoDB query to fetch the first 10 documents of `posts` collection;
+- a MongoDB query for each one of the 10 posts returned by the first one.
+
+Precisely, N+1 requests.
+
+== Batching and Caching
+
+In order to mitigate the N+1 problem and optimize performances of yours GraphQL API, RESTHeart allows you to use **per-request DataLoaders** to batch and cache MongoDB queries. This can be done specifying `dataLoader` object within the _Field to Query mapping_. For instance, the author mapping seen above becomes:
+
+[source,json]
+----
+{
+ "descriptor": "...",
+ "schema": "...",
+ "mappings": {
+ "User": "...",
+ "Post": {
+ "author": {
+ "db": "restheart",
+ "collection": "user",
+ "find": {
+ "_id": {
+ "$fk": "author_id"
+ }
+ },
+ "dataLoader": {
+ "batching": true,
+ "caching": true,
+ "maxBatchSize": 20
+ }
+ }
+ },
+ "Query": "..."
+ }
+}
+----
+
+where:
+
+- `batching` (boolean): allows you to specify if queries batching is enabled. By default it's `false`;
+- `caching` (boolean): allows you to specify if queries caching is enabled. By default it's `false`;
+- `maxBatchSize` (int): allows you to specify how many queries batch together at most.
+
+== Tuning
+
+There's no magic number for `maxBatchSize`, so you have to tune it.
+
+For this purpose you can set `verbose: true` under the GraphQL plugin configuration within `restheart.yml`. In this way, RESTHeart will insert DataLoader statistics inside GraphQL queries answers.
+
+[source,json]
+----
+{
+"data": {"..."},
+ "extensions": {
+ "dataloader": {
+ "overall-statistics": {
+ "loadCount": 0,
+ "loadErrorCount": 0,
+ "loadErrorRatio": 0.0,
+ "batchInvokeCount": 0,
+ "batchLoadCount": 0,
+ "batchLoadRatio": 0.0,
+ "batchLoadExceptionCount": 0,
+ "batchLoadExceptionRatio": 0.0,
+ "cacheHitCount": 0,
+ "cacheHitRatio": 0.0
+ },
+ "individual-statistics": {
+ "dataLoader1":"...",
+ "dataLoader2":"...",
+ "dataLoader3":"..."
+ }
+ }
+ }
+}
+----
\ No newline at end of file
diff --git a/docs/v7/mongodb-graphql/tutorial.adoc b/docs/v7/mongodb-graphql/tutorial.adoc
new file mode 100644
index 00000000..3e892fea
--- /dev/null
+++ b/docs/v7/mongodb-graphql/tutorial.adoc
@@ -0,0 +1,537 @@
+---
+title: GraphQL API Tutorial with RESTHeart
+layout: docs-adoc
+menu: mongodb
+---
+
+:page-liquid:
+
+This tutorial guides you through the process of implementing a GraphQL API using RESTHeart, following the structure and concepts presented in the link:https://graphql.org/learn/schema/#type-system[GraphQL.org tutorial] on Star Wars characters and episodes, demonstrating the implementation using RESTHeart.
+
+Dive into the world of GraphQL and RESTHeart, and may the force be with your data!
+
+NOTE: While this tutorial provides buttons for executing requests using "Rest Ninja," please be aware that it may not seamlessly function with Safari due to HTTPS requirements. For a smoother experience, we recommend using Chrome or Firefox browsers (refer to link:/docs/security/tls[Configure TLS]).
+
+== Create the Star Wars GraphQL API
+
+IMPORTANT: This tutorial requires RESTHeart v7.6.4+
+
+NOTE: You won't write a single line of code! The GraphQL API just requires to define a json configuration, known as GraphQL App Definition and store it in the special collection `/gql-apps`.
+
+**1 Start RESTHeart and MongoDB**
+
+The following one-liner uses docker compose to start both RESTHeart and MongoDb. If you prefer not using docker, please refer to link:/docs/setup[setup] section to install RESTHeart and MongoDB.
+
+[source,bash]
+----
+$ curl https://raw.githubusercontent.com/SoftInstigate/restheart/master/docker-compose.yml --output docker-compose.yml && docker compose up
+----
+
+**2 Create collections**
+
+Create the *star-wars-characters* collection. This is where the data will be inserted.
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/36f1499c310f74ec7092e47e488666c69abf45f5/0"
+%}
+++++
+
+[source,http]
+PUT /star-wars-characters HTTP/1.1
+
+Create the *gql-apps* collection. This is where the GraphQL App definition will be inserted.
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/cf0d3d9a0f811cf5d6921ad66fcf49cbad852a5a/0"
+%}
+++++
+
+[source, http]
+PUT /gql-apps HTTP/1.1
+
+**3 Insert data**
+
+Create documents in the *star-wars-characters* collection:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/1dd617582b894304fe3968dc2c97feff08c0adcb/1"
+%}
+++++
+
+[source,http]
+----
+POST /star-wars-characters?wm=upsert HTTP/1.1
+----
+
+[.text-muted]
+*Request body*
+[source,json]
+----
+[
+ {"_id":1000,"name":"Luke Skywalker","friends":[1002,1003,2000,2001],"appearsIn":[4,5,6],"homePlanet":"Tatooine","heroOf":4},
+ {"_id":1001,"name":"Darth Vader","friends":[1004],"appearsIn":[4,5,6],"homePlanet":"Tatooine","heroOf":5},
+ {"_id":1002,"name":"Han Solo","friends":[1000,1003,2001],"appearsIn":[4,5,6],"homePlanet":"Corellia"},
+ {"_id":1003,"name":"Leia Organa","friends":[1000,1002,2000,2001],"appearsIn":[4,5,6],"homePlanet":"Alderaan"},
+ {"_id":1004,"name":"Wilhuff Tarkin","friends":[1001],"appearsIn":[4],"homePlanet":"Eriadu"},{"_id":2000,"name":"C-3PO","friends":[1000,1002,1003,2001],"appearsIn":[4,5,6],"primaryFunction":"Protocol"},
+ {"_id":2001,"name":"R2-D2","friends":[1000,1002,1003],"appearsIn":[4,5,6],"primaryFunction":"Astromech","heroOf":6},
+ {"_id":3000,"name":"TIE Advanced x1","length":9.2}
+]
+----
+
+**4 Insert the GraphQL App Definition**
+
+To insert the GraphQL app definition, run the following:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/8d48b4efb6c042ea3ae6fff72823d42356494514/0"
+%}
+++++
+
+[source,http]
+----
+POST /gql-apps?wm=upsert HTTP/1.1
+----
+
+NOTE: Request body omitted because is quite long. Find it in the link:#the-full-graphql-app-definition[The full GraphQL APP definition] section.
+
+[.mt-4]
+.That's it
+****
+[.text-center]
+The GraphQL API is ready to use!
+****
+
+== Execute queries
+
+=== hero
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/705cbffaa3daca184dde2958b15ffd5563faab46/0"
+%}
+++++
+
+[source,http]
+POST /graphql/star-wars HTTP/1.1
+
+[.text-muted]
+*Request body*
+[source,graphql]
+----
+{
+ hero(episode: JEDI) {
+ name
+ friends {
+ name
+ }
+ ... on Droid {
+ primaryFunction
+ }
+ ... on Human {
+ homePlanet
+ }
+ }
+}
+----
+
+++++
+{% include code-header.html
+ type="Response"
+%}
+++++
+
+[source,json]
+----
+{
+ "data": {
+ "hero": {
+ "name": "R2-D2",
+ "friends": [
+ {
+ "name": "Luke Skywalker"
+ },
+ {
+ "name": "Han Solo"
+ },
+ {
+ "name": "Leia Organa"
+ }
+ ],
+ "primaryFunction": "Astromech"
+ }
+ }
+}
+----
+
+NOTE: Please note that the response content-type is `application/graphql-response+json`. It is treated as a binary format by RestNinja, which results in a less user-friendly display. To circumvent this issue and view the response more effectively, you can opt to use HTTPie, a command-line HTTP client:
+
+[source,bash]
+$ echo '{ hero(episode: JEDI) { name friends { name } ... on Droid { primaryFunction } ... on Human { homePlanet } } }' | http -a admin:secret :8080/graphql/star-wars Content-Type:application/graphql
+
+=== search
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/985a919c91ef4b62f895a9c7996bef40e04a85dc/0"
+%}
+++++
+
+[source,http]
+POST /graphql/star-wars HTTP/1.1
+
+[.text-muted]
+*Request body*
+[source,graphql]
+----
+{
+ search(text: "an") {
+ ... on Character {
+ name
+ }
+ ... on Starship {
+ name
+ length
+ }
+ }
+}
+----
+
+++++
+{% include code-header.html
+ type="Response"
+%}
+++++
+
+[source,json]
+----
+{
+ "data": {
+ "search": [
+ {
+ "name": "Han Solo"
+ },
+ {
+ "name": "Leia Organa"
+ },
+ {
+ "name": "TIE Advanced x1",
+ "length": 9.2
+ }
+ ]
+ }
+}
+----
+
+NOTE: Please note that the response content-type is `application/graphql-response+json`. It is treated as a binary format by RestNinja, which results in a less user-friendly display. To circumvent this issue and view the response more effectively, you can opt to use HTTPie, a command-line HTTP client:
+
+[source,bash]
+$ echo '{ search(text: "an") { ... on Character { name } ... on Starship { name length } } }' | http -a admin:secret :8080/graphql/star-wars Content-Type:application/graphql
+
+== Understanding the GraphQL App Definition
+
+GraphQL types are connected to MongoDB data through mappings.
+
+NOTE: If you don’t explicitly define a mapping for a field, RESTHeart will automatically map it to the MongoDB document field with the same name.
+
+=== enum Episode
+
+The GraphQL schema defines the enum `Episode`:
+
+[source,graphql]
+----
+enum Episode { NEWHOPE EMPIRE JEDI }
+----
+
+The enum type requires a mapping unless the value in the database is identical to the string representation of the enum value. If you look at the data, the episode are stored with Int codes. Thus we need a mapping to link the Int codes to the enum values.
+
+TIP: for more information on enum mappings see link:/docs/mongodb-graphql/graphql-apps#enum-mappings[Enum mappings]
+
+[source,json]
+----
+{
+ "mappings": {
+ "Episode": { "NEWHOPE": 4, "EMPIRE": 5, "JEDI": 6 }
+ }
+}
+----
+
+=== union SearchResult
+
+The GraphQL schema defines the union `SearchResult`:
+
+[source,graphql]
+----
+union SearchResult = Human | Droid | Starship
+----
+
+The union requires a `$typeResolver`
+
+TIP: for more information on union mappings see link:/docs/mongodb-graphql/graphql-apps#union-mappings[Union Mappings]
+
+[source,json]
+----
+{
+ "mappings": {
+ "SearchResult": {
+ "$typeResolver": {
+ "Human": "field-exists(homePlanet)",
+ "Droid": "field-exists(primaryFunction)",
+ "Starship": "field-exists(length)"
+ }
+ }
+ }
+}
+----
+
+=== interface Character
+
+The GraphQL schema defines the interface `Character`:
+
+[source,graphql]
+----
+interface Character {
+ _id: Int!
+ name: String!
+ friends: [Character]!
+ appearsIn: [Episode]!
+}
+----
+
+The interface requires a `$typeResolver`
+
+TIP: for more information on interface mappings see link:/docs/mongodb-graphql/graphql-apps#interface-mappings[Interface Mappings]
+
+[source,json]
+----
+{
+ "mappings": {
+ "Character": {
+ "$typeResolver": {
+ "Human": "field-exists(homePlanet)",
+ "Droid": "field-exists(primaryFunction)"
+ }
+ }
+ }
+}
+----
+
+=== object Starship
+
+The GraphQL schema defines the object type `Starship`:
+
+[source,graphql]
+----
+type Starship {
+ _id: Int!
+ name: String!
+ length(unit: LengthUnit = METER): Float
+}
+----
+
+No mapping is required since default field-to-field mappings are fine
+
+TIP: for more information on field-to-field mappings see link:/docs/mongodb-graphql/graphql-apps#field-to-field-mapping[Field-to-field mapping]
+
+=== objects Human and Droid
+
+The GraphQL schema defines the object types `Human` and `Droids`:
+
+[source,graphql]
+----
+type Human implements Character {
+ _id: Int!
+ name: String!
+ friends: [Character]!
+ appearsIn: [Episode]!
+ homePlanet: String!
+}
+
+type Droid implements Character {
+ _id: Int!
+ name: String!
+ friends: [Character]!
+ appearsIn: [Episode]!
+ primaryFunction: String!
+}
+----
+
+Those object types have the field `friends` in common, actually derived by the fact that they both implement the interface `Character`. This field requires a field-to-query mapping.
+
+TIP: for more information on field-to-query mappings see link:/docs/mongodb-graphql/graphql-apps#field-to-query-mapping[Field-to-query Mapping]
+
+TIP: for more information on the `$fk` operator see link:/docs/mongodb-graphql/graphql-apps#mappings-operators[Mapping Operators]
+
+[source,json]
+----
+{
+ "mappings": {
+ "Human": {
+ "friends": {
+ "db": "restheart",
+ "collection": "star-wars-characters",
+ "find": { "_id": { "$in": { "$fk": "friends" } } }
+ }
+ },
+ "Droid": {
+ "friends": {
+ "db": "restheart",
+ "collection": "star-wars-characters",
+ "find": { "_id": { "$in": { "$fk": "friends" } } }
+ }
+ }
+ }
+}
+----
+
+=== Query
+
+The GraphQL schema defines the queries `hero` and `search`
+
+[source,graphql]
+----
+type Query {
+ hero(episode: Episode!): Character
+ search(text: String!): [SearchResult]
+}
+----
+
+Queries always require mappings.
+
+TIP: for more information on query mappings see link:/docs/mongodb-graphql/graphql-apps#field-to-query-mapping[Field-to-query Mapping]
+
+[source,json]
+----
+{
+ "mappings": {
+ "Query": {
+ "hero": {
+ "db": "restheart",
+ "collection": "star-wars-characters",
+ "find": { "heroOf": { "$arg": "episode" } }
+ },
+ "search": {
+ "db": "restheart",
+ "collection": "star-wars-characters",
+ "find": { "name": { "$regex": { "$arg": "text" } , "$options": "i" } } }
+ }
+ }
+}
+----
+
+== The full GraphQL Schema
+
+[source,graphql]
+----
+union SearchResult = Human | Droid | Starship
+
+enum LengthUnit {
+ METER
+}
+
+enum Episode {
+ NEWHOPE
+ EMPIRE
+ JEDI
+}
+
+type Starship {
+ _id: Int!
+ name: String!
+ length(unit: LengthUnit = METER): Float
+}
+
+interface Character {
+ _id: Int!
+ name: String!
+ friends: [Character]!
+ appearsIn: [Episode]!
+}
+
+type Human implements Character {
+ _id: Int!
+ name: String!
+ friends: [Character]!
+ appearsIn: [Episode]!
+ homePlanet: String!
+}
+
+type Droid implements Character {
+ _id: Int!
+ name: String!
+ friends: [Character]!
+ appearsIn: [Episode]!
+ primaryFunction: String!
+}
+
+type Query {
+ hero(episode: Episode!): Character
+ search(text: String!): [SearchResult]
+}
+----
+
+== The full GraphQL APP definition
+
+[source,json]
+----
+{
+ "_id": "star-wars",
+ "descriptor": {
+ "name": "star-wars",
+ "description": "GraphQL application used in the Star Wars Tutorial",
+ "enabled": true,
+ "uri": "star-wars"
+ },
+ "schema": "union SearchResult = Human | Droid | Starship enum LengthUnit { METER } enum Episode { NEWHOPE EMPIRE JEDI } type Starship { _id: Int! name: String! length(unit: LengthUnit = METER): Float } interface Character { _id: Int! name: String! friends: [Character]! appearsIn: [Episode]! } type Human implements Character { _id: Int! name: String! friends: [Character]! appearsIn: [Episode]! homePlanet: String! } type Droid implements Character { _id: Int! name: String! friends: [Character]! appearsIn: [Episode]! primaryFunction: String! } type Query { hero(episode: Episode!): Character search(text: String!): [SearchResult] }",
+ "mappings": {
+ "Episode": { "NEWHOPE": 4, "EMPIRE": 5, "JEDI": 6 },
+ "SearchResult": {
+ "$typeResolver": {
+ "Human": "field-exists(homePlanet)",
+ "Droid": "field-exists(primaryFunction)",
+ "Starship": "field-exists(length)"
+ }
+ },
+ "Character": {
+ "$typeResolver": {
+ "Human": "field-exists(homePlanet)",
+ "Droid": "field-exists(primaryFunction)"
+ }
+ },
+ "Human": {
+ "friends": {
+ "db": "restheart",
+ "collection": "star-wars-characters",
+ "find": { "_id": { "$in": { "$fk": "friends"} } }
+ }
+ },
+ "Droid": {
+ "friends": {
+ "db": "restheart",
+ "collection": "star-wars-characters",
+ "find": { "_id": { "$in": { "$fk": "friends"} } }
+ }
+ },
+ "Query": {
+ "hero": {
+ "db": "restheart",
+ "collection": "star-wars-characters",
+ "find": { "heroOf": { "$arg": "episode" } }
+ },
+ "search": {
+ "db": "restheart",
+ "collection": "star-wars-characters",
+ "find": { "name": { "$regex": { "$arg": "text" } , "$options": "i" } } }
+ }
+ }
+}
+----
diff --git a/docs/v7/mongodb-rest/aggregations.adoc b/docs/v7/mongodb-rest/aggregations.adoc
new file mode 100644
index 00000000..bab152c0
--- /dev/null
+++ b/docs/v7/mongodb-rest/aggregations.adoc
@@ -0,0 +1,471 @@
+---
+title: Aggregations
+layout: docs-adoc
+menu: mongodb
+---
+
+> Aggregations operations process data records and return computed results. Aggregation operations group values from multiple documents together, and can perform a variety of operations on the grouped data to return a single result.
+
+The RESTHeart API provides powerful aggregation capabilities to developers, including the ability to run both aggregation pipelines and map reduce functions using just a GET request.
+
+To execute an aggregation query, simply send a GET request to `/coll/_aggrs/` with the appropriate parameters!
+
+NOTE: Only inline output type is supported - meaning that no results are written directly to the database. However, if you wish to have results written to the database, then link:#materialized-views[Materialized Views] is the solution for you.
+
+== Aggregation definition
+
+NOTE: In RESTHeart, not only documents but also dbs and collections have
+properties. Some properties are metadata, i.e. they have a special
+meaning for RESTheart that influences its behavior.
+
+You can define aggregation by setting the aggrs collection metadata property via a `PATCH /coll` request. Here is an example of how to structure the request body:
+
+[source,http]
+----
+PATCH /coll HTTP/1.1
+
+{
+ "aggrs": [
+ { },
+ { },
+ ...,
+ { }
+ ]
+}
+----
+
+The _aggregation definition objects_ have the following format:
+
+[source,json]
+----
+{
+ "uri": "",
+ "stages": [
+ "",
+ "",
+ "..."
+ ],
+ "allowDiskUse": true
+}
+----
+
+WARNING: For RESTHeart versions < 7.3, you also need to specify `"type": "pipeline"`
+
+[options="header"]
+[cols="1,5,1"]
+|===
+|Property |Description |Mandatory
+|type
+|for aggregation pipeline operations is `pipeline`
+|No, default is `pipeline` (prior to v7.3, `type` was required)
+|uri
+|specifies the URI when the operation is bound under the path `//_aggrs`
+|Yes
+|stages
+|the MongoDB aggregation pipeline stages. For more information refer to link:https://docs.mongodb.org/manual/core/aggregation-pipeline[Aggregation Pipeline] on MongoDb documentation.
+|Yes
+|allowDiskUse
+|Allow pipeline stages that require more than 100 megabytes of memory to write temporary files to disk
+|No, default is `false`
+|===
+
+== Example
+
+The following request sets an aggregation pipeline bound at `/coll/_aggrs/example-pipeline`
+
+[source,http]
+----
+PATCH /coll HTTP/1.1
+
+{
+ "aggrs": [
+ {
+ "stages": [
+ { "$match": { "name": { "$var": "name" } } },
+ { "$group": { "_id": "$name", "avg_age": { "$avg": "$age" } } }
+ ],
+ "uri": "example-pipeline"
+ }
+ ]
+}
+----
+
+== Variables
+
+Using variables to define parameters in an aggregation allows you to include dynamic queries and create a more customized output. This can help to make the query much more specific and efficient when retrieving data from the database.
+
+=== The `$var` Operator
+
+In aggregation definitions, you have the flexibility to create parametric aggregations using the special operator `{"$var": "name" }`. This operator enables you to dynamically customize aggregations based on variable values.
+
+=== Passing Variables to Aggregations
+
+To leverage this feature, you can utilize the `?avars` query parameter when making requests. By including `?avars={"name":"Bob"}`, you can pass variables to aggregations. This allows you to adapt the aggregation behavior on the fly.
+
+=== Variable Value Format
+
+It's important to note that the value of a variable can be any valid JSON. This means you can pass various data types, including strings and complex objects. For instance:
+
+[source]
+----
+?avars={ "name": "Bob", "obj": {"a": { "json": "object" }} }
+----
+
+In this example, we are passing two variables: a string (`"name"`) and an object (`"obj"`).
+
+=== Handling Missing Variables
+
+A crucial point to remember is that if an aggregation relies on a variable, such as `name`, and that variable is not passed via the `?avars` query parameter, the request will fail unless you define a variable with a default value. Therefore, ensure that all required variables are provided to avoid issues during aggregation execution.
+
+[source,http]
+----
+GET /coll/_aggrs/example-pipeline HTTP/1.1
+
+HTTP/1.1 400 Bad Request
+
+{
+ "http status code": 400,
+ "http status description": "Bad Request",
+ "message": "error executing aggreation pipeline: variable name not bound"
+}
+----
+
+=== Dot Notation Support
+
+Starting from RESTHeart version 7.6, the `$var` operator also supports dot notation. This means you can navigate through nested JSON structures within variables. For instance:
+
+[source]
+----
+?avars={ "foo": {"bar": 1 }
+----
+
+In this case, the value of `{"$var": "foo.bar" }` will be resolved as `1`. This enhances the flexibility and versatility of parametric aggregations, allowing for more complex and dynamic data processing.
+
+=== Variables with default values
+
+In RESTHeart version 7.3 and onwards, you can enhance the flexibility of your aggregation requests by specifying default values for variables. This feature ensures that your aggregations gracefully handle cases where a variable is not explicitly provided in the request using the `?avar` query parameter.
+
+==== Defining Variables with Default Values
+
+To define a variable with a default value, utilize the following syntax: `{"$var": [ "name", "default-value" ] }`. This structure allows you to set a fallback value that will be used when a specific variable is not included in the request.
+
+==== Default Values Format
+
+It's essential to note that default values can take any valid JSON format. For instance, you can set a default value like this:
+
+[source,json]
+----
+{"$var": [ "s", {"name":1} ]}
+----
+
+In this example, the default value for variable `s` is `{"name":1}`.
+
+==== Example: Using a Variable with Default Value in `$sort` Stage
+
+To illustrate this concept, consider an example aggregation that incorporates a variable `s` with a default value in the `$sort` stage:
+
+[source,json]
+----
+{
+ "aggrs": [
+ {
+ "uri": "sort-with-default-example",
+ "stages": [
+ { "$sort": { "$var": [ "s", { "name": 1 } ] } }
+ ]
+ }
+ ]
+}
+----
+
+In this aggregation, if the `s` variable is not provided in the request, it will default to `{"name": 1}`. This powerful feature simplifies aggregation requests and ensures consistent behavior even when specific variables are not explicitly set.
+
+== Predefined variables
+
+The following predefined variables can be used in the aggregation definition:
+
+[options="header"]
+[cols="1,3"]
+|===
+|variable|description
+|`@user`
+|the user object (excluding the password), e.g. `@user._id` (for users defined in MongoDB by `MongoRealmAuthenticator`) or `@user.userid` (for users defined in acl.yml by `FileRealmAuthenticator`)
+|`@mongoPermissions`
+|the `MongoPermissions` object, e.g. `@mongoPermissions.readFilter`
+|`@page`
+|the value of the `page` query parameter
+|`@pagesize`
+|the value of the `pagesize` query parameter
+|`@skip`
+|to be used in `$skip` stage, equals to `(page-1)*pagesize`
+|`@limit`
+|to be used in `$limit` stage, equals to the value of the `pagesize` query parameter
+|===
+
+== Handling paging in aggregations
+
+Paging must be handled explicitly by the aggregation-
+
+For example, the following defines the aggregation `/aggrs/paging` that uses the `@skip` and `@limit` variables. As a result, the request `GET /coll/_aggrs/paging?page=3&pagesize=25` skips 50 documents, returning the following 25 documents.
+
+[source,json]
+----
+{
+ "aggrs": [
+ {
+ "uri": "paging",
+ "stages": [
+ { "$skip": { "$var": "@skip" } },
+ { "$limit": { "$var": "@limit" } }
+ ]
+ }
+ ]
+}
+----
+
+[[optional-stages]]
+== Optional Stages
+
+NOTE: Optional stages are available from RESTHeart 7.3.
+
+A pipeline in RESTHeart can include optional stages, which are included only if certain variables are set using the `?avar` query parameter.
+
+To define an optional stage, you can use the `$ifvar` operator.
+
+=== With One Required Variable
+
+For one required variable, use the following format:
+
+[source,json]
+----
+{
+ "uri": "by-name",
+ "stages": [
+ { "$match": { "name": "foo" } },
+ { "$ifvar": [ "required-variable", ] }
+ ]
+}
+----
+
+Here's an example:
+
+[source,json]
+----
+{
+ "uri": "by-name",
+ "stages": [
+ { "$match": { "name": "foo" } },
+ { "$ifvar": [ "s", { "$sort": { "$var": "s" } } ] }
+ ]
+}
+----
+
+=== With Multiple Required Variables
+
+If you need to specify more than one required variable, you can use the following format:
+
+[source,json]
+----
+{
+ "uri": "by-name",
+ "stages": [
+ { "$match": { "name": "foo" } },
+ { "$ifvar": [ [ ], ] }
+ ]
+}
+----
+
+TIP: Starting from RESTHeart v7.6, the `$ifvar` operator supports the dot notation for specifying variables, so it is possible to define an optional stage as `{ "$ifvar": [ "a.nested.var", ] }`
+
+[source,json]
+----
+{
+ "uri": "by-name",
+ "stages": [
+ { "$match": { "name": "foo" } },
+ { "$ifvar": [ ["a", "b" ] , { "$match": { "foo": { "$var": "a" }, "bar": { "$var": "b" } } } ] }
+ ]
+}
+----
+
+=== Specifying an Else Stage
+
+It is also possible to specify an _else_ stage, i.e., an alternative stage that is included in the aggregation if the required variables are not passed via the `?avar` query parameter.
+
+To specify an _else_ stage, use the following format:
+
+[source,json]
+----
+{
+ "uri": "by-name",
+ "stages": [
+ { "$match": { "name": "foo" } },
+ { "$ifvar": [ ["a", "b" ],
+ { "$match": { "foo": { "$var": "a" }, "bar": { "$var": "b" } } },
+ { "$match": { "foo": 1, "bar": 2 } } ] }
+ ]
+}
+----
+
+== Materialized Views
+
+The `$merge` stage for the pipelines delivers the ability to create collections based on an aggregation and update those created collections efficiently, i.e. it just updates the generated results collection rather than rebuild it completely (like it would with the `$out` stage).
+
+It's as simple as adding `$merge` as the last stage of the pipeline.
+
+The following example defines the aggregation `/coll/_aggrs/age-by-gender` that computes average ages grouping data by gender. `$merge` is used as the last stage of the pipeline to write computed data to the `avgAgeByGender` collection.
+
+[source,http]
+----
+PUT /coll HTTP/1.1
+
+{ "aggrs" : [
+ { "stages" : [
+ { "$group" : { "_id" : "$gender", "avg_age" : { "$avg" : "$age" } } },
+ { "$merge": { "into": "avgAgeByGender" } }
+ ],
+ "uri" : "age-by-gender"
+ }
+ ]
+}
+----
+
+Executing the aggregation request returns no data, but thanks to the `$merge` stage, the new collection `avgAgeByGender` gets created.
+
+
+[source,http]
+----
+GET /coll/_aggrs/avg-by-city HTTP/1.1
+
+HTTP/1.1 200 OK
+[]
+----
+
+[source,http]
+----
+GET /avgAgeByGender HTTP/1.1
+
+HTTP/1.1 200 OK
+[
+ { "_id": "male", "avg_age": 34.5 }
+ { "_id": "female", "avg_age": 35.6 }
+]
+----
+
+
+== Security considerations
+
+By default RESTHeart makes sure that the aggregation variables passed as query parameters don't include MongoDB operators.
+
+This behavior is required to protect data from undesirable malicious query injection.
+
+Even though is highly discouraged, is possible to disable this check by editing the following property in the `restheart.yml` configuration file.
+
+[source,yml]
+----
+# Check if aggregation variables use operators. https://restheart.org/docs/mongodb-rest/aggregations/#security-considerations
+mongo:
+ aggregation-check-operators: true
+----
+
+== Transaction Support
+
+Aggregations are executed in the transaction scope if specified via the `sid` and `txn` query parameters.
+
+For more information on how to create a transaction scope refer to link:/docs/mongodb-rest/transactions[Transactions] doc page.
+
+== Map-Reduce
+
+WARNING: map reduce are deprecated. Use aggregation pipeline instead. See link:https://www.mongodb.com/docs/manual/core/map-reduce/[Map-Reduce] in MongoDb documentation.
+
+[source,json]
+----
+{
+ "type": "mapReduce",
+ "uri": "",
+ "map": "",
+ "reduce": "",
+ "query": ""
+}
+----
+
+[options="header"]
+[cols="1,3,1"]
+|===
+|Property |Description |Mandatory
+|type
+|for aggregation pipeline operations is "mapReduce"
+|yes
+|uri
+|specifies the map reduce URI under `///_aggrs` path.
+|yes
+|map
+|the map function
+|yes
+|reduce
+|the reduce function
+|yes
+|query
+|the query
+|yes
+|===
+
+=== Example
+
+The following request update the collection metadata defining a map reduce operation bound at `/coll/_aggrs/example-mapreduce`
+
+[source,http]
+----
+PUT /coll HTTP/1.1
+
+{
+ "aggrs": [
+ {
+ "map": "function() { emit(this.name, this.age) }",
+ "query": { "name": { "$var": "n" } },
+ "reduce": "function(key, values) { return Array.avg(values) }",
+ "type": "mapReduce",
+ "uri": "example-mapreduce"
+ }
+ ]
+}
+----
+
+=== Variables
+
+==== in query
+
+You can use the variable in queries using the `$var` operator.
+
+==== in map reduce functions
+
+Variables are passed also to *map* and *reduce* javascript functions
+where the variable `$vars` can be used. For instance:
+
+[source,http]
+----
+PATCH /coll HTTP/1.1
+
+{ "aggrs" : [
+ {
+ "map" : "function() { var minage = JSON.parse($vars).minage; if (this.age > minage ) { emit(this.name, this.age); }; }",
+ "reduce" : "function(key, values) { return Array.avg(values) } }",
+ "type" : "mapReduce",
+ "uri" : "example-mapreduce"
+ }
+ ]
+}
+
+HTTP/1.1 200 Ok
+----
+
+Note the _map_ function; `JSON.parse($vars)` allows to access the
+variables passed with the query parameter `avars`
+
+[source,js]
+----
+function() {
+ var minage = JSON.parse($vars).minage;// <-- here we get minage from avars qparam
+ if (this.age > minage ) { emit(this.name, this.age); }
+};
+----
diff --git a/docs/v7/mongodb-rest/caching.adoc b/docs/v7/mongodb-rest/caching.adoc
new file mode 100644
index 00000000..bde3314c
--- /dev/null
+++ b/docs/v7/mongodb-rest/caching.adoc
@@ -0,0 +1,155 @@
+---
+title: Caching
+layout: docs-adoc
+menu: mongodb
+---
+
+== Introduction
+
+RESTHeart speedups the execution of GET requests to collections, i.e. `GET /coll`, via caching.
+
+This applies when several documents need to be read from a
+collection and can moderate the effects of the
+MongoDB link:https://docs.mongodb.org/manual/reference/method/cursor.skip/#cursor.skip[cursor.skip()] method **that slows downs linearly**.
+
+RESTHeart allows to link:/docs/mongodb-rest/read-docs[Read Documents] via GET requests
+on collections.
+
+```
+GET /test/coll?count&page=3&pagesize=10 HTTP/1.1
+
+HTTP/1.1 200 OK
+
+[
+ { }, { }, ... { }
+]
+```
+
+Documents are returned as **paginated** result sets, i.e. each
+request returns a limited number of documents.
+
+Pagination is controlled via the following query parameters:
+
+- `page`: the range of documents to return
+- `pagesize`: the number of documents to return (default value is 100,
+ maximum is 1000).
+
+**Behind the scene, this is implemented via the MongoDB *cursor.skip()*
+method;**
+
+The issue is that MongoDB queries with a large "skip" slow down
+linearly. As the MongoDB manual says:
+
+> The `cursor.skip()` method is often expensive because it requires the server to walk from the beginning of the collection or index to get the offset or skip position before beginning to return result. As offset (e.g. pageNumber above) increases, `cursor.skip()` will become slower and more CPU intensive. With larger collections, `cursor.skip()` may become IO bound.
+
+That is why the MongoDB documentation section about
+link:https://www.mongodb.com/docs/manual/reference/method/cursor.skip/#using-range-queries[skips] suggests:
+
+> Range queries can use indexes to avoid scanning unwanted documents, typically yielding better performance as the offset grows compared to using `skip()` for pagination.
+
+## How it works
+
+If the request contains the query parameter `?cache`, than the query cursor used to retrieve the `pagesize` documents is cached. This allows to cache up to `batchSize` documents.
+
+A subsequent request, on the same collection, and with the very same `filter`, `sort`, `hint`, etc. parameters can reuse the cached cursor, avoiding the need to query MongoDB, and speeding up the request.
+
+NOTE: as with any caching system, the performance gain comes at a price. The cached documents pages can be obsolete, since cached documents could have been modified or deleted and new documents could have been created.
+
+## Configuration
+
+The following configuration applies on caching
+
+[source,yml]
+----
+mongo:
+ # get collection cache speedups GET /coll?cache requests
+ get-collection-cache-size: 100
+ get-collection-cache-ttl: 10_000 # Time To Live, default 10 seconds
+ get-collection-cache-docs: 1000 # number of documents to cache for each request
+----
+
+[options="header"]
+|===
+|parameter |description |default value
+|`get-collection-cache-size`
+|the maximum number of cached cursors
+|100
+|`get-collection-cache-ttl`
+|the time in milliseconds that an cursor is cached before it’s deleted
+|10000 (10 seconds)
+|`get-collection-cache-docs`
+|the number of documents to cache per each query (must be >= `/mongo/max-pagesize`)
+|1000
+|===
+
+## Results
+
+The issue link:https://github.com/SoftInstigate/restheart/issues/442[442] on github, has the following performance results on a collection with 6+ millions documents.
+
+Without caching (total time = ~12 seconds):
+
+[img-fluid]
+image::https://user-images.githubusercontent.com/7335252/204082210-f62b8a13-d78d-4e13-b7e5-d6456d1ca7f6.png[without caching]
+
+With caching (total time = ~2 seconds):
+
+[img-fluid]
+image::https://user-images.githubusercontent.com/7335252/205438554-fbf523ad-55b7-416a-9d81-37fe23fa5f2d.png[with caching]
+
+
+## Cache consistency with transactions
+
+To make sure that requests using caching return consistent data, link:/docs/mongodb-rest/transactions[transactions] can be used, since the *isolation* property of transactions guarantees consistency.
+
+create a session:
+
+[source,bash]
+-----
+POST /_sessions HTTP/1.1
+
+...
+Location: http://localhost:8009/_sessions/11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0
+-----
+
+start a transactions
+
+[source,bash]
+-----
+POST /_sessions/11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0/_txns HTTP/1.1
+
+HTTP/1.1 201 Created
+Location: http://localhost:8009/_sessions/11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0/_txns/1
+-----
+
+get data in the transaction with caching
+
+[source,bash]
+-----
+GET /coll?sid=11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0&txn=1&cache&page=3&pagesize=10 HTTP/1.1
+
+HTTP/1.1 200 OK
+
+[
+ { }, { }, ... { }
+]
+-----
+
+[source,bash]
+-----
+GET /coll?sid=11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0&txn=1&cache&page=4&pagesize=10 HTTP/1.1
+
+HTTP/1.1 200 OK
+
+[
+ { }, { }, ... { }
+]
+-----
+
+abort the transaction (since no data has been modified)
+
+[source,bash]
+----
+DELETE /_sessions/11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0/_txns/1 HTTP/1.1
+
+HTTP/1.1 204 No Content
+----
diff --git a/docs/v7/mongodb-rest/csv.md b/docs/v7/mongodb-rest/csv.md
new file mode 100644
index 00000000..349c594b
--- /dev/null
+++ b/docs/v7/mongodb-rest/csv.md
@@ -0,0 +1,342 @@
+---
+title: Upload CSV files
+layout: docs
+menu: mongodb
+---
+
+
+
+* [What are Clustering and Load Balancing](#what-are-clustering-and-load-balancing)
+
+* [How it works](#how-it-works)
+
+* [JWT Token Manager](#jwt-token-manager)
+
+* [References](#references)
+
+
+
+
+{% include docs-head.html %}
+
+## What are Clustering and Load Balancing
+
+**Server Clustering** is a method of turning multiple computer servers into a cluster, which is a group of servers that acts like a single system.
+
+**Load Balancing** is about the distribution of workloads across multiple computing resources, such as computers, server clusters, network links, etc. Load balancing aims to optimize resource usage, maximize throughput, minimize response time, and avoid overload of any single resource.
+
+A **MongoDB Replica Set** is a group of `mongod` processes that maintain the same data set. Replica sets provide redundancy and high availability, and are the basis for all production deployments.
+
+**High availability (HA)** is a general characteristic of a system, which aims to ensure an agreed level of operational performance, usually uptime, for a higher-than-normal period.
+
+{: width="50%" height="auto" class="mx-auto d-block img-responsive" style="padding: 20px"}
+
+RESTHeart has always been a very good fit for Microservices and other styles of distributed architecture. It has been deployed successfully with clustering technologies such as **AWS ECS** and **Fargate**, **Kubernetes** and many others.
+
+## How it works
+
+RESTHeart receives HTTP requests and routes them to the Service bound to the request paths. Creating a cluster requires an HTTP load balancer on top of the chosen clustering technology.
+
+RESTHeart is stateless for all features but for the default Token Manager used for [token authentication](https://restheart.org/docs/security/authentication#token-managers). This implementation that comes with RESTHeart holds the tokens in memory. As a result, it does not support clustering.
+
+Thus a cluster of RESTHeart nodes requires **sticky sessions** when using token authentication otherwise the RESTHeart node could receive an authentication token created by another instance, which results in an HTTP 401 "Unauthorized" error.
+
+As RESTHeart instances don't communicate directly (to avoid expensive synchronization steps), then they can't validate authentication tokens created by other instances in the same cluster. To overcome this situation, the HTTP Load Balancer must insert a sticky session token into a cookie and then handle the communication flow from clients to RESTHeart instances accordingly. Sticky sessions, from an architectural point of view, introduce a level of statefulness in the system and their expiration timeout must be carefully tuned.
+
+## JWT Token Manager
+
+The specialized `JWT Token Manager` which creates cryptographically signed tokens that can be acknowledged by any RESTHeart node in the cluster without direct communication and synchronization among them: fast, simple and safe.
+
+For more information refer to the [JWT Token Manager](https://restheart.org/docs/security/authentication#jwt-token-manager) documentation page.
+
+{: class="mx-auto d-block img-responsive"}
+
+In summary, the top-level steps for a highly available RESTHeart \+ MongoDB configuration are:
+
+1. Create a MongoDB Replica Set;
+
+2. Create a RESTHeart cluster connected to the MongoDB Replica Set;
+
+3. Put an HTTP Load Balancer on top of it.
+
+{: .bs-callout.bs-callout-info}
+If you want to know more about clustering, load balancing and high availability, please [contact us](https://restheart.com/#contact).
+
+## References
+
+To understand more in general about Load Balancing, Affinity, Persistence, and Sticky Sessions you can read this [overview](https://www.haproxy.com/fr/blog/load-balancing-affinity-persistence-sticky-sessions-what-you-need-to-know/).
+
+
diff --git a/docs/v7/configuration.adoc b/docs/v7/configuration.adoc
new file mode 100644
index 00000000..1273fdd9
--- /dev/null
+++ b/docs/v7/configuration.adoc
@@ -0,0 +1,218 @@
+---
+title: Configuration
+layout: docs-adoc
+menu: setup
+---
+
+== Update the `admin` password!
+
+At first startup, RESTHeart initializes the user `admin`, with the default password `secret`. *This user can execute any request*.
+
+WARNING: *YOU MUST UPDATE THE DEFAULT PASSWORD!* The role `admin` can execute any request as it is set as the `root` role in the `mongoAclAuthorizer` configuration.
+
+To update it, run the following command:
+
+[source,bash]
+$ curl -u admin:secret -X PATCH localhost:8080/users/admin -H "Content-Type: application/json" -d '{ "password": "my-strong-password" }'
+
+Refer to link:/docs/security/user-management/[User Management] for more information on how to create new users, roles and permissions.
+
+== Default configuration
+
+RESTHeart v7 has a link:/docs/default-configuration[default configuration] and specifying a configuration file is not required.
+
+The following command runs RESTHeart with the _default configuration_.
+
+[source,bash]
+$ java -jar restheart.jar
+
+The following command prints the default configuration to the console.
+
+[source,bash]
+$ java -jar restheart.jar -t
+
+== Configuration file
+
+RESTHeart can also use a configuration file:
+
+[source,bash]
+$ java -jar restheart.jar -t 2> restheart.yml # generate a configuration file with default values
+$ java -jar restheart.jar restheart.yml
+
+NOTE: The default configuration is fine most of the times. You just want to change few options and the suggested way is using the default configuration with the needed overrides.
+
+== Modify the configuration with the RHO env var
+
+The environment variable `RHO` allows to modify and add any configuration option.
+
+An example is:
+
+[source,bash]
+$ RHO='/mclient/connection-string->"mongodb://127.0.0.1";/mongo/mongo-mounts[1]/where->"/api"' java -jar restheart.jar
+
+or even:
+
+[source,bash]
+$ RHO='/mclient/connection-string->"mongodb://127.0.0.1";/mongo/mongo-mounts[1]->{"where: "/api", "what": "mydb"}' java -jar restheart.jar
+
+The following command with the `-c` option, prints the effective configuration, i.e. the default configuration with the `RHO` overrides applied.
+
+[source,bash]
+```
+$ RHO='/core/name->"***** test *****"' java -jar restheart.jar -c
+
+INFO o.r.configuration.Configuration - Overriding configuration parameters from RHO environment variable:
+INFO o.r.configuration.Configuration - /core/name -> ***** test *****
+
+core: {name: '***** test *****', plugins-directory: plugins, base-url: null, io-threads: 0,
+ worker-threads: -1, requests-limit: 1000, buffer-size: 16364, direct-buffers: true,
+ force-gzip-encoding: false, allow-unescaped-characters-in-url: true}
+```
+The format is:
+
+[source,bash]
+
+
+- [Requirements](#requirements)
+- [The activation process](#the-activation-process)
+- [Silent acceptance](#silent-acceptance)
+- [Specify the license key directory](#specify-the-license-key-directory)
+- [Docker](#docker)
+
+
+
+
+{% include docs-head.html %}
+
+The [Enterprise License](https://github.com/SoftInstigate/restheart/blob/master/COMM-LICENSE.txt) comes into effect by executing the License Key Activation process.
+
+{: .bs-callout .bs-callout-info }
+For more information about the Enterprise License and Support please refer to [restheart.com](/https://restheart.com) web site.
+
+To activate the license key, you need to download and install the **License Key Activator Plugin**.
+
+As long as this process is not completed, the terms and conditions of the Affero General Public License are in force.
+
+## Requirements
+The License Key Activator Plugin requires RESTHeart version 5.0 and later.
+
+If you use a previous version you should upgrade; for more information please contact `support@softinstigate.com`
+
+## The activation process
+
+The license key activation requires three steps:
+
+1. Download, extract and copy the license key activator plugin to the RESTHeart plugins directory;
+2. Copy and extract the provided license key archive to the RESTHeart plugin directory;
+3. Execute RESTHeart and accept the license agreement.
+
+### Download, extract and copy the license key activator plugin
+
+Download the license activator plugins from `https://download.restheart.com/si-lka-.zip`.
+
+Where `` is the version of RESTHeart you are using.
+
+For instance, if you are using RESTHeart v6.1.6 the download URL is `https://download.restheart.com/si-lka-6.1.6.zip`
+
+{: .bs-callout .bs-callout-info }
+If the activator plugin for your version of RESTHeart is missing (you get error *404 Not Found*), please email us at support@softinstigate.com and we will upload it.
+
+Once downloaded, extract the zip package and copy the contained plugin jar file into the plugins directory:
+
+```bash
+$ unzip si-lka-.zip
+$ cp si-lka-/si-lka.jar /plugins
+```
+
+Where `` is the RESTHeart root directory.
+
+### Copy and extract the provided license key archive
+
+Copy the license key tar archive you have been provided by SoftInstigate to the RESTHeart plugins directory.
+
+```bash
+$ cp lickey.tar.gz /plugins
+```
+
+Where `` is the RESTHeart root directory.
+
+Extract the package files.
+
+```bash
+$ cd /plugins
+$ tar -xzf lickey.tar.gz
+```
+
+This creates the directory `lickey` with the following files:
+
+- comm-license.key
+- COMM-LICENSE.txt
+
+### Accept the License Agreement
+
+Running RESTHeart will cause the following warning message:
+
+```
+*-------------------------------------------------------------------*
+| |
+| The License Agreement has not yet been accepted. |
+| |
+| Please open your browser at http://localhost:8080/license and |
+| accept the license to continue. |
+| |
+| The HTTP listener is bound to localhost: accept the license from |
+| a browser running on the same host or edit the configuration. |
+| |
+| More information at |
+| https://restheart.org/docs/enterprise-license |
+| |
+*-------------------------------------------------------------------*
+```
+
+To properly run RESTHeart you must explicitly accept the license:
+
+ - open your browser at `http://:8080/license`.
+ - read and approve the license
+
+> To accept the License Agreement you need to select the two checkboxes and then click the "Activate the License Key" button.
+
+{: class="mx-auto d-block img-fluid"}
+
+When done, you will find the following message in RESTHeart's log:
+
+```
+ 11:20:16.445 [XNIO-1 task-2] INFO com.restheart.CommLicense - License Agreement accepted.
+```
+
+Once the License Agreement has been accepted, at startup RESTHeart just logs the following message confirming the Enterprise License is in force:
+
+```
+*-------------------------------------------------------------------*
+| |
+| This instance of RESTHeart is licenced under the Terms and |
+| Conditions of the Enterprise License Agreement. |
+| |
+*-------------------------------------------------------------------*
+```
+
+## Silent acceptance
+
+You can also accept the License Agreement with the system property `ACCEPT_LICENSE_AGREEMENT`
+
+```
+java -DACCEPT_LICENSE_AGREEMENT=true -jar restheart.jar
+```
+
+## Specify the license key directory
+
+The default directory that contains the license key is `/plugins/lickey` next to the file `si-lka.jar`:
+
+```
+- restheart.jar
+- plugins
+ - lickey
+ - comm-license.key
+ - COMM-LICENSE.txt
+```
+
+You can set a different directory with the system property `lk-dir`:
+
+```
+java -Dlk-dir=/etc/rh-lickey -jar restheart.jar
+```
+
+## Docker
+
+If you use Docker to run RESTHeart, you need to mount the `lickey` directory.
+
+Add the following option to the `docker run` command:
+
+```bash
+-v ~/plugins/lickey:/opt/restheart/plugins/lickey/
+```
+
+
diff --git a/docs/v7/example-webapps.adoc b/docs/v7/example-webapps.adoc
new file mode 100644
index 00000000..4527164e
--- /dev/null
+++ b/docs/v7/example-webapps.adoc
@@ -0,0 +1,98 @@
+---
+title: Example Web Apps built with RESTHeart
+layout: docs-adoc
+menu: overview
+---
+:page-liquid:
+
+== Introduction
+
+In this section, we'll introduce you to two web applications developed using Angular and RESTHeart, showcasing the capabilities of RESTHeart for Web Applications development.
+
+NOTE: here we use Angular. Of course you can use RESTHeart with any frontend framework!
+
+These examples demonstrate the versatility and ease of use of RESTHeart, which can be seamlessly integrated with various frontend frameworks to build dynamic web applications. Whether you are using Angular, React, or any other framework, RESTHeart provides a robust backend solution for your web development needs.
+
+== Webchat
+
+The Webchat application is a real-time chat app hosted at link:https://chat.restheart.org[chat.restheart.org^]. It enables users to engage in real-time conversations with others. What's remarkable about this application is that it requires zero lines of code for creating a real-time chat API, thanks to RESTHeart.
+
+To explore the source code and get a deeper understanding, you can access the GitHub repository at link:https://github.com/SoftInstigate/restheart-webchat[restheart-webchat GitHub repository^].
+
+Moreover, the app leverage RESTHeart link:/docs/mongodb-websocket[Change Streams]'s, allowing instant notifications to clients about any data modifications through WebSockets.
+
+[.iframe]
+++++
+
+++++
+
+[.mt-4]
+To gain insights into the communication flow between the web clients and RESTHeart, refer to the following diagram:
+
+[.img-fluid]
+image::/images/webchat-diagram.gif[Webchat Communication Diagram]
+
+== Messages Table View
+
+The Messages Table View application offers a simple and intuitive way to display a tabular view of _message_ documents stored in a MongoDB collection. Additionally, it provides a user-friendly form to create new messages. This application is hosted at link:https://ng-demo.restheart.org[ng-demo.restheart.org^].
+
+For those interested in exploring the source code, the GitHub repository can be found at link:https://github.com/SoftInstigate/restheart-ng-demo[restheart-ng-demo GitHub repository^].
+
+By utilizing RESTHeart, you can effortlessly build and manage this type of web application, making it a valuable tool for frontend developers looking to create interactive and data-driven experiences.
+
+Here's a live demo of the Messages Table View application:
+
+[.iframe]
+++++
+
+++++
+
+[.mt-4]
+Let's examine the advantages of using RESTHeart. With the REST MongoDB API plugin, there's no need for any backend code, and the only frontend code required to interact with it is as follows:
+
+[source,typescript]
+----
+@Injectable()
+export class Service {
+ url = 'https://demo.restheart.org/messages';
+
+ constructor(private http: HttpClient) {
+ }
+
+ public get(page: number = 1): Observable
+
+* [Introduction](#introduction)
+* [Why GraalVM](#why-graalvm)
+* [Install the GraalVM](#install-the-graalvm)
+* [Run RESTHeart with GraalVM](#run-restheart-with-graalvm)
+* [Build stock RESTHeart as native image](#build-stock-restheart-as-native-image)
+* [Build RESTHeart with custom plugins as native image](#build-restheart-with-custom-plugins-as-native-image)
+* [A docker image to build Linux native images](#a-docker-image-to-build-linux-native-images)
+
+
+
+
+
+{% include docs-head.html %}
+
+## Introduction
+
+[GraalVM](https://www.graalvm.org/) is a new virtual machine from Oracle that supports a polyglot runtime environment and the ability to compile Java applications to native images.
+
+RESTHeart fully supports the GraalVM:
+
+- RESTHeart can be run and is supported on the GraalVM
+- Services and Interceptors can be implemented in JavaScript and TypeScript leveraging the GraalVM polyglot programming model
+- RESTHeart (and your custom plugins) can be built as a native image using GraalVM’s `native-image` tool
+
+## Why GraalVM
+
+GraalVM provides advanced optimizing compiler that generates fast lean code which requires fewer compute resources and allows Ahead-of-Time Compilation to build
+Native binaries that start up instantly and deliver peak performance with no warm up time.
+
+
+
+The numbers clearly show that running RESTHeart as a native image is ideal for microservices and clustering. With instant startup time and smaller memory footprint you can run multiple instances of RESTHeart Docker images and also better support dynamic scaling.
+
+{: .bs-callout.bs-callout-warning}
+In some use cases, native image might result in slightly worse peak performance. Read [this great article](https://stackoverflow.com/questions/59488654/does-graalvm-native-image-increase-overall-application-performance-or-just-reduc) for more information. The fact that peak performances might be worse, is well compensated by the ability to run more RESTHeart instances in parallel due to much smaller memory footprint.
+
+## Install the GraalVM
+
+We suggest to install GraalVM with [sdkman](https://sdkman.io)
+
+You need at least version 22.1.0 for Java 17:
+
+```bash
+$ sdk install java 17.0.8-graal
+```
+
+After having installed GraalVM, you can install the `native-image` tool with `gu`
+
+```bash
+$ gu install native-image
+```
+
+## Run RESTHeart with GraalVM
+
+Check that GraalVM SDK is active:
+
+```bash
+$ java -version
+java version "17.0.8" 2023-07-18 LTS
+Java(TM) SE Runtime Environment Oracle GraalVM 17.0.8+9.1 (build 17.0.8+9-LTS-jvmci-23.0-b14)
+Java HotSpot(TM) 64-Bit Server VM Oracle GraalVM 17.0.8+9.1 (build 17.0.8+9-LTS-jvmci-23.0-b14, mixed mode, sharing)
+```
+
+Then just run RESTHeart as usual:
+
+```bash
+$ java -jar restheart.jar etc/restheart.yml -e etc/default.properties
+```
+
+## Build stock RESTHeart as native image
+
+{: .bs-callout.bs-callout-info }
+A Docker image of RESTHeart native is available tagged as `softinstigate/restheart:-native`
+
+Example:
+
+```bash
+$ docker pull softinstigate/restheart:latest-native
+```
+
+The [docker-compose-native.yml](https://github.com/SoftInstigate/restheart/blob/master/docker-compose-native.yml) leveraging restheart-native is available as well. It runs restheart-native and MongoDB stack.
+
+### how to build from source
+
+RESTHeart's `pom.xml` includes the `native` profile.
+
+Check that GraalVM SDK is active:
+
+```bash
+$ java -version
+java version "17.0.8" 2023-07-18 LTS
+Java(TM) SE Runtime Environment Oracle GraalVM 17.0.8+9.1 (build 17.0.8+9-LTS-jvmci-23.0-b14)
+Java HotSpot(TM) 64-Bit Server VM Oracle GraalVM 17.0.8+9.1 (build 17.0.8+9-LTS-jvmci-23.0-b14, mixed mode, sharing)
+```
+
+You can then simply build it with:
+
+```bash
+$ git checkout https://github.com/SoftInstigate/restheart.git
+$ cd restheart
+$ ./mvnw clean package -Pnative
+```
+
+As a result, you'll find the executable binary file `target/restheart-native`.
+
+## Build RESTHeart with custom plugins as native image
+
+JavaScript plugins can be deployed on RESTHeart native. However you cannot deploy Java plugins in RESTHeart native by merely copying jars file into the plugins directory.
+
+In order to use Java or Kotlin plugins on RESTHeart native you must build them as native image together with RESTHeart.
+
+Refer to [Deploy Java Plugins On Restheart Native](https://restheart.org/docs/plugins/deploy/#deploy-java-plugins-on-restheart-native) for detailed instructions on how to do it.
+
+## build native image
+
+Build image for local OS
+
+```bash
+$ ./mvnw clean package -Pnative -DskipTests
+```
+
+__Note__: Linux needs to use the `G1` garbage collector. This is obtained by passing the `-Dnative.gc="--gc=G1"` property to maven.
+
+## A docker image to build Linux native images
+
+[SoftInstigate](https://softinstigate.com) maintains the Debian based, docker image [softinstigate/graalvm-maven](https://github.com/SoftInstigate/graalvm-maven-docker) with GraalVM and Maven and `native-image`.
+
+Use it if you are running a different OS and you need to build a native image for Linux to include it in a Docker image.
+
+```bash
+$ docker pull softinstigate/graalvm-maven
+```
+
+You can build a Linux native image with:
+
+```bash
+$ docker run -it --rm \
+ -v "$PWD":/opt/app \
+ -v "$HOME"/.m2:/root/.m2 \
+ softinstigate/graalvm-maven \
+ clean package -Pnative -DskipTests -Dnative.gc="--gc=G1"
+```
+
+native-image arguments are defined in [this file](https://github.com/SoftInstigate/restheart/blob/master/core/src/main/resources/META-INF/native-image/org.restheart/restheart/native-image.properties).
+
+
diff --git a/docs/v7/graphql-redirect.md b/docs/v7/graphql-redirect.md
new file mode 100644
index 00000000..5f3623ac
--- /dev/null
+++ b/docs/v7/graphql-redirect.md
@@ -0,0 +1,7 @@
+---
+permalink: "/docs/graphql"
+layout: redirect
+redirectUrl: "/docs/mongodb-graphql"
+sitemap: false
+---
+
diff --git a/docs/v7/index.adoc b/docs/v7/index.adoc
new file mode 100644
index 00000000..c520796a
--- /dev/null
+++ b/docs/v7/index.adoc
@@ -0,0 +1,162 @@
+---
+title: Get Started with RESTHeart v7
+layout: docs-adoc
+menu: overview
+---
+
+> *RESTHeart is a modern, JVM and GraalVM-based platform for building cloud-native HTTP microservices*
+
+NOTE: An _HTTP microservice_ is a server-side, lightweight component that exposes an HTTP API. Clients interact with it only through HTTP requests, usually - but not exclusively - using JSON payloads, decoupling the client from the underlying technology and completely separating the presentation from the business logic.
+
+*Speed and Ease*
+
+RESTHeart prioritizes speed and simplicity, carefully crafted with top-notch libraries for a seamless developer experience.
+
+*Empower Developers, Streamline Applications*
+
+RESTHeart aims to empower developers with an intuitive framework encompassing essential features. This approach positions RESTHeart as a true low-code platform, offering developers customizable APIs that are ready to go.
+
+*Plug-and-Play, Extendable APIs*
+
+Save time and effort with RESTHeart's pre-configured APIs, covering a broad range of functionality. These APIs are highly customizable to fit your specific application needs.
+
+++++
+
+
+Startup time
+ Memory Footprint
+
+
+
+
+
+{: .bs-callout.bs-callout-info.mt-3.small}
+Images from graalvm.org website.
+
+### Benefits of running RESTHeart with the GraalVM
+
+The GraalVM is faster than OpenJDK and it is also a polyglot runtime environment, so that you can seamlessly use multiple languages to implement RESTHeart plugins.
+
+RESTHeart leverages the GraalVM to allow developing [services](/docs/plugins/core-plugins/#services) and [interceptors](https://restheart.org/docs/plugins/core-plugins/#interceptors) using JavaScript.
+
+See [Polyglot JavaScript Services and Interceptors](/docs/plugins/core-plugins-js) for more details.
+
+{: .bs-callout.bs-callout-info}
+Want to see some code? Several [code examples](https://github.com/SoftInstigate/restheart/tree/master/polyglot/src/test/resources/test-js-plugins) are available as well.
+
+### Benefits of running RESTHeart as a native image
+
+Building a RESTHeart application to native image provides multiple advantages, including faster startup time and smaller memory footprint.
+
+{: .bs-callout.bs-callout-info}
+A *RESTHeart application* is a bundle of RESTHeart core and plugins. The plugins can include the one shipped with RESTHeart (`restheart-mongodb.jar` and `restheart-security.jar`) and custom plugins that implement your application logic.
+
+The following table compares RESTHeart (with default plugins) running on a MacBook Pro with OpenJDK, GraalVM CE and GraalVM CE native image.
+
+{: .table }
+||OpenJDK|GraalVM CE|GraalVM CE native|
+|-|-|-|-|
+|startup time|2441ms|2042ms|249ms|
+|memory|487Mbyte|761Mbyte|279Mbyte|
+|integration test execution time|63,503s|57,292s|52,518s|
+
+
+
+The numbers clearly show that running RESTHeart as a native image is ideal for microservices and clustering. With instant startup time and smaller memory footprint you can run multiple instances of RESTHeart Docker images and also better support dynamic scaling.
+
+{: .bs-callout.bs-callout-warning}
+In some use cases, native image might result in slightly worse peak performance. Read [this great article](https://stackoverflow.com/questions/59488654/does-graalvm-native-image-increase-overall-application-performance-or-just-reduc) for more information. The fact that peak performances might be worse, is well compensated by the ability to run more RESTHeart instances in parallel due to much smaller memory footprint.
+
+## Install the GraalVM
+
+We suggest to install GraalVM with [sdkman](https://sdkman.io)
+
+You need at least version 22.1.0 for Java 17:
+
+```bash
+$ sdk install java 17.0.8-graal
+```
+
+After having installed GraalVM, you can install the `native-image` tool with `gu`
+
+```bash
+$ gu install native-image
+```
+
+## Run RESTHeart with GraalVM
+
+Check that GraalVM SDK is active:
+
+```bash
+$ java -version
+java version "17.0.8" 2023-07-18 LTS
+Java(TM) SE Runtime Environment Oracle GraalVM 17.0.8+9.1 (build 17.0.8+9-LTS-jvmci-23.0-b14)
+Java HotSpot(TM) 64-Bit Server VM Oracle GraalVM 17.0.8+9.1 (build 17.0.8+9-LTS-jvmci-23.0-b14, mixed mode, sharing)
+```
+
+Then just run RESTHeart as usual:
+
+```bash
+$ java -jar restheart.jar etc/restheart.yml -e etc/default.properties
+```
+
+## Build stock RESTHeart as native image
+
+{: .bs-callout.bs-callout-info }
+A Docker image of RESTHeart native is available tagged as `softinstigate/restheart:
+ 
+
+++++
+
+== What makes RESTHeart different from other frameworks?
+
+*RESTHeart* is a framework for building HTTP microservices comparable to others, like _Undertow_ (internally used by RESTHeart), _Vert.x_, _Quarkus_, _Spring Boot_, _Node.js_, etc.
+
+However, RESTHeart does not only comprise a framework but also a set of application-level features that allow developers to build their applications without the need to reinvent the wheel.
+
+++++
+
+ RESTHeart features set
+
+ 
+
+++++
+
+`restheart-core` is the foundation of the platform, the runtime process responsible for handling the core services, parsing the configuration, registering the plugins, enforcing the security policy, resolving dependency injections with the available `Providers`, routing requests to the correct `Services`, executing `Interceptors` and `Initializers`.
+
+If you look at the RESTHeart installation directory structure, you will notice a directory called `plugins`:
+
+[source,bash]
+----
+plugins
+├── restheart-graphql.jar
+├── restheart-mongoclient-provider.jar
+├── restheart-mongodb.jar
+├── restheart-polyglot.jar
+└── restheart-security.jar
+----
+
+Those plugins implement application-level functionalities that help build applications.
+
+For instance, the plugin `restheart-mongodb` implements the REST API for MongoDB and `restheart-security.jar` implements the ready-to-use Authentication and Authorization features.
+
+A developer can easily deploy a custom plugin, by just adding it into the `plugins` directory. The plugin is just a JAR file, in the case of Java or Kotlin and a directory with its `package.json` file in the case of JavaScript.
+
+== Built for developers
+
+RESTHeart is built for developers by developers and evolved by implementing dozens of real-world projects.
+
+- Only four, simple yet powerful building blocks: `Services`, `Providers` `Interceptors` and `Initializers`.
+- Starts in 100~ milliseconds, so code-deploy-test cycles are smooth and fast.
+- Each request is handled in a dedicated thread, so all code is _thread-safe_, _simple_ to write and maintain and _scales well_.
+- Powerful Dependency Injection via `@Inject` annotation and `Provider` plugin.
+- The framework is polyglot and supports *Java*, *Kotlin*, *JavaScript* and *Typescript*.
+- Well documented with many examples and tutorials available. Check link:https://github.com/SoftInstigate/restheart/tree/master/examples[plugin examples].
+
+Here you have the _Hello World_ example in *Java*:
+
+[source,java]
+----
+@RegisterPlugin(name = "greetings", description = "just another Hello World")
+public class GreeterService implements JsonService {
+ @Override
+ public void handle(JsonRequest request, JsonResponse response) {
+ response.setContent(object().put("message", "Hello World!"));
+ }
+}
+----
+
+And the same in *Javascript*
+
+[source,javascript]
+----
+export const options = { name: "greetings", description: "just another Hello World" }
+
+export function handle(request, response) {
+ response.setContent(JSON.stringify({ msg: 'Hello World' }));
+ response.setContentTypeAsJson();
+}
+----
+
+NOTE: Javascript is executed in a thread-safe, multi-threading concurrency environment. So you don't need to deal with async/await, promises, observable or any other fancy stuff. *Just clean and simple code*.
+
+== Features
+
+RESTHeart provides developers with the features required by most applications: authentication, authorization and data management:
+
+- Declarative Authentication and Authorization.
+- Instant REST, GraphQL and WebSocket API for MongoDB.
+- SDK to easily develop custom features.
+
+> Most applications just require this. Then you just run a stock RESTHeart. Really, no code!
+
+TIP: Check the link:/docs/try[demo Web Chat application]. It requires *zero* lines of backend code.
+
+== The perfect MongoDB’s companion
+
+RESTHeart is the best API for MongoDB any compatible database (like link:https://www.ferretdb.io[FerretDB], AWS DocumentDB and Azure CosmosDB).
+
+- It exposes the full database’s capabilities via *REST*, *GraphQL* and *WebSocket* APIs.
+- Developers don’t need to write a single line of backend code to handle data with Mobile Apps, Web Apps or Integration Middleware.
+- The Instant Data API cuts development complexity and costs by up to 90%.
+
+++++
+
+ RESTHeart modular architecture
+
+ 
+
+++++
+
+== Extreme Performances
+
+*Hundreds of thousands TPS*
+
+RESTHeart parallel architecture provides superior performance.
+link:/docs/performances[Read More]
+
+*Horizontal scaling*
+
+RESTHeart is fully stateless and allows clustering, to reach demanding
+requirements.
+link:/docs/clustering[Read More]
+
+*Even faster on GraalVM*
+
+RESTHeart on GraalVM provides a
+native solution with instant startup time and a smaller memory footprint.
+This is perfect when deploying to Kubernetes clusters,
+where regular Java applications usually consume too many resources.
+
+== Deploy at rest
+
+RESTHeart is tailored for the JVM, GraalVM, Docker or Kubernetes,
+designed to radically simplify microservices development and deployment.
+
+- Ready-to-run Runtime.
+- Available as a standalone JAR file, native binary or Docker image.
+- Deploy it on Cloud and On-Premises.
+
+== Open-source and business-friendly licenses
+
+RESTHeart is dual-licensed under the AGPL and a *Business Friendly* Enterprise License.
+
+- Use the free AGPL distribution without feature restrictions.
+- Rely on the Enterprise License for production-grade support and to use RESTHeart in closed-source products or services link:https://restheart.com[Read More].
diff --git a/docs/v7/logging.adoc b/docs/v7/logging.adoc
new file mode 100644
index 00000000..bac8c76d
--- /dev/null
+++ b/docs/v7/logging.adoc
@@ -0,0 +1,168 @@
+---
+title: Documentation
+layout: docs-adoc
+menu: setup
+---
+
+== Introduction
+
+RESTHeart uses for logging the http://logback.qos.ch[LogBack] implementation of http://www.slf4j.org[SLF4J].
+
+== Default LogBack configuration
+
+restheart.jar embeds the following default `logback.xml` configuration.
+
+[source,xml]
+----
+
+
+
+ MongoDB features supported by RESTHeart
+
+
+- [Introduction ](#introduction)
+- [Upload the CSV file](#upload-the-csv-file)
+- [Query parameters](#query-parameters)
+- [Update documents from CSV](#update-documents-from-csv)
+- [Transform data](#transform-data)
+
+
+
+
+
+{% include docs-head.html %}
+
+## Introduction
+
+_A comma-separated values (CSV) file is a delimited text file that uses a comma to separate values. A CSV file stores tabular data (numbers and text) in plain text. Each line of the file is a data record. Each record consists of one or more fields, separated by commas. The use of the comma as a field separator is the source of the name for this file format._
+
+The CSV file format is supported by almost all spreadsheets and database management systems, including Microsoft Excel, Apple Numbers, LibreOffice Calc, and Apache OpenOffice Calc.
+
+The CSV Uploader Service allows importing data from a CSV file into a MongoDB collection.
+
+This RESTHeart service is bound to the `/csv` API resource by default.
+
+{: .bs-callout.bs-callout-info}
+By uploading a CSV file you create or update one document per each row of the file.
+
+### Before running the example requests
+
+The following examples assume the RESTHeart running on `localhost` with the default configuration: the database `restheart` is bound to `/` and the user `admin` exists with default password `secret`.
+
+To create the `restheart` db, run the following:
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/e1d4fc9769d1fd15fc11f8b0b360897668ff11a9/0"
+%}
+
+```http
+PUT / HTTP/1.1
+```
+
+Let's create a `poi` collection, run the following:
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/0f076791d9d87f503299c588b626675296ec4adb/0"
+%}
+
+```http
+PUT /poi HTTP/1.1
+```
+
+## Upload the CSV file
+
+We are going to use the following example file `POI.csv`:
+
+```
+id,name,city,lat,lon,note
+1,Coliseum,Rome,41.8902614,12.4930871,Also known as the Flavian Amphitheatre
+2,Duomo,Milan,45.464278,9.190596,Milan Cathedral
+```
+
+To import the `POI.csv` into the collection `poi`, run the following:
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/93ed5c1c6b20f9e8899b2308232e8ab8b5ee6820/0"
+%}
+
+```http
+POST /csv?db=restheart&coll=poi&id=0 HTTP/1.1
+Content-Type: text/csv
+
+id,name,city,lat,lon,note
+1,Coliseum,Rome,41.8902614,12.4930871,Also known as the Flavian Amphitheatre
+2,Duomo,Milan,45.464278,9.190596,Milan Cathedral
+```
+
+{: .bs-callout.bs-callout-info}
+The `/csv` path is a reserved path, used by the RESTHeart CSV Uploader Service
+
+{: .bs-callout.bs-callout-info }
+Note that the Content-Type must be `text/csv` otherwise you'll get a `400 Bad Request` error.
+
+Now the `/poi` collection contains the documents:
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/adf673704bf76f7c2ee8f3273f0f8cfe6d975596/0"
+%}
+
+```http
+GET /poi HTTP/1.1
+```
+
+{% include code-header.html
+ type="Response"
+%}
+
+```
+[{
+ "_id": 2,
+ "city": "Milan",
+ "lat": 45.464278,
+ "lon": 9.190596,
+ "name": "Duomo",
+ "note": "Milan Cathedral",
+ "_etag": {
+ "$oid": "5d249beebb77e333b6dc9c84"
+ }
+},
+{
+ "_id": 1,
+ "city": "Rome",
+ "lat": 41.8902614,
+ "lon": 12.4930871,
+ "name": "Coliseum",
+ "note": "Also known as the Flavian Amphitheatre",
+ "_etag": {
+ "$oid": "5d249beebb77e333b6dc9c83"
+ }
+}]
+```
+
+## Query parameters
+
+The CSV uploader service is controlled by the following query parameters.
+
+{: .table }
+|query parameter|description|default value|
+|-|-|
+|`db`|(_required_) the name of the database|no default|
+|`coll`|(_required_) the name of the collection|no default|
+|`id`|id column index |no id column|
+|`sep`|column separator |,|
+|`update`|if `true`, update matching documents|false|
+|`upsert`|applies when `update=true`; if `true`, create new document if no documents match the \_id |true|
+|`props`|additional properties to add to each row, e.g. `?props=foo&props=bar`|no props|
+|`values`|values of additional properties to add to each row e.g. `?values=1&values=2`|no values|
+
+{: .bs-callout.bs-callout-info}
+If the `id` parameter is not specified, a document is created with a new `ObjectId` per each CSV row.
+
+## Update documents from CSV
+
+If the CSV lines are changed or new ones are added, you can update your collection with the `update` and `upsert` parameters.
+
+To update your collection use the `update` parameter.
+
+{: .bs-callout.bs-callout-warning }
+New lines in the CSV will _NOT_ be added.
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/79039d27d707ec45ecd0c65b9485c169606c0cf3/0"
+%}
+
+```http
+POST /csv?db=restheart&coll=poi&id=0&update=true HTTP/1.1
+Content-Type: text/csv
+
+id,name,city,lat,lon,note
+1,Coliseum,Rome,41.8902614,12.4930871,Also known as the Flavian Amphitheatre -UPDATED-
+2,Duomo,Milan,45.464278,9.190596,Milan Cathedral -UPDATED-
+3,Cattedrale di Santa Maria del Fiore,43.773251,11.255474,Florence Cathedral
+```
+
+To update existing documents _and_ add new ones, add the `upsert=true` query parameter:
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/102cc2b5ebddc0b1ee0856bb04d2864c1916b436/0"
+%}
+
+```http
+POST /csv?db=restheart&coll=poi&id=0&update=true&upsert=true HTTP/1.1
+Content-Type: text/csv
+
+id,name,city,lat,lon,note
+1,Coliseum,Rome,41.8902614,12.4930871,Also known as the Flavian Amphitheatre
+2,Duomo,Milan,45.464278,9.190596,Milan Cathedral
+3,Cattedrale di Santa Maria del Fiore,43.773251,11.255474,Florence Cathedral
+```
+
+## Transform Data
+
+The CSV format allows creating flat documents. Using an Interceptor data can be modified to take advantage of the nested nature of JSON.
+
+We will use [csv-interceptor](https://github.com/SoftInstigate/restheart/tree/master/examples/csv-interceptor) from the plugin examples.
+
+Clone the RESTHeart repository
+
+```bash
+$ git clone --depth 1 git@github.com:SoftInstigate/restheart.git
+```
+
+Build the examples:
+
+```
+$ cd restheart/examples
+$ ./mvnw package
+```
+
+Deploy the csv-interceptor
+
+```bash
+$ cp csv-interceptor/target/csv-interceptor.jar /plugins
+```
+
+Restarting RESTHeart, the plugins will be automatically deployed.
+
+### The coordsToGeoJson Interceptor
+
+The code of the coordsToGeoJson follows:
+
+```java
+@RegisterPlugin(name = "coordsToGeoJson",
+ description = "transforms cordinates array to GeoJSON point object for csv loader service")
+public class CoordsToGeoJson implements Interceptor {
+ @Override
+ public void handle(BsonFromCsvRequest request, BsonResponse response) throws Exception {
+ var docs = request.getContent();
+
+ if (docs == null) {
+ return;
+ }
+
+ docs.stream()
+ .map(doc -> doc.asDocument())
+ .filter(doc -> doc.containsKey("lon") && doc.containsKey("lat"))
+ .forEachOrdered(doc -> {
+ // get Coordinates
+ var coordinates = new BsonArray();
+ coordinates.add(doc.get("lon"));
+ coordinates.add(doc.get("lat"));
+
+ var point = new BsonDocument();
+
+ point.put("type", new BsonString("Point"));
+ point.put("coordinates", coordinates);
+
+ // Add the object to the document
+ doc.append("point", point);
+ });
+ }
+
+ @Override
+ public boolean resolve(BsonFromCsvRequest request, BsonResponse response) {
+ return request.isHandledBy("csvLoader")
+ && request.isPost()
+ && "/csv".equals(request.getPath());
+ }
+}
+```
+
+Note that the `resolve()` method returns true for POST requests on the /csv URI (where the csvLoader service is bound).
+
+The `handle()` method receives the `BsonFromCsvRequest` object that contains a `BsonArray` of documents parsed from the uploaded CSV data. It uses a stream to process all documents containing the properties `lon` and `lat` to add the corresponding GeoJSON object.
+
+The interceptor implements the `Interceptor` interface specifying the parametric types `BsonFromCsvRequest` and `BsonResponse`. This is mandatory since an interceptor can intercept requests handled by services that use the same exact types (Check the code of [CsvLoader](https://github.com/SoftInstigate/restheart/blob/master/mongodb/src/main/java/org/restheart/mongodb/services/CsvLoader.java) service, it implements the parametric `Service` interface using those types).
+
+```java
+public class CoordsToGeoJson implements Interceptor
+```
+
+
+After uploading csv data the result is the following. The GeoJSON field is `point`.
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/93ed5c1c6b20f9e8899b2308232e8ab8b5ee6820/0"
+%}
+
+```http
+POST /csv?db=restheart&coll=poi&id=0 HTTP/1.1
+Content-Type: text/csv
+
+id,name,city,lat,lon,note
+1,Coliseum,Rome,41.8902614,12.4930871,Also known as the Flavian Amphitheatre
+2,Duomo,Milan,45.464278,9.190596,Milan Cathedral
+```
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/adf673704bf76f7c2ee8f3273f0f8cfe6d975596/0"
+%}
+
+```http
+GET /poi HTTP/1.1
+```
+
+{% include code-header.html
+ type="Response"
+%}
+
+```
+[
+ {
+ "_etag": {
+ "$oid": "5ed905845db98d3376dc30c8"
+ },
+ "_id": 2,
+ "city": "Milan",
+ "lat": 45.464278,
+ "lon": 9.190596,
+ "name": "Duomo",
+ "note": "Milan Cathedral",
+ "point": {
+ "coordinates": [
+ 9.190596,
+ 45.464278
+ ],
+ "type": "Point"
+ }
+ },
+ {
+ "_etag": {
+ "$oid": "5ed905845db98d3376dc30c7"
+ },
+ "_id": 1,
+ "city": "Rome",
+ "lat": 41.8902614,
+ "lon": 12.4930871,
+ "name": "Coliseum",
+ "note": "Also known as the Flavian Amphitheatre",
+ "point": {
+ "coordinates": [
+ 12.4930871,
+ 41.8902614
+ ],
+ "type": "Point"
+ }
+ }
+]
+```
\ No newline at end of file
diff --git a/docs/v7/mongodb-rest/dbs-collections.md b/docs/v7/mongodb-rest/dbs-collections.md
new file mode 100644
index 00000000..8195ac27
--- /dev/null
+++ b/docs/v7/mongodb-rest/dbs-collections.md
@@ -0,0 +1,205 @@
+---
+title: Databases and Collections
+layout: docs
+menu: mongodb
+---
+
+
+
+- [Introduction](#introduction)
+- [Create a collection](#create-a-collection)
+- [Modify the properties of a collection](#modify-the-properties-of-a-collection)
+- [Delete a collection](#delete-a-collection)
+- [Before running the example requests for dbs](#before-running-the-example-requests-for-dbs)
+- [Create a db](#create-a-db)
+- [Modify the properties of a db](#modify-the-properties-of-a-db)
+- [Delete a db](#delete-a-db)
+
+
+
+
+{% include docs-head.html %}
+
+## Introduction
+
+RESTHeart allows managing dbs and collections.
+
+## Create a collection
+
+```http
+PUT /foo HTTP/1.1
+
+{ "descr": "just a test collection" }
+
+HTTP/1.1 201 Created
+
+```
+
+Note that RESTHeart allows to set properties for collections.
+
+{: .bs-callout.bs-callout-info }
+Note that some properties are metadata, i.e. they have a special
+meaning for RESTheart that influences its behavior.
+
+The collection's properties can be read as follows:
+
+```http
+GET /foo/_meta HTTP/1.1
+
+HTTP/1.1 200 OK
+
+{
+ "_etag": {
+ "$oid": "5d95ef77ab3cf85b199ed3b7"
+ },
+ "_id": "_meta",
+ "descr": "just a test collection"
+}
+```
+
+## Modify the properties of a collection
+
+`PUT` and `PATCH` verbs modify the properties of the collection.
+
+{: .bs-callout.bs-callout-info}
+`PATCH` modifies only properties in the request body; `PUT` replaces the whole properties set.
+
+```http
+PATCH /newDb HTTP/1.1
+
+{ "owner": "Bob" }
+
+HTTP/1.1 200 OK
+```
+
+## Delete a collection
+
+To delete a collection, the ETag must be passed using the `If-Match` request header.
+
+Let's try to delete the collection `foo` without passing it.
+
+```http
+DELETE /foo HTTP/1.1
+
+HTTP/1.1 409 Conflict
+...
+ETag: 5d95ef77ab3cf85b199ed3b7
+
+{
+ "http status code": 409,
+ "http status description": "Conflict",
+ "message": "The ETag must be provided using the 'If-Match' header."
+}
+```
+
+Now let's pass the If-Match` request header, the db will be deleted.
+
+```http
+DELETE /foo HTTP/1.1
+If-Match: 5d95ef77ab3cf85b199ed3b7
+
+HTTP/1.1 204 No Content
+```
+
+## Before running the example requests for dbs
+
+The following examples that all dbs are exposes via RESTHeart. For this, edit the property file `etc/default.properties` and set `root-mongo-resource = '*'`:
+
+```
+# The MongoDB resource to bind to the root URI /
+# The format is /db[/coll[/docid]] or '*' to expose all dbs
+root-mongo-resource = '*'
+```
+
+After restarting RESTHeart, all MongoDB resources are exposes by RESTHeart. With this configuration the URIs are a follows:
+
+- database: `/restheart`,
+- collection: `/restheart/inventory`
+- document: `/restheart/inventory/5d08b08097c4c04680c41579`.
+
+For instance, we can list the existing dbs as follows:
+
+```http
+GET / HTTP/1.1
+
+[
+ "restheart",
+ "myDb",
+ ...
+]
+
+```
+
+## Create a db
+
+```http
+PUT /newDb HTTP/1.1
+
+{ "descr": "just a test db" }
+
+HTTP/1.1 201 Created
+
+```
+
+Note that RESTHeart allows to set properties for dbs.
+
+{: .bs-callout.bs-callout-info }
+Note that some properties are metadata, i.e. they have a special
+meaning for RESTheart that influences its behavior.
+
+This properties can be read as follows:
+
+```http
+GET /newDb/_meta HTTP/1.1
+
+HTTP/1.1 200 OK
+
+{
+ "_etag": {
+ "$oid": "5d95ed1dab3cf85b199ed3b6"
+ },
+ "_id": "_meta",
+ "desc": "just a test db"
+}
+```
+
+## Modify the properties of a db
+
+`PUT` and `PATCH` verbs modify the properties of the collection.
+
+```http
+PATCH /newDb HTTP/1.1
+
+{ "owner": "Bob" }
+
+HTTP/1.1 200 OK
+```
+
+## Delete a db
+
+To delete a db, the ETag must be passed using the `If-Match` request header.
+
+Let's try to delete the `newDb` without passing it.
+
+```http
+DELETE /newDb HTTP/1.1
+
+HTTP/1.1 409 Conflict
+...
+ETag: 5d95ed1dab3cf85b199ed3b6
+
+{
+ "http status code": 409,
+ "http status description": "Conflict",
+ "message": "The database's ETag must be provided using the 'If-Match' header."
+}
+```
+
+Now let's pass the If-Match` request header, the db will be deleted.
+
+```http
+DELETE /newDb HTTP/1.1
+If-Match: 5d95ed1dab3cf85b199ed3b6
+
+HTTP/1.1 204 No Content
+```
diff --git a/docs/v7/mongodb-rest/etag.md b/docs/v7/mongodb-rest/etag.md
new file mode 100644
index 00000000..95eb18ba
--- /dev/null
+++ b/docs/v7/mongodb-rest/etag.md
@@ -0,0 +1,196 @@
+---
+title: ETag
+layout: docs
+menu: mongodb
+---
+
+
+
+NOTE: Specify multiple sort options using multiple `sort` query parameters
+
+[source,http]
+GET /inventory?sort=qty&sort=-status HTTP/1.1
+
+=== Sort JSON expression format
+
+`sort` can also be a MongoDB link:https://docs.mongodb.com/manual/reference/method/cursor.sort/#cursor.sort[sort expression].
+
+[source]
+sort={"field": 1}
+
+=== Default sorting
+
+The default sorting of the documents is by the *id descending*.
+
+In the usual case, where the type of the ids of the documents is
+ObjectId, this makes the documents sorted by creation time by default
+(ObjectId have a timestamp in the most significant bits).
+
+RESTHeart returns data in pages (default being 100) and it is stateless.
+This means that two requests use different db cursors. A default sorting
+makes sure that requests on different pages returns documents in a well
+defined order.
+
+TIP: Default sorting could impact performances for some use cases. To _disable_ default sorting add the`sort={}` query parameter
+
+=== Sorting Examples
+
+==== Sort by *status* ascending
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/65aa0aae4ef7cf984c960113b21b42819a8b034b/0"
+%}
+++++
+
+
+[source,http]
+GET /inventory?sort=status HTTP/1.1
+
+or equivalently:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/dd99c056f88e5ac9f990ffcd3f2a18032007d639/0"
+%}
+++++
+
+[source,http]
+GET /inventory?sort={"status":1} HTTP/1.1
+
+==== Sort by *status* descending
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/cc4cdce5906cef6fee7859a09f5aae197d8b10f2/0"
+%}
+++++
+
+[source,http]
+GET /inventory?sort=-status HTTP/1.1
+
+or equivalently:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/e6fe674153926f9834c1aa10e156b0792dc35bc5/0"
+%}
+++++
+
+[source,http]
+GET /inventory?sort={"status":-1} HTTP/1.1
+
+==== Sort by *status* ascending and *qty* descending
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/fe1fde2e234e08de495ab533ea62529ef0f37cd6/0"
+%}
+++++
+
+[source,http]
+GET /inventory?sort=status&sort=-qty HTTP/1.1
+
+or equivalently:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/13bd5e1b3889b3c0f42fea5c694fae4c4cff5493/0"
+%}
+++++
+
+[source,http]
+GET /inventory?sort={"status":1,"qty":-1} HTTP/1.1
+
+
+==== Sort by search score
+
+NOTE: This is only possible with json expression format
+
+**create a text index**
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/ce942a7557a061396ad65dd27560158df32cc17a/0"
+%}
+++++
+
+[source,http]
+----
+PUT /inventory/_indexes/text HTTP/1.1
+
+{"keys": {"item": "text" }}
+----
+
+**sort by score**
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/da896056a261d129fddd086d5c43425b328dc7c8/0"
+%}
+++++
+
+[source,http]
+GET /inventory?filter={"$text":{"$search":"paper"}}&keys={"item":1,"score":{"$meta":"textScore"}}&sort={"score":{"$meta":"textScore"}} HTTP/1.1
+
+== Projection
+
+Projection limits the fields to return for all matching documents,
+specifying the inclusion or the exclusion of fields.
+
+This is done via the `keys` query parameter.
+
+=== Projection Examples
+
+==== Only return the property *item*
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/358ee35c14b7e564bb1cc9fa207c35286c2692fa/0"
+%}
+++++
+
+[source,http]
+GET /inventory?keys={'item':1} HTTP/1.1
+
+==== Return all but the property *item*
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/cf2e40e99b1e3ba36500ee331092b24812b85622/0"
+%}
+++++
+
+[source,http]
+GET /inventory?keys={'item':0} HTTP/1.1
+
+==== Only return the properties *item* and *qty*
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/1e60f50d60ed667a06f504f7831d7c8e85692670/0"
+%}
+++++
+
+[source,http]
+GET /inventory?keys={'item':1}&keys={'qty':1} HTTP/1.1
+
+== Hint
+
+Hint allows overriding MongoDB’s default index selection and query optimization process. See link:https://docs.mongodb.com/manual/reference/method/cursor.hint/#cursor.hint[cursor hint] on MongoDB documentation.
+
+This is done via the `hint` query parameter.
+
+Specify the index by the index specification document, either using a json document or the compact string representation; specifying the index by name is not supported.
+
+Use `$natural` to force the query to perform a forwards collection scan.
+
+=== Hint Examples
+
+Before running the following examples create the following indexes:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/12101c3d1033820c768ab65692a7816f823973db/0"
+%}
+++++
+[source,http]
+----
+PUT /inventory/_indexes/item HTTP/1.1
+
+{"keys": {"item": 1}}
+----
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/0bebde37afbb97a5c5362b54bc18748394c76059/0"
+%}
+++++
+
+[source,http]
+----
+PUT /inventory/_indexes/status HTTP/1.1
+
+{"keys":{"status": 1 }}
+----
+
+==== Use the index on item field
+
+The following example returns all documents in the collection named **coll** using the index on the **item** field.
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/fd17ca5f145ca84abeb3d7ea6a15c7e2e5932749/0"
+%}
+++++
+
+[source,http]
+GET /inventory?hint={'item':1} HTTP/1.1
+
+
+==== Use the compound index on age and timestamp fields using the compact string format
+
+The following example returns the documents using the compound index on the **item** and reverse **status** fields.
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/9cf833a9840717317888aab86eb5a92ea828dc5a/0"
+%}
+++++
+
+[source,http]
+GET /inventory?hint=item&hint=-status HTTP/1.1
+
+==== Perform a forwards collection scan
+
+The following example returns the documents using a forwards collection scan.
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/26721abb1946b0f5464565e568dff2bf52b1623c/0"
+%}
+++++
+
+[source,http]
+GET /inventory?hint={'$natural':1} HTTP/1.1
+
+
+==== Perform a reverse collection scan
+
+The following example returns the documents using a reverse collection scan.
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/4f64c9e56340214607d08f293488d3d90beffa2b/0"
+%}
+++++
+
+[source,http]
+GET /inventory?hint={'$natural':-1} HTTP/1.1
\ No newline at end of file
diff --git a/docs/v7/mongodb-rest/relationships.md b/docs/v7/mongodb-rest/relationships.md
new file mode 100644
index 00000000..d2857532
--- /dev/null
+++ b/docs/v7/mongodb-rest/relationships.md
@@ -0,0 +1,374 @@
+---
+title: Relationships
+layout: docs
+menu: mongodb
+---
+
+/` in contrast with the default configuration where it is just `/` being it this case the `` set to `restheart`.
+
+For this the mount, the URI `/sample_mflix/movies` maps to the collection `sample_mflix.movies`: the request `GET /sample_mflix/movies` retrieves the movies in the database `sample_mflix`.
+
+Alternatively you can simply add one or more database mounts as follows:
+
+[source,yml]
+----
+mongo-mounts:
+ - what: "/restheart"
+ where: /
+ - what: "/sample_mflix"
+ where: /mflix
+----
+
+NOTE: With this configuration the URI of a collection of the database `restheart` is `/` and the URI of a collection of the database `sample_mflix` is `/mflix/`.
+
+For the first mount, the URI `/users` maps to the collection `restheart.users`: the request `GET /users` retrieves the users in the database `restheart`.
+
+For the second mount, the URI `/mflix/movies` maps to the collection `sample_mflix.movies`: the request `GET /mflix/movies` retrieves the movies in the database `sample_mflix`.
\ No newline at end of file
diff --git a/docs/v7/mongodb-rest/shard-keys.md b/docs/v7/mongodb-rest/shard-keys.md
new file mode 100644
index 00000000..de15a236
--- /dev/null
+++ b/docs/v7/mongodb-rest/shard-keys.md
@@ -0,0 +1,22 @@
+---
+title: Shard Keys
+layout: docs
+menu: mongodb
+---
+
+
+
+- [Introduction](#introduction)
+- [ETag for write requests](#etag-for-write-requests)
+- [ETag for web caching](#etag-for-web-caching)
+- [ETag policy](#etag-policy)
+
+
+
+
+{% include docs-head.html %}
+
+## Introduction
+
+The **ETag** or **entity tag** is part of HTTP; it is used for:
+
+- **[Web cache](https://en.wikipedia.org/wiki/Web_cache) validation**,
+ and which allows a client to make conditional requests. This allows
+ caches to be more efficient, and saves bandwidth, as a web server
+ does not need to send a full response if the content has not
+ changed.
+- For **[optimistic concurrency
+ control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control)** as
+ a way to help prevent ghost writes, i.e. simultaneous updates of a
+ resource from overwriting each other.
+
+RESTHeart automatically manages ETags, creating and updating them.
+
+For example, let's create a database, a collection and a document. You
+can note that any response includes the header ETag (other response
+headers are omitted for simplicity) and this is valid for any type of
+resource, included file resources.
+
+```bash
+PUT /test {"descr": "a db for testing" }
+
+HTTP/1.1 201 Created
+ETag: 55e84b95c2e66d1e0a8e46b2
+(other headers omitted)
+```
+
+```bash
+PUT /test/coll { "descr": "a collection for testing" }
+
+HTTP/1.1 201 Created
+ETag: 55e84be2c2e66d1e0a8e46b3
+(other headers omitted)
+```
+
+```bash
+PUT /test/coll/doc { "descr": "a document for testing" }
+
+HTTP/1.1 201 Created
+ETag: 55e84c0ac2e66d1e0a8e46b4
+(other headers omitted)
+```
+
+```bash
+GET /test/coll/doc HTTP/1.1
+
+HTTP/1.1 200 OK
+ETag: 55e84c0ac2e66d1e0a8e46b4
+(other headers omitted)
+
+{ "descr": "a document for testing" }
+```
+
+## ETag for write requests
+
+The checking policy is configurable and the default
+policy only requires the ETag for `DELETE /db` and `DELETE /db/collection`
+requests.
+
+Previous versions always require the ETag to be specified for any write
+request.
+
+Let's try to update the document at URI `/test/coll/doc` forcing the ETag
+check with the `checkEtag` query parameter.
+
+```http
+PUT /test/coll/doc?checkEtag HTTP/1.1
+
+{ "descry": "a document for testing but modified" }
+
+HTTP/1.1 409 Conflict
+...
+ETag: 55e84c0ac2e66d1e0a8e46b4
+```
+
+RESTHeart send back the error message `409 Conflict`, showing that the
+document has not been updated.
+
+Note that the _ETag_ header is present in the response.
+
+Let's try to pass now a wrong ETag via the _If-Match_ request header
+
+```http
+PUT 127.0.0.1:8080/test/coll/doccheckEtag HTTP/1.1
+If-Match:wrong_etag
+{ "desc":"a document for testing but modified"}
+
+HTTP/1.1 412 Precondition Failed
+...
+ETag: 55e84c0ac2e66d1e0a8e46b4
+```
+
+RESTHeart send back the error message `412 Precondition Failed`, showing
+that the document has not been updated.
+
+Again the correct ETag header is present in the response.
+
+Let's try to pass now the correct ETag via the `If-Match` request header
+
+```bash
+PUT /test/coll/doc?checkEtag HTTP/1.1
+If-Match:55e84c0ac2e66d1e0a8e46b4
+
+{"descr": "a document for testing but modified"}
+
+HTTP/1.1 200 OK
+ETag: 55e84f5ac2e66d1e0a8e46b8
+(other headers omitted)
+```
+
+Yes, updated! And the response includes the new ETag value.
+
+## ETag for web caching
+
+The responses of GET requests on document and file resources always
+include the ETag header.
+
+The ETag is used by browsers for caching: after the first data
+retrieval, the browser will send further requests with _If-None-Match_
+request header. In case the resource state has not been modified
+(leading to a change in the ETag value), the response will be just *304
+Not Modified*, without passing back the data and thus saving bandwidth.
+This is especially useful for file resources.
+
+```bash
+GET /test/coll/doc HTTP/1.1
+HTTP/1.1 200 OK
+ETag: 55e84c0ac2e66d1e0a8e46b4
+(other headers omitted)
+
+{"descr": "a document for testing but modified"}
+```
+
+```bash
+GET /test/coll/doc HTTP/1.1
+If-None-Match:55e84c0ac2e66d1e0a8e46b4
+
+HTTP/1.1 304 Not Modified
+```
+
+## ETag policy
+
+RESTHeart has a default configurable ETag checking policy.
+
+The following configuration file snippet defines the default ETag check
+policy:
+
+- The policy applies for databases, collections (also applies to file
+ buckets) and documents.
+- valid values are REQUIRED, REQUIRED_FOR_DELETE, OPTIONAL
+
+It defines when the ETag check is mandatory.
+
+```yml
+etag-check-policy:
+ db: REQUIRED_FOR_DELETE
+ coll: REQUIRED_FOR_DELETE
+ doc: OPTIONAL
+```
+
+The ETag checking policy can also be modified at request level with the
+`checkETag` query parameter and at db or collection level using the
+`etagPolicy` and `etagDocPolicy` metadata.
+
+For instance specifying the following collection metadata, the ETag will
+be checked for all write requests on the collection resources and its
+documents.
+
+```json
+{
+ "etagPolicy": "REQUIRED",
+ "etagDocPolicy": "REQUIRED"
+}
+```
+
+
diff --git a/docs/v7/mongodb-rest/files.adoc b/docs/v7/mongodb-rest/files.adoc
new file mode 100644
index 00000000..277a773d
--- /dev/null
+++ b/docs/v7/mongodb-rest/files.adoc
@@ -0,0 +1,159 @@
+---
+title: Binary Files
+layout: docs-adoc
+menu: mongodb
+---
+
+RESTHeart offers complete binary files management. It's possible to **create**, **read** and **delete** even huge files. RESTHeart makes use of MongoDB's **GridFS**, a specification for storing and retrieving files that exceed the BSON-document size limit of 16 MB.
+
+You can read more about GridFS link:https://docs.mongodb.org/manual/core/gridfs/[here].
+
+== Create a File Bucket
+
+File buckets are special collections whose aim is to store binary data and the associated metadata. Start by creating a new one for uploading binaries.
+
+NOTE: A file bucket name must end with _.files_ (e.g. `mybucket.files` is a valid file bucket name)
+
+Create the default `restheart` database, if none exists yet:
+
+Create the file bucket.
+
+[source,http]
+----
+PUT /mybucket.files HTTP/1.1
+
+HTTP/1.1 201 Created
+----
+
+== Upload a file with POST
+
+`POST /bucket.files` is used to insert a file.
+
+NOTE: the request body must be encoded as `multipart/form-data`. This is obtained in the following example with the `--form` option in the `http` command
+
+The following example request POSTs the binary image `example.jpg` with `{"author":"SoftInstigate"}` metadata into `/mybucket.files`
+
+With httpie:
+
+[source,bash]
+----
+$ http -a admin:secret --form POST localhost:8080/mybucket.files @/path/to/my/binary/example.jpg metadata='{"author":"SoftInstigate", "filename": "example.jpg"}'
+
+HTTP/1.1 201 Created
+Location: http://localhost:8080/mybucket.files/5e5fcdd8ddfa017301e00331
+(other response headers omitted)
+----
+
+With curl:
+
+[source,bash]
+----
+$ curl -i -X POST -u admin:secret --form metadata='{"author":"SoftInstigate", "filename": "example.jpg"}' --form file= @/path/to/my/binary/example.jpg localhost:8080/mybucket.files
+
+HTTP/1.1 201 Created
+Location: http://localhost:8080/mybucket.files/5e5fcdd8ddfa017301e00331
+(other response headers omitted)
+----
+
+curl -i -X POST -u admin:secret --form metadata='{"filename":"hello.json"}' --form file=@/tmp/hello2.json localhost:8080/my.files
+
+The `Location` HTTP header returns the file's URI. The last part is the `_id`.
+
+NOTE: file bucket does not support write mode. The `POST` verb is always an insert. If an `_id` is specified in the request content and a file with this `_id` already exists, the request will fail with status code `409 Conflict`
+
+== Upsert a file with PUT
+
+`PUT /bucket.files/fileid` is used to upsert a file.
+
+NOTE: the request body must be encoded as `multipart/form-data`. This is obtained in the following example with the `--form` option in the `http` command
+
+With httpie:
+
+[source,bash]
+----
+$ http -a admin:secret --form PUT localhost:8080/mybucket.files/example @/path/to/my/binary/example.jpg metadata='{"author": "SoftInstigate", "filename": "example.jgp"}'
+
+HTTP/1.1 201 Created
+----
+
+With curl:
+
+[source,bash]
+----
+$ curl -i -X PUT -u admin:secret --form metadata='{"author":"SoftInstigate", "filename": "example.jpg"}' --form file=@/path/to/my/binary/example.jpg localhost:8080/mybucket.files/example
+
+HTTP/1.1 201 Created
+----
+
+NOTE: file bucket does not support write mode. The `PUT` verb is always an upsert. If the file exists, it will be updated (response code `200 Ok`) otherwise it will be created (response code `201 Created`)
+
+== GET the file metadata
+
+The file metadata is returned with `GET /bucket.files` and `GET /bucket.files/fileid` requests.
+
+[source,http]
+----
+GET http://localhost:8080/mybucket.files/example HTTP/1.1
+
+{
+ "_id": "example.jpg",
+ "chunkSize": 261120,
+ "filename": "example.jgp",
+ "length": 66273,
+ "metadata": {
+ "_etag": {
+ "$oid": "5e5fcdd8ddfa017301e00330"
+ },
+ "author": "SoftInstigate",
+ "contentType": "image/jpeg",
+ "filename": "example.jgp"
+ },
+ "uploadDate": {
+ "$date": 1583336920114
+ }
+}
+----
+
+IMPORTANT: the file `contentType` is automatically detected by RESTHeart and used to define the `Content-Type` response header.
+
+NOTE: Uploaded files metadata can be filtered and treated as regular collection documents. For example, `http://localhost:8080/mybucket.files?filter={"metadata.author":"SoftInstigate"}` returns all the file metadata that satisfy the query.
+
+== GET the file binary data
+
+The binary content is available by appending `/binary` to the file URI:
+
+[source,http]
+----
+GET http://localhost:8080/mybucket.files/example/binary HTTP/1.1
+----
+
+== Update file metadata
+
+`PUT /bucket.files/docid` and `PATCH /bucket.files/docid` are used to update the file metadata.
+
+IMPORTANT: to update the metadata, use a normal requests with `Content-Type: application/json`. This differ from upserting a file that uses a multi-part request, i.e. `Content-Type: multipart/form-data`
+
+The following request, adds the two field `foo` and `bar` to the file metadata.
+
+[source,http]
+----
+PATCH http://localhost:8080/mybucket.files/example HTTP/1.1
+
+{
+ "foo": 1,
+ "bar": 2
+}
+----
+
+The following request replaces the whole file `metadata` with the given document:
+
+[source,http]
+----
+PUT http://localhost:8080/mybucket.files/example HTTP/1.1
+
+{
+ "author": "uji"
+}
+----
+
+NOTE: update operators and update aggregation pipelines cannot be used in files updates.
\ No newline at end of file
diff --git a/docs/v7/mongodb-rest/indexes.md b/docs/v7/mongodb-rest/indexes.md
new file mode 100644
index 00000000..996c7746
--- /dev/null
+++ b/docs/v7/mongodb-rest/indexes.md
@@ -0,0 +1,148 @@
+---
+title: Collection Indexes
+layout: docs
+menu: mongodb
+---
+
+
+
+- [List the collection indexes](#list-the-collection-indexes)
+- [Create an index](#create-an-index)
+ - [Example - create an unique, sparse index on property 'qty'](#example---create-an-unique-sparse-index-on-property-qty)
+ - [Example - create a text index on property 'item'](#example---create-a-text-index-on-property-item)
+- [Delete an index](#delete-an-index)
+- [Notes](#notes)
+ - [Invalid options](#invalid-options)
+ - [Indexes cannot be updated](#indexes-cannot-be-updated)
+
+
+
+
+{% include docs-head.html %}
+
+{% include running-examples.md %}
+
+## List the collection indexes
+
+To list the collection indexes use the following request:
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/955c6f52f254b504694b8fb1b49b05e881427f8b/0"
+%}
+
+```http
+GET /inventory/_indexes HTTP/1.1
+```
+
+{% include code-header.html
+ type="Response"
+%}
+
+```json
+[
+ {
+ "v": 2,
+ "key": {
+ "_id": 1
+ },
+ "ns": "restheart.inventory",
+ "_id": "_id_"
+ }
+]
+```
+
+## Create an index
+
+To create an index you have to specify the keys and the index options:
+
+```json
+{ "keys": , "ops": }
+```
+
+### Example - create an unique, sparse index on property 'qty'
+
+To create an unique, sparse index on property `qty` run the following:
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/4e6c63ceba6860a37d53998e6e99be1ad35c226c/1"
+%}
+
+```http
+PUT /inventory/_indexes/qtyIndex HTTP/1.1
+
+{"keys": {"qty": 1},"ops": {"unique": true, "sparse": true }}
+```
+
+{: .bs-callout.bs-callout-info}
+See also
+Indexes in MongoDB documentation
+
diff --git a/docs/v7/mongodb-rest/json-schema-validation.md b/docs/v7/mongodb-rest/json-schema-validation.md
new file mode 100644
index 00000000..680934d3
--- /dev/null
+++ b/docs/v7/mongodb-rest/json-schema-validation.md
@@ -0,0 +1,265 @@
+---
+title: JSON Schema Validation
+layout: docs
+menu: mongodb
+---
+
+
+
+- [Introduction](#introduction)
+- [The Schema Store and Schema resources](#the-schema-store-and-schema-resources)
+- [Document validation](#document-validation)
+- [MongoDB BSON types](#mongodb-bson-types)
+- [Example](#example)
+- [Limitations](#limitations)
+
+
+
+
+{% include docs-head.html %}
+
+## Introduction
+
+RESTHeart supports MongoDB schema validation to enforce a format to documents: rules-based validation from MongoDB 3.2 and Json Schema validation from MongoDB 3.6, more in the [MongoDB documentation](https://docs.mongodb.com/manual/core/schema-validation).
+
+On top of this, RESTHeart provides a more general approach for
+validation based on [Interceptors](/docs/plugins/core-plugins) that can verify write requests based on any condition.
+
+RESTHeart provides "out of the box" the _jsonSchema_ Interceptor
+that validates the body of write requests against a **JSON schema**.
+
+Compared to the internal MongoDB Json Schema validation, the _jsonSchema_ Interceptor of RESTHeart provides additional advantages:
+
+- schemas are stored in a special collection, the schema store `/_schemas` and are validated
+- schemas can and can be reused on multiple collections
+- complex schemas can be defined using sub-schemas, i.e. using the [\$ref](https://json-schema.org/understanding-json-schema/structuring.html) keyword
+- documents can be validated using schemas that available online
+- schemas are cached
+
+## JSON Schema
+
+> JSON Schema specifies a JSON-based format to define the structure of
+> JSON data for validation, documentation, and interaction control. A
+> JSON Schema provides a contract for the JSON data required by a given
+> application, and how that data can be modified.
+
+For more information about JSON Schema refer
+to [json-schema.org](https://json-schema.org/); a very good resource
+is [understanding json
+schema](https://spacetelescope.github.io/understanding-json-schema) web
+site too.
+
+## The Schema Store and Schema resources
+
+_Schema Store_ resources allow store JSON schemas used for document
+validation; they are specialized collection resources whose documents
+must conform to the JSON schema format (specifically to the latest
+version draft-04)
+
+Schema Store are first class citizens in RESTHeart and the format of
+their URIs is `/_schemas`
+
+**Create the db schema store**
+
+```http
+PUT /_schemas HTTP/1.1
+```
+
+Schema resources are documents of the Schema Store. The following
+request creates a valid JSON Schema.
+
+```http
+PUT /_schemas/address?wm=upsert HTTP/1.1
+
+{
+ "$schema": "https://json-schema.org/draft-04/schema#",
+ "type": "object",
+ "properties": {
+ "address": { "type": "string" },
+ "city": { "type": "string" },
+ "postal-code": { "type": "string" },
+ "country": { "type": "string"}
+ },
+ "required": ["address", "city", "country"]
+}
+
+HTTP/1.1 201 Created
+...
+```
+
+In JSON Schema, the `id` property (not to be confused with the `_id`
+key) has a special role. This property is auto-generated by RESTHeart as
+can be noted in the response of the following GET request.
+
+```http
+GET /_schemas/address HTTP/1.1
+
+HTTP/1.1 200 OK
+
+{
+ "$schema": "https://json-schema.org/draft-04/schema#",
+ "id": "https://schema-store/restheart/address#",
+ "_id": "address",
+ ....
+}
+```
+
+## Document validation
+
+To apply the jsonSchema simply define the collection
+metadata property `jsonSchema` as follows:
+
+```json
+{
+ "jsonSchema": {
+ "schemaId": ,
+ "schemaStoreDb":
+ }
+}
+```
+
+
diff --git a/docs/v7/mongodb-rest/monitoring.md b/docs/v7/mongodb-rest/monitoring.md
new file mode 100644
index 00000000..905f1ca6
--- /dev/null
+++ b/docs/v7/mongodb-rest/monitoring.md
@@ -0,0 +1,619 @@
+---
+title: Monitoring
+layout: docs
+menu: mongodb
+---
+
+
+
+
+
+
+
+## MongoDB BSON types
+
+This section provides an approach to validate the bson types used by MongoDB.
+
+As an example, the following schema defines two bson types: `date` and `objectid`
+
+```json
+{
+ "_id": "bson",
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "definitions": {
+ "date": {
+ "type": "object",
+ "properties": {
+ "_$date": { "type": "number" }
+ },
+ "additionalProperties": false
+ },
+ "objectid": {
+ "type": "object",
+ "properties": {
+ "_$oid": { "type": "string" }
+ },
+ "additionalProperties": false
+ }
+ }
+}
+```
+
+Once the definition has been saved in the `schema-store`, the new types can be used by other schemas with the `$ref` keyword
+
+```json
+{
+ "_id": "post",
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "type": "object",
+ "properties": {
+ "_id": { "$ref": "http://schema-store/restheart/bson#/definitions/objectid" },
+ "_etag": { "$ref": "http://schema-store/restheart/bson#/definitions/objectid" },
+ "title": { "type": "string" },
+ "content": { "type": "string" },
+ "date": { "$ref": "http://schema-store/bson#/definitions/date" }
+ }
+}
+```
+
+## Example
+
+**Create a collection enforcing the address JSON Schema**
+
+```http
+PUT /addresses HTTP/1.1
+
+{
+ "jsonSchema": { "schemaId": "address" }
+}
+```
+
+Now let's try to create an invalid document.
+
+**Try to create an invalid address**
+
+```http
+POST /addresses HTTP/1.1
+
+{ "address": "Via D'Annunzio 28" }
+
+HTTP/1.1 400 Bad Request
+...
+
+{
+ "http status code": 400,
+ "http status description": "Bad Request",
+ "message": "Request content violates schema 'address': 2 schema violations found, required key [city] not found, required key [country] not found"
+}
+```
+
+Passing valid data results in the document creation:
+
+**Create a valid documents**
+
+```http
+POST /addresses HTTP/1.1
+
+{
+ "address": "Via D'Annunzio, 28",
+ "city": "L'Aquila",
+ "country": "Italy"
+}
+
+HTTP/1.1 201 Created
+```
+
+## Limitations
+
+_jsonChecker_ does not support bulk PATCH requests:
+
+{: .bs-callout.bs-callout-info }
+To handle this requests, set the metadata property `skipNotSupported` to `true`, and add specialized interceptors to validate these requests if required.
+
+```http
+PATCH /addresses/*?filter={"country":"Italy"} HTTP/1.1
+
+{ "updated": true }
+
+HTTP 1.1 501 Not Implemented
+
+{
+ "http status code": 501,
+ "http status description": "Not Implemented",
+ "message": "'jsonSchema' checker does not support bulk PATCH requests. Set 'skipNotSupported:true' to allow them."
+}
+```
+
+
+Property
+ |
+
+Description
+ |
+
+Mandatory
+ |
+
|---|---|---|
schemaId |
+the _id of the JSON schema to enforce |
+Yes | +
schemaStoreDb |
+the db | +No, if omitted the current db is used. | +
+
+- [Introduction](#introduction)
+- [Formats](#formats)
+ - [using restheart *rep* query parameter](#using-restheart-rep-query-parameter)
+ - [using HTTP content negotiation](#using-http-content-negotiation)
+- [Configuration options](#configuration-options)
+- [Reading data](#reading-data)
+- [Examples](#examples)
+- [Prometheus root metrics](#prometheus-root-metrics)
+
+
+
+
+{% include docs-head.html %}
+
+
diff --git a/docs/v7/mongodb-rest/read-docs.adoc b/docs/v7/mongodb-rest/read-docs.adoc
new file mode 100644
index 00000000..bb38cf19
--- /dev/null
+++ b/docs/v7/mongodb-rest/read-docs.adoc
@@ -0,0 +1,413 @@
+---
+title: Read Documents
+layout: docs-adoc
+menu: mongodb
+---
+
+:page-liquid:
+
+== Introduction
+
+This page provides examples of query operations using the `GET` method.
+
+You will learn how to get documents from a collection, optionally specifying a query, sort criteria, fields projections options and deal with pagination.
+
+You will also learn hot to get a single document knowing its `_id`.
+
+{% include running-examples.adoc %}
+
+== GETting Documents from a Collection
+
+To GET documents from a collection, run the following:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/5b1ea0cbcd6826ebaab3de45ce57963dfeb037d0/0"
+%}
+++++
+
+[source,http]
+GET /inventory HTTP/1.1
+
+== Paging
+
+The response is paginated, i.e. only a subset of the collection’s document is returned in the response array.
+
+The number of documents to return is controlled via the `pagesize` query
+parameter. Its default value is 100, maximum allowable size is 1000.
+
+The page to return is specified with the `page` query parameter.
+
+=== Paging Examples
+
+==== Return documents of second page with 3 documents per page
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/623a4d4d9338e182ae8fc6a7d2b1382a0e4f029e/3"
+%}
+++++
+
+[source,http]
+GET /inventory?page=2&pagesize=3 HTTP/1.1
+
+== Dot notation
+
+It's possible to use the "dot notation" to specify fields within an
+sub-document, for example:
+
+[source,http]
+GET /inventory?keys={'header.item':1}&sort={'header.status':1} HTTP/1.1
+
+== Filtering
+
+The `filter` query parameter allows to specify conditions on the
+documents to be returned in the form of a link:https://docs.mongodb.org/manual/tutorial/query-documents/[mongodb query].
+
+=== Filtering Examples
+
+==== Return documents whose `quantity` is more than 50
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/e3a1a8ba94de959d9e0099d4a3aee64ce05dff52/0"
+%}
+++++
+
+[source,http]
+GET /inventory?filter={"qty":{"$gt":50}} HTTP/1.1
+
+==== Return documents whose `quantity` is more than 25 and with `status` set to "D" value
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/9274556528ca5f4fd356a7245102bb7b483011fb/0"
+%}
+++++
+
+[source,http]
+GET /inventory?filter={"$and":[{"qty":{"$gt":75}},{"status":"D"}]} HTTP/1.1
+
+or equivalently:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/d104f56976eac72a4237324fbdcc951e9e255fc6/0"
+%}
+++++
+
+[source,http]
+GET /inventory?filter={"qty":{"$gt":75}}&filter={"status":"D"} HTTP/1.1
+
+== Counting
+
+Use `_size` keyword after the collection path to retrieve the number of documents that meets the filter condition (if present).
+
+=== Counting Examples
+
+==== Return the number of documents of "inventory" collection
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/feaa50aac771e3d7c9b9058855d79f322afa20c0/1"
+%}
+++++
+
+[source,http]
+GET /inventory/_size?filter={"status":"A"} HTTP/1.1
+
+== Sorting
+
+Sorting is controlled by the `sort` query parameter.
+
+=== Sort simple format
+
+The `sort` simplified format is :
+
+[source]
+sort=[ |-]
+
+
+## Introduction
+
+Gathering metrics about your production (and staging) environments can
+give you valuable knowledge about your infrastructure. Not only do
+metrics allow to define service level objectives, knowing their values
+open up possibilities to both monitor these values, and tackle problems
+as well - maybe even automatically.
+
+The metrics endpoints included in restheart use [Dropwizard
+metrics](https://metrics.dropwizard.io) under the hood. The measured
+values include counts, call rates, as well as timings of the calls and
+their distributions.
+
+## Formats
+
+The current implementation supports both the [Prometheus
+format](https://prometheus.io/docs/instrumenting/exposition_formats/) (which is popular in kubernetes environments), as well as the [classical
+JSON
+format](https://github.com/iZettle/dropwizard-metrics/blob/master/metrics-json/src/main/java/io/dropwizard/metrics/json/MetricsModule.java) generated
+by Dropwizard Metrics. The Prometheus format is the default one, but you
+can explicitly request one of the formats:
+
+### using restheart `rep` query parameter
+
+Simply add a query parameter `rep` to your request to the metrics
+endpoint. Use `PJ` or `PLAIN_JSON` to request the dropwizard JSON
+format, or omit the parameter to get prometheus.
+
+### using HTTP content negotiation
+
+You can also use the `Accept` header. `application/json` will select the
+dropwizard format. `text/plain` (or, if you want to be more specific:
+`text/plain; version=0.0.4`) will select the prometheus format.
+
+If you supply both query parameter and the `Accept` header, the query
+parameter wins.
+
+## Configuration options
+
+By default, restheart will only gather high-level metrics that apply to
+all databases and collections. To gather more detailed and fine-grained
+metrics (with the cost of more memory usage), you can enable additional
+collection on a per-database or per-collection level.
+
+Use config value `metrics-gathering-level`, possible values are
+
+- `OFF`
+- `ROOT (default)`
+- `DATABASE`
+- `COLLECTION`
+
+These configuration options are consecutive, e.g. COLLECTION contains
+DATABASE.
+
+## Reading data
+
+| Endpoint | Purpose |
+| ----------------------------------- | ------------------------------------------------------------- |
+| `/_metrics` | for generic over-all values. |
+| `/$DBNAME/_metrics` | for values tied to this specific database. |
+| `/$DBNAME/$COLLECTIONNAME/_metrics` | for values tied to this specific collection of this database. |
+
+If metrics are not configured to be collected at the given level, the
+endpoint will return `404 NOT FOUND`. Each upper level contains all the
+information from the deeper levels, aggregated.
+
+## Examples
+
+Note the structure of the response fields: the field names are related
+to the type of the query (e.g. `METRICS`, `DATABASE`, `COLLECTION`,
+`DOCUMENT`) and can also include the response code (none, grouped by
+first digit, full). The examples are calls to the root `/_metrics` after
+a few calls to an empty database (thus the 404s).
+
+**Prometheus example response**
+
+
+```
+http_response_timers_METRICS_count{method="GET",code="2xx"} 13 1510039263986
+http_response_timers_METRICS_max{method="GET",code="2xx"} 101.0 1510039263986
+http_response_timers_METRICS_mean{method="GET",code="2xx"} 13.66447895963094 1510039263986
+http_response_timers_METRICS_min{method="GET",code="2xx"} 4.0 1510039263986
+http_response_timers_METRICS_p50{method="GET",code="2xx"} 18.0 1510039263986
+http_response_timers_METRICS_p75{method="GET",code="2xx"} 18.0 1510039263986
+http_response_timers_METRICS_p95{method="GET",code="2xx"} 18.0 1510039263986
+http_response_timers_METRICS_p98{method="GET",code="2xx"} 18.0 1510039263986
+http_response_timers_METRICS_p99{method="GET",code="2xx"} 18.0 1510039263986
+http_response_timers_METRICS_p999{method="GET",code="2xx"} 18.0 1510039263986
+http_response_timers_METRICS_stddev{method="GET",code="2xx"} 5.779944201589175 1510039263986
+http_response_timers_METRICS_m15_rate{method="GET",code="2xx"} 0.11197540667244438 1510039263986
+http_response_timers_METRICS_m1_rate{method="GET",code="2xx"} 0.02346856889987903 1510039263986
+http_response_timers_METRICS_m5_rate{method="GET",code="2xx"} 0.040980329912974914 1510039263986
+http_response_timers_METRICS_mean_rate{method="GET",code="2xx"} 0.021582478380531817 1510039263986
+
+http_response_timers_METRICS_count{method="GET",code="200"} 13 1510039263986
+http_response_timers_METRICS_max{method="GET",code="200"} 101.0 1510039263986
+http_response_timers_METRICS_mean{method="GET",code="200"} 13.66447895963094 1510039263986
+http_response_timers_METRICS_min{method="GET",code="200"} 4.0 1510039263986
+http_response_timers_METRICS_p50{method="GET",code="200"} 18.0 1510039263986
+http_response_timers_METRICS_p75{method="GET",code="200"} 18.0 1510039263986
+http_response_timers_METRICS_p95{method="GET",code="200"} 18.0 1510039263986
+http_response_timers_METRICS_p98{method="GET",code="200"} 18.0 1510039263986
+http_response_timers_METRICS_p99{method="GET",code="200"} 18.0 1510039263986
+http_response_timers_METRICS_p999{method="GET",code="200"} 18.0 1510039263986
+http_response_timers_METRICS_stddev{method="GET",code="200"} 5.779944201589175 1510039263986
+http_response_timers_METRICS_m15_rate{method="GET",code="200"} 0.11197540667244438 1510039263986
+http_response_timers_METRICS_m1_rate{method="GET",code="200"} 0.02346856889987903 1510039263986
+http_response_timers_METRICS_m5_rate{method="GET",code="200"} 0.040980329912974914 1510039263986
+http_response_timers_METRICS_mean_rate{method="GET",code="200"} 0.021582482412705724 1510039263986
+
+http_response_timers_DOCUMENT_count{method="GET",code="404"} 1 1510039263986
+http_response_timers_DOCUMENT_max{method="GET",code="404"} 12.0 1510039263986
+http_response_timers_DOCUMENT_mean{method="GET",code="404"} 12.0 1510039263986
+http_response_timers_DOCUMENT_min{method="GET",code="404"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p50{method="GET",code="404"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p75{method="GET",code="404"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p95{method="GET",code="404"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p98{method="GET",code="404"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p99{method="GET",code="404"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p999{method="GET",code="404"} 12.0 1510039263986
+http_response_timers_DOCUMENT_stddev{method="GET",code="404"} 0.0 1510039263986
+http_response_timers_DOCUMENT_m15_rate{method="GET",code="404"} 0.1902458849001428 1510039263986
+http_response_timers_DOCUMENT_m1_rate{method="GET",code="404"} 0.09447331054820299 1510039263986
+http_response_timers_DOCUMENT_m5_rate{method="GET",code="404"} 0.17214159528501158 1510039263986
+http_response_timers_DOCUMENT_mean_rate{method="GET",code="404"} 0.019699054561810325 1510039263986
+
+http_response_timers_DOCUMENT_count{method="GET",code="4xx"} 1 1510039263986
+http_response_timers_DOCUMENT_max{method="GET",code="4xx"} 12.0 1510039263986
+http_response_timers_DOCUMENT_mean{method="GET",code="4xx"} 12.0 1510039263986
+http_response_timers_DOCUMENT_min{method="GET",code="4xx"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p50{method="GET",code="4xx"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p75{method="GET",code="4xx"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p95{method="GET",code="4xx"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p98{method="GET",code="4xx"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p99{method="GET",code="4xx"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p999{method="GET",code="4xx"} 12.0 1510039263986
+http_response_timers_DOCUMENT_stddev{method="GET",code="4xx"} 0.0 1510039263986
+http_response_timers_DOCUMENT_m15_rate{method="GET",code="4xx"} 0.1902458849001428 1510039263986
+http_response_timers_DOCUMENT_m1_rate{method="GET",code="4xx"} 0.09447331054820299 1510039263986
+http_response_timers_DOCUMENT_m5_rate{method="GET",code="4xx"} 0.17214159528501158 1510039263986
+http_response_timers_DOCUMENT_mean_rate{method="GET",code="4xx"} 0.019699076069657512 1510039263986
+
+http_response_timers_METRICS_count{method="GET"} 13 1510039263986
+http_response_timers_METRICS_max{method="GET"} 101.0 1510039263986
+http_response_timers_METRICS_mean{method="GET"} 13.66447895963094 1510039263986
+http_response_timers_METRICS_min{method="GET"} 4.0 1510039263986
+http_response_timers_METRICS_p50{method="GET"} 18.0 1510039263986
+http_response_timers_METRICS_p75{method="GET"} 18.0 1510039263986
+http_response_timers_METRICS_p95{method="GET"} 18.0 1510039263986
+http_response_timers_METRICS_p98{method="GET"} 18.0 1510039263986
+http_response_timers_METRICS_p99{method="GET"} 18.0 1510039263986
+http_response_timers_METRICS_p999{method="GET"} 18.0 1510039263986
+http_response_timers_METRICS_stddev{method="GET"} 5.779944201589175 1510039263986
+http_response_timers_METRICS_m15_rate{method="GET"} 0.11197540667244438 1510039263986
+http_response_timers_METRICS_m1_rate{method="GET"} 0.02346856889987903 1510039263986
+http_response_timers_METRICS_m5_rate{method="GET"} 0.040980329912974914 1510039263986
+http_response_timers_METRICS_mean_rate{method="GET"} 0.021582442655335453 1510039263986
+
+http_response_timers_DB_count{method="GET",code="4xx"} 2 1510039263986
+http_response_timers_DB_max{method="GET",code="4xx"} 10.0 1510039263986
+http_response_timers_DB_mean{method="GET",code="4xx"} 8.97000899676118 1510039263986
+http_response_timers_DB_min{method="GET",code="4xx"} 8.0 1510039263986
+http_response_timers_DB_p50{method="GET",code="4xx"} 8.0 1510039263986
+http_response_timers_DB_p75{method="GET",code="4xx"} 10.0 1510039263986
+http_response_timers_DB_p95{method="GET",code="4xx"} 10.0 1510039263986
+http_response_timers_DB_p98{method="GET",code="4xx"} 10.0 1510039263986
+http_response_timers_DB_p99{method="GET",code="4xx"} 10.0 1510039263986
+http_response_timers_DB_p999{method="GET",code="4xx"} 10.0 1510039263986
+http_response_timers_DB_stddev{method="GET",code="4xx"} 0.99955016868826 1510039263986
+http_response_timers_DB_m15_rate{method="GET",code="4xx"} 0.23206560286490113 1510039263986
+http_response_timers_DB_m1_rate{method="GET",code="4xx"} 1.1358519356130308E-4 1510039263986
+http_response_timers_DB_m5_rate{method="GET",code="4xx"} 0.07811102513427433 1510039263986
+http_response_timers_DB_mean_rate{method="GET",code="4xx"} 0.004003171495603914 1510039263986
+
+http_response_timers_COLLECTION_count{method="GET",code="404"} 2 1510039263986
+http_response_timers_COLLECTION_max{method="GET",code="404"} 22.0 1510039263986
+http_response_timers_COLLECTION_mean{method="GET",code="404"} 15.965442805585523 1510039263986
+http_response_timers_COLLECTION_min{method="GET",code="404"} 11.0 1510039263986
+http_response_timers_COLLECTION_p50{method="GET",code="404"} 11.0 1510039263986
+http_response_timers_COLLECTION_p75{method="GET",code="404"} 22.0 1510039263986
+http_response_timers_COLLECTION_p95{method="GET",code="404"} 22.0 1510039263986
+http_response_timers_COLLECTION_p98{method="GET",code="404"} 22.0 1510039263986
+http_response_timers_COLLECTION_p99{method="GET",code="404"} 22.0 1510039263986
+http_response_timers_COLLECTION_p999{method="GET",code="404"} 22.0 1510039263986
+http_response_timers_COLLECTION_stddev{method="GET",code="404"} 5.473960961305782 1510039263986
+http_response_timers_COLLECTION_m15_rate{method="GET",code="404"} 0.11603638270096507 1510039263986
+http_response_timers_COLLECTION_m1_rate{method="GET",code="404"} 5.718721810339868E-5 1510039263986
+http_response_timers_COLLECTION_m5_rate{method="GET",code="404"} 0.03906636157175893 1510039263986
+http_response_timers_COLLECTION_mean_rate{method="GET",code="404"} 0.0039626643164382205 1510039263986
+
+http_response_timers_DB_count{method="GET"} 2 1510039263986
+http_response_timers_DB_max{method="GET"} 10.0 1510039263986
+http_response_timers_DB_mean{method="GET"} 8.97000899676118 1510039263986
+http_response_timers_DB_min{method="GET"} 8.0 1510039263986
+http_response_timers_DB_p50{method="GET"} 8.0 1510039263986
+http_response_timers_DB_p75{method="GET"} 10.0 1510039263986
+http_response_timers_DB_p95{method="GET"} 10.0 1510039263986
+http_response_timers_DB_p98{method="GET"} 10.0 1510039263986
+http_response_timers_DB_p99{method="GET"} 10.0 1510039263986
+http_response_timers_DB_p999{method="GET"} 10.0 1510039263986
+http_response_timers_DB_stddev{method="GET"} 0.99955016868826 1510039263986
+http_response_timers_DB_m15_rate{method="GET"} 0.23206560286490113 1510039263986
+http_response_timers_DB_m1_rate{method="GET"} 1.1358519356130308E-4 1510039263986
+http_response_timers_DB_m5_rate{method="GET"} 0.07811102513427433 1510039263986
+http_response_timers_DB_mean_rate{method="GET"} 0.004003171129199612 1510039263986
+
+http_response_timers_DB_count{method="GET",code="404"} 2 1510039263986
+http_response_timers_DB_max{method="GET",code="404"} 10.0 1510039263986
+http_response_timers_DB_mean{method="GET",code="404"} 8.97000899676118 1510039263986
+http_response_timers_DB_min{method="GET",code="404"} 8.0 1510039263986
+http_response_timers_DB_p50{method="GET",code="404"} 8.0 1510039263986
+http_response_timers_DB_p75{method="GET",code="404"} 10.0 1510039263986
+http_response_timers_DB_p95{method="GET",code="404"} 10.0 1510039263986
+http_response_timers_DB_p98{method="GET",code="404"} 10.0 1510039263986
+http_response_timers_DB_p99{method="GET",code="404"} 10.0 1510039263986
+http_response_timers_DB_p999{method="GET",code="404"} 10.0 1510039263986
+http_response_timers_DB_stddev{method="GET",code="404"} 0.99955016868826 1510039263986
+http_response_timers_DB_m15_rate{method="GET",code="404"} 0.23206560286490113 1510039263986
+http_response_timers_DB_m1_rate{method="GET",code="404"} 1.1358519356130308E-4 1510039263986
+http_response_timers_DB_m5_rate{method="GET",code="404"} 0.07811102513427433 1510039263986
+http_response_timers_DB_mean_rate{method="GET",code="404"} 0.0040031714981198984 1510039263986
+
+http_response_timers_COLLECTION_count{method="GET",code="4xx"} 2 1510039263986
+http_response_timers_COLLECTION_max{method="GET",code="4xx"} 22.0 1510039263986
+http_response_timers_COLLECTION_mean{method="GET",code="4xx"} 15.965442805585523 1510039263986
+http_response_timers_COLLECTION_min{method="GET",code="4xx"} 11.0 1510039263986
+http_response_timers_COLLECTION_p50{method="GET",code="4xx"} 11.0 1510039263986
+http_response_timers_COLLECTION_p75{method="GET",code="4xx"} 22.0 1510039263986
+http_response_timers_COLLECTION_p95{method="GET",code="4xx"} 22.0 1510039263986
+http_response_timers_COLLECTION_p98{method="GET",code="4xx"} 22.0 1510039263986
+http_response_timers_COLLECTION_p99{method="GET",code="4xx"} 22.0 1510039263986
+http_response_timers_COLLECTION_p999{method="GET",code="4xx"} 22.0 1510039263986
+http_response_timers_COLLECTION_stddev{method="GET",code="4xx"} 5.473960961305782 1510039263986
+http_response_timers_COLLECTION_m15_rate{method="GET",code="4xx"} 0.11603638270096507 1510039263986
+http_response_timers_COLLECTION_m1_rate{method="GET",code="4xx"} 5.718721810339868E-5 1510039263986
+http_response_timers_COLLECTION_m5_rate{method="GET",code="4xx"} 0.03906636157175893 1510039263986
+http_response_timers_COLLECTION_mean_rate{method="GET",code="4xx"} 0.003962664528990094 1510039263986
+
+http_response_timers_COLLECTION_count{method="GET"} 2 1510039263986
+http_response_timers_COLLECTION_max{method="GET"} 22.0 1510039263986
+http_response_timers_COLLECTION_mean{method="GET"} 15.965442805585523 1510039263986
+http_response_timers_COLLECTION_min{method="GET"} 11.0 1510039263986
+http_response_timers_COLLECTION_p50{method="GET"} 11.0 1510039263986
+http_response_timers_COLLECTION_p75{method="GET"} 22.0 1510039263986
+http_response_timers_COLLECTION_p95{method="GET"} 22.0 1510039263986
+http_response_timers_COLLECTION_p98{method="GET"} 22.0 1510039263986
+http_response_timers_COLLECTION_p99{method="GET"} 22.0 1510039263986
+http_response_timers_COLLECTION_p999{method="GET"} 22.0 1510039263986
+http_response_timers_COLLECTION_stddev{method="GET"} 5.473960961305782 1510039263986
+http_response_timers_COLLECTION_m15_rate{method="GET"} 0.11603638270096507 1510039263986
+http_response_timers_COLLECTION_m1_rate{method="GET"} 5.718721810339868E-5 1510039263986
+http_response_timers_COLLECTION_m5_rate{method="GET"} 0.03906636157175893 1510039263986
+http_response_timers_COLLECTION_mean_rate{method="GET"} 0.003962663999950156 1510039263986
+
+http_response_timers_DOCUMENT_count{method="GET"} 1 1510039263986
+http_response_timers_DOCUMENT_max{method="GET"} 12.0 1510039263986
+http_response_timers_DOCUMENT_mean{method="GET"} 12.0 1510039263986
+http_response_timers_DOCUMENT_min{method="GET"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p50{method="GET"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p75{method="GET"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p95{method="GET"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p98{method="GET"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p99{method="GET"} 12.0 1510039263986
+http_response_timers_DOCUMENT_p999{method="GET"} 12.0 1510039263986
+http_response_timers_DOCUMENT_stddev{method="GET"} 0.0 1510039263986
+http_response_timers_DOCUMENT_m15_rate{method="GET"} 0.1902458849001428 1510039263986
+http_response_timers_DOCUMENT_m1_rate{method="GET"} 0.09447331054820299 1510039263986
+http_response_timers_DOCUMENT_m5_rate{method="GET"} 0.17214159528501158 1510039263986
+http_response_timers_DOCUMENT_mean_rate{method="GET"} 0.019699022734163196 1510039263986
+```
+
+**JSON example response**
+
+
+```
+{
+ "version": "3.0.0",
+ "gauges": {},
+ "counters": {},
+ "histograms": {},
+ "meters": {},
+ "timers": {
+ "METRICS.GET.2xx": {
+ "count": 11,
+ "max": 101,
+ "mean": 15.944381818716298,
+ "min": 4,
+ "p50": 14,
+ "p75": 18,
+ "p95": 18,
+ "p98": 18,
+ "p99": 21,
+ "p999": 101,
+ "stddev": 5.052944160882624,
+ "m15_rate": 0.1154439183453834,
+ "m1_rate": 0.0011557077668897736,
+ "m5_rate": 0.04047387926642257,
+ "mean_rate": 0.019742700780046633,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "METRICS.GET.200": {
+ "count": 11,
+ "max": 101,
+ "mean": 15.944381818716298,
+ "min": 4,
+ "p50": 14,
+ "p75": 18,
+ "p95": 18,
+ "p98": 18,
+ "p99": 21,
+ "p999": 101,
+ "stddev": 5.052944160882624,
+ "m15_rate": 0.1154439183453834,
+ "m1_rate": 0.0011557077668897736,
+ "m5_rate": 0.04047387926642257,
+ "mean_rate": 0.019742702972526945,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "DOCUMENT.GET.404": {
+ "count": 1,
+ "max": 12,
+ "mean": 12,
+ "min": 12,
+ "p50": 12,
+ "p75": 12,
+ "p95": 12,
+ "p98": 12,
+ "p99": 12,
+ "p999": 12,
+ "stddev": 0,
+ "m15_rate": 0.2,
+ "m1_rate": 0.2,
+ "m5_rate": 0.2,
+ "mean_rate": 0.17884100839774422,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "DOCUMENT.GET.4xx": {
+ "count": 1,
+ "max": 12,
+ "mean": 12,
+ "min": 12,
+ "p50": 12,
+ "p75": 12,
+ "p95": 12,
+ "p98": 12,
+ "p99": 12,
+ "p999": 12,
+ "stddev": 0,
+ "m15_rate": 0.2,
+ "m1_rate": 0.2,
+ "m5_rate": 0.2,
+ "mean_rate": 0.17884385317337576,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "METRICS.GET": {
+ "count": 11,
+ "max": 101,
+ "mean": 15.944381818716298,
+ "min": 4,
+ "p50": 14,
+ "p75": 18,
+ "p95": 18,
+ "p98": 18,
+ "p99": 21,
+ "p999": 101,
+ "stddev": 5.052944160882624,
+ "m15_rate": 0.1154439183453834,
+ "m1_rate": 0.0011557077668897736,
+ "m5_rate": 0.04047387926642257,
+ "mean_rate": 0.019742660741986995,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "DB.GET.4xx": {
+ "count": 2,
+ "max": 10,
+ "mean": 8.97000899676118,
+ "min": 8,
+ "p50": 8,
+ "p75": 10,
+ "p95": 10,
+ "p98": 10,
+ "p99": 10,
+ "p999": 10,
+ "stddev": 0.99955016868826,
+ "m15_rate": 0.24396386075494766,
+ "m1_rate": 0.0002404598566562324,
+ "m5_rate": 0.0907520637356095,
+ "mean_rate": 0.004401101980577996,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "COLLECTION.GET.404": {
+ "count": 2,
+ "max": 22,
+ "mean": 15.965442805585523,
+ "min": 11,
+ "p50": 11,
+ "p75": 22,
+ "p95": 22,
+ "p98": 22,
+ "p99": 22,
+ "p999": 22,
+ "stddev": 5.473960961305782,
+ "m15_rate": 0.12198569526155147,
+ "m1_rate": 0.00012106534167492762,
+ "m5_rate": 0.04538863661287383,
+ "mean_rate": 0.004352188986310938,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "DB.GET": {
+ "count": 2,
+ "max": 10,
+ "mean": 8.97000899676118,
+ "min": 8,
+ "p50": 8,
+ "p75": 10,
+ "p95": 10,
+ "p98": 10,
+ "p99": 10,
+ "p999": 10,
+ "stddev": 0.99955016868826,
+ "m15_rate": 0.24396386075494766,
+ "m1_rate": 0.0002404598566562324,
+ "m5_rate": 0.0907520637356095,
+ "mean_rate": 0.004401100970351595,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "DB.GET.404": {
+ "count": 2,
+ "max": 10,
+ "mean": 8.97000899676118,
+ "min": 8,
+ "p50": 8,
+ "p75": 10,
+ "p95": 10,
+ "p98": 10,
+ "p99": 10,
+ "p999": 10,
+ "stddev": 0.99955016868826,
+ "m15_rate": 0.24396386075494766,
+ "m1_rate": 0.0002404598566562324,
+ "m5_rate": 0.0907520637356095,
+ "mean_rate": 0.004401101777845054,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "COLLECTION.GET.4xx": {
+ "count": 2,
+ "max": 22,
+ "mean": 15.965442805585523,
+ "min": 11,
+ "p50": 11,
+ "p75": 22,
+ "p95": 22,
+ "p98": 22,
+ "p99": 22,
+ "p999": 22,
+ "stddev": 5.473960961305782,
+ "m15_rate": 0.12198569526155147,
+ "m1_rate": 0.00012106534167492762,
+ "m5_rate": 0.04538863661287383,
+ "mean_rate": 0.004352189636138756,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "COLLECTION.GET": {
+ "count": 2,
+ "max": 22,
+ "mean": 15.965442805585523,
+ "min": 11,
+ "p50": 11,
+ "p75": 22,
+ "p95": 22,
+ "p98": 22,
+ "p99": 22,
+ "p999": 22,
+ "stddev": 5.473960961305782,
+ "m15_rate": 0.12198569526155147,
+ "m1_rate": 0.00012106534167492762,
+ "m5_rate": 0.04538863661287383,
+ "mean_rate": 0.004352188004333907,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ },
+ "DOCUMENT.GET": {
+ "count": 1,
+ "max": 12,
+ "mean": 12,
+ "min": 12,
+ "p50": 12,
+ "p75": 12,
+ "p95": 12,
+ "p98": 12,
+ "p99": 12,
+ "p999": 12,
+ "stddev": 0,
+ "m15_rate": 0.2,
+ "m1_rate": 0.2,
+ "m5_rate": 0.2,
+ "mean_rate": 0.1788374724008199,
+ "duration_units": "milliseconds",
+ "rate_units": "calls/second"
+ }
+ }
+}
+```
+
+## Prometheus root metrics
+
+The Prometheus metrics requested on endpoint `/ _metrics` collected all metrics.
+To distinguish metrics per database and collection there are the prometheus labels `database` and
+`collection` containing the corresponding database and collection names.
+
+The following example demonstrates the label values requesting `/_metrics` using
+the prometheus format. The data contains an existing database named mydatabase
+including a single collection named mycollection. All aggregated metrics contain the
+value \_all\_, i.e. metrics for database mydatabase and all contained collections,
+which is equivalent to requesting `/mydatabase/_metrics`.
+
+The prometheus metrics look as follows:
+
+
+```
+http_response_timers_count{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 3 1510039263986
+http_response_timers_max{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_mean{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 5.666666666666666 1510039263986
+http_response_timers_min{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 2.0 1510039263986
+http_response_timers_p50{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 5.0 1510039263986
+http_response_timers_p75{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p95{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p98{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p99{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p999{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_stddev{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 3.299831645537221 1510039263986
+http_response_timers_m15_rate{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 0.0 1510039263986
+http_response_timers_m1_rate{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 0.0 1510039263986
+http_response_timers_m5_rate{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 0.0 1510039263986
+http_response_timers_mean_rate{database="_all_",collection="_all_",type="requests",method="GET",code="2xx"} 0.019699022734163196 1510039263986
+
+http_response_timers_count{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 2 1510039263986
+http_response_timers_max{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_mean{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 7.5 1510039263986
+http_response_timers_min{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 5.0 1510039263986
+http_response_timers_p50{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p75{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p95{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p98{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p99{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p999{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_stddev{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 2.5 1510039263986
+http_response_timers_m15_rate{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 0.0 1510039263986
+http_response_timers_m1_rate{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 0.0 1510039263986
+http_response_timers_m5_rate{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 0.0 1510039263986
+http_response_timers_mean_rate{database="mydatabase",collection="_all_",type="requests",method="GET",code="2xx"} 0.019699022734163196 1510039263986
+
+http_response_timers_count{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 1 1510039263986
+http_response_timers_max{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_mean{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_min{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p50{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p75{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p95{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p98{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p99{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_p999{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 10.0 1510039263986
+http_response_timers_stddev{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 0.0 1510039263986
+http_response_timers_m15_rate{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 0.0 1510039263986
+http_response_timers_m1_rate{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 0.0 1510039263986
+http_response_timers_m5_rate{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 0.0 1510039263986
+http_response_timers_mean_rate{database="mydatabase",collection="mycollection",type="requests",method="GET",code="2xx"} 0.019699022734163196 1510039263986
+```
+
+Prometheus metrics requested for `/mydatabase/_metrics` or
+`/mydatabase/mycollection/_metrics` do not contain this labels.
+
+In case of using prometheus it's recommended to only use the
+single endpoint `/_metrics`, allowing to scrape all metrics at
+once and do filtering based on label values.
+
+DEPRECATED
++ Beginning with version 7.5, this has been marked as deprecated and substituted with the all-encompassing Monitoring feature. +
++ CAUTION: It is scheduled for removal in RESTHeart v8.0. +
+
+
+- [Introduction](#introduction)
+- [The rels collection metadata](#the-rels-collection-metadata)
+- [Examples](#examples)
+ - [Tree of documents](#tree-of-documents)
+ - [One-to-Many, owning](#one-to-many-owning)
+ - [One-to-Many, inverse](#one-to-many-inverse)
+
+
+
+
+{% include docs-head.html %}
+
+## Introduction
+
+In MongoDB, documents can have relationships with other documents (see
+MongoDB [Relationships](https://docs.mongodb.org/master/applications/data-models-relationships/)
+documentation section).
+
+**RESTHeart allows to declare the existing relationships in a
+collection, so that it automatically adds the links to related documents
+in its representation.**
+
+{: bs-callout.bs-callout-info}
+Declaring relationships adds the `_links` property to the documents only in the HAL representation format. This is not available in the default representation format. Add the query parameters `?rep=HAL&hal=f` to display the `_links` property.
+
+## The _rels_ collection metadata
+
+In RESTHeart, not only documents but also dbs and collections have
+properties. Some properties are metadata, i.e. they have a special
+meaning for RESTheart that influences its behavior.
+
+The collection metadata `rels` allows to declare existing
+relationship so that links to the referenced documents are auto-magically included in the `_link` property
+
+`rels` is an array of `rel` objects having the following format:
+
+```json
+{
+ "rel": "",
+ "type": "",
+ "role": "",
+ "target-db": "",
+ "target-coll": "",
+ "ref-field": ""
+}
+```
+
+
diff --git a/docs/v7/mongodb-rest/representation-format.md b/docs/v7/mongodb-rest/representation-format.md
new file mode 100644
index 00000000..7f73e0d3
--- /dev/null
+++ b/docs/v7/mongodb-rest/representation-format.md
@@ -0,0 +1,538 @@
+---
+title: Representation Format
+layout: docs
+menu: mongodb
+---
+
+
+
+
+
+
+## Examples
+
+### Tree of documents
+
+In this example, we create a collection to store documents organized in
+a tree (each document has a single parent document).
+
+Let's create a collection, declaring a **many-to-one** relationship
+called **`parent`**, so that documents can refer a _parent document_ in
+the collection itself.
+
+```http
+PUT /parentcoll HTTP/1.1
+
+{
+ "rels": [
+ {
+ "rel": "parent",
+ "type": "MANY_TO_ONE",
+ "role": "OWNING",
+ "target-coll": "parentcoll",
+ "ref-field": "parent"
+ }
+ ]
+}
+
+HTTP/1.1 201 CREATED
+```
+
+Let's now create few documents, specifying the `parent` property:
+
+```http
+PUT /parentcoll/root HTTP/1.1
+
+{"parent":"root"}
+
+HTTP/1.1 201 CREATED
+```
+
+```http
+PUT /parentcoll/1 HTTP/1.1
+
+{"parent":"root"}
+
+HTTP/1.1 201 CREATED
+```
+
+```http
+PUT /parentcoll/1.1 HTTP/1.1
+
+{"parent":"1"}
+
+HTTP/1.1 201 CREATED
+```
+
+```http
+PUT /parentcoll/1.2 HTTP/1.1
+
+{"parent":"1"}
+
+HTTP/1.1 201 CREATED
+```
+
+If we now get the document `/parentcoll/1.2`, the `_links` property
+includes `parent` with the correct URI of the
+document `/parentcoll/1`
+
+```http
+GET /test/parentcoll/1.2 HTTP/1.1
+
+HTTP/1.1 200 OK
+{
+ "_id": "1.2",
+ "parent": 1,
+ "_links": {
+ "parent": {
+ "href": "/parentcoll/1"
+ }
+ }
+}
+```
+
+### One-to-Many, owning
+
+In this example, we create two collections: `bands` and `albums`; of
+course, each band has a **1:N** relationship to albums.
+
+```http
+PUT /bands HTTP/1.1
+
+{
+ "rels": [{
+ "rel": "albums",
+ "type": "ONE_TO_MANY",
+ "role": "OWNING",
+ "target-coll": "albums",
+ "ref-field": "albums"
+ }],
+ "descr": "music bands"
+}
+
+HTTP/1.1 201 CREATED
+```
+
+```http
+PUT /albums HTTP/1.1
+
+{ "descr":"albums published by music bands" }
+
+HTTP/1.1 201 CREATED
+```
+
+Let's now create few albums:
+
+```http
+PUT /albums/Disintegration HTTP/1.1
+
+{"year":1989}
+
+HTTP/1.1 201 CREATED
+```
+
+```http
+PUT /albums/Wish HTTP/1.1
+
+{"year":1992}
+
+HTTP/1.1 201 CREATED
+```
+
+```http
+PUT /albums/Bloodflowers HTTP/1.1
+
+{"year":2000}
+
+HTTP/1.1 201 CREATED
+```
+
+Now we create the band referring these albums:
+
+```http
+PUT /bands/The%20Cure HTTP/1.1
+
+{"albums":["Disintegration","Wish","Bloodflowers"]}
+
+HTTP/1.1 201 CREATED
+```
+
+If we now get The Cure document, we can notice the `albums` link: `/albums?filter={'_id':{'$in':['Disintegration','Wish','Bloodflowers']}}"`
+
+Since the other side of the relationship has cardinality N, the `albums`
+link is a collection resource URI with a **filter query parameter**.
+
+```http
+GET /bands/The%20Cure HTTP/1.1
+
+HTTP/1.1 200 OK
+{
+ "_id": "The Cure",
+ "_links": {
+ "albums": {
+ "href": "/albums?filter={'_id':{'$in':['Disintegration','Wish','Bloodflowers']}}"
+ },
+ },
+ "albums": [
+ "Disintegration",
+ "Wish",
+ "Bloodflowers"
+ ]
+}
+```
+
+If we want to get the referenced document with httpie (or curl) we need
+to issue the following request:
+
+```http
+GET /albums?filter="{'_id':{'$in':['Disintegration','Wish','Bloodflowers']}}"` HTTP/1.1
+```
+
+### One-to-Many, inverse
+
+We'll resemble the previous example, but using an inverse relationship,
+i.e. the field storing the relationship will be stored in the album
+documents.
+
+```http
+PUT /bandsi HTTP/1.1
+
+{
+ "rels": [
+ {
+ "rel": "albums",
+ "type": "ONE_TO_MANY",
+ "role": "INVERSE",
+ "target-coll": "albums",
+ "ref-field": "band"
+ }
+ ],
+ "descr": "music bands"
+}
+
+HTTP/1.1 201 CREATED
+```
+
+```http
+PUT /albumsi HTTP/1.1
+
+{ "descr":"albums published by music bands" }
+
+HTTP/1.1 201 CREATED
+```
+
+Let's now create few albums:
+
+```http
+PUT /albumsi/Disintegration HTTP/1.1
+
+{ "year":1989, "band":"The Cure" }
+
+HTTP/1.1 201 CREATED
+```
+
+```http
+PUT /albumsi/Wish HTTP/1.1
+
+{ "year":1992, "band":"The Cure" }
+
+HTTP/1.1 201 CREATED
+```
+
+```http
+PUT /test/albumsi/Bloodflowers HTTP/1.1
+
+{ "year":2000, "band":"The Cure" }
+
+HTTP/1.1 201 CREATED
+```
+
+Now we create the band referred by these albums:
+
+```http
+PUT /bandsi/The%20Cure HTTP/1.1
+
+{"descr":"The Cure are an English rock band formed in Crawley, West Sussex, in 1976"}
+
+HTTP/1.1 201 CREATED
+```
+
+If we now get "The Cure" document, we can notice the `albums` link: `/albumsi?filter={'band':'The Cure'}`
+
+```http
+GET /test/bandsi/The%20Cure HTTP/1.1
+
+HTTP/1.1 200 OK
+
+{
+ "_id": "The Cure",
+ "_links": {
+ "albums": {
+ "href": "/test/albums?filter={'band':'The Cure'}"
+ }
+ },
+ "descr": "The Cure are an English rock band formed in Crawley, West Sussex, in 1976"
+}
+```
+
+
+Property
+ |
+
+Description
+ |
+
+Mandatory
+ |
+
|---|---|---|
rel |
+Name of the relationship. |
+Yes | +
type |
+Type of relationship: ONE_TO_ONE, MANY_TO_ONE, ONE_TO_MANY or MANY_TO_MANY | +Yes | +
role |
+Role of the relationship: OWNING or INVERSE. This says where the reference field is. OWNING means it is in this document, INVERSE means that it is on the target document. | +Yes | +
target-db |
+Database name of the referenced document(s) | +No. If omitted the target db is supposed to be the current one |
+
target-coll |
+Collection's name of the referenced document(s) | +Yes | +
ref-field |
+Name of the first level field storing the id(s) of the referenced document(s) or the json path expression that resolves to the ids of the referenced documents (to reference nested fields). +The value of the first level field must be either the id string (in case the multiplicity of other side of the relationship is ONE) or an array of id strings (in case the multiplicity of other side of the relationship is MANY) +Note: json path expression must start with
|
+Yes | +
+
+- [Representation Format](#representation-format)
+ - [BSON types](#bson-types)
+ - [Json Mode](#json-mode)
+- [Other representation formats](#other-representation-formats)
+ - [HAL](#hal)
+ - [Simplified HAL](#simplified-hal)
+
+
+
+
+{% include docs-head.html %}
+
+The following table summarizes how resources are represented
+
+{: .table }
+|resource|represented as|example|
+|-|-|-|
+|root `/`|paginated array of existing db names|`["db1", "db2"]`|
+|db `/`|paginated array of collection/buckets names that exist in the db|`["collection1", "file.bucket"]`|
+|collection `/`|paginated array of documents of the collection|`[ {"_id": "doc1, "foo": "bar" }, {"_id": "doc2, "foo": "bar" } ]`|
+|document|JSON object|`{"_id": "doc1, "foo": "bar" }`
+
+### BSON types
+
+MongoDB uses the [BSON](https://en.wikipedia.org/wiki/BSON) data format
+which type system is a superset of JSON’s. To preserve type information,
+MongoDB adds this extension to the JSON.
+
+For instance, the `_id` of the following JSON document is an ObjectId.
+
+```json
+ {
+ "_id": {
+ "$oid": "5d0b4e325beb2029a8d1bd5e"
+ },
+ "item": "paper"
+
+ ...
+ }
+```
+
+{: .bs-callout.bs-callout-info }
+The strict mode is used on both request and response resource representation and also on the query parameter `filter`
+
+The following `filter` won’t find the document since the `_id` is an ObjectId (and not a String).
+
+{% include code-header.html
+ type="Request"
+%}
+
+```http
+GET /inventory?filter={'_id':'5d0b4e325beb2029a8d1bd5e'} HTTP/1.1
+```
+
+The correct request is:
+
+{% include code-header.html
+ type="Request"
+%}
+
+```http
+GET /inventory?filter={'_id':{'$oid':'5d0b4e325beb2029a8d1bd5e'}} HTTP/1.1
+```
+
+### JSON Mode
+
+JSON can only directly represent a subset of the types supported by BSON. To preserve type information, RESTHeart adds the following extensions to the JSON format.
+
+The query parameter `jsonMode` allows to specify the JSON Mode
+
+{: .table}
+|jsonMode|Description|
+|-|-|
+|none|Standard RESTHeart representation|
+|STRICT|JSON representation with type information for specific cases|
+|EXTENDED|Extended JSON representation with full type information|
+|RELAXED|Standard relaxed extended JSON representation|
+|SHELL|This output mode will attempt to produce output that corresponds to what the MongoDB shell actually produces when showing query results|
+
+#### Standard RESTHeart representation
+
+```http
+GET locahost:8080/coll/5d7a4b59cf6eeb5fb1686613 HTTP/1.1
+
+{
+ "_etag": {
+ "$oid": "5d7a4f10af0e1b77a7731d05"
+ },
+ "_id": {
+ "$oid": "5d7a4b59cf6eeb5fb1686613"
+ },
+ "a": 1,
+ "b": 1.0,
+ "big": 1568295769260,
+ "timestamp": {
+ "$date": 1568295769260
+ }
+}
+```
+
+#### Strict representation
+
+```http
+GET locahost:8080/coll/5d7a4b59cf6eeb5fb1686613?jsonMode=strict HTTP/1.1
+
+HTTP/1.1 200 OK
+
+{
+ "_etag": {
+ "$oid": "5d7a4f10af0e1b77a7731d05"
+ },
+ "_id": {
+ "$oid": "5d7a4b59cf6eeb5fb1686613"
+ },
+ "a": 1,
+ "b": 1.0,
+ "big": {
+ "$numberLong": "1568295769260"
+ },
+ "timestamp": {
+ "$date": 1568295769260
+ }
+}
+```
+
+#### Extended representation
+
+```http
+GET locahost:8080/coll/5d7a4b59cf6eeb5fb1686613?jsonMode=extended HTTP/1.1
+
+HTTP/1.1 200 OK
+
+{
+ "_etag": {
+ "$oid": "5d7a4f10af0e1b77a7731d05"
+ },
+ "_id": {
+ "$oid": "5d7a4b59cf6eeb5fb1686613"
+ },
+ "a": {
+ "$numberInt": "1"
+ },
+ "b": {
+ "$numberDouble": "1.0"
+ },
+ "big": {
+ "$numberLong": "1568295769260"
+ },
+ "timestamp": {
+ "$date": {
+ "$numberLong": "1568295769260"
+ }
+ }
+}
+```
+
+#### Relaxed representation
+
+```http
+GET locahost:8080/coll/5d7a4b59cf6eeb5fb1686613?jsonMode=relaxed HTTP/1.1
+
+HTTP/1.1 200 OK
+
+{
+ "_etag": {
+ "$oid": "5d7a6c61bd8a0d69516bbf55"
+ },
+ "_id": {
+ "$oid": "5d7a4b59cf6eeb5fb1686613"
+ },
+ "a": 1,
+ "b": 1.0,
+ "big": 1568295769260,
+ "timestamp": {
+ "$date": "2019-09-12T13:42:49.26Z"
+ }
+}
+```
+
+#### Shell representation
+
+{: .bs-callout.bs-callout-success }
+SHELL JSON Mode is very useful since it **allows to use the response body directly in the mongoshell!**
+
+```http
+GET locahost:8080/coll/5d7a4b59cf6eeb5fb1686613?jsonMode=shell HTTP/1.1
+
+HTTP/1.1 200 OK
+
+Content-Type: application/javascript
+
+{"_id":ObjectId("5d7a4b59cf6eeb5fb1686613"),"_etag":ObjectId("5d7a6d13bd8a0d69516bbf56"),"timestamp":ISODate("2019-09-12T13:42:49.260Z"),"a":1,"b":1.0,"big":NumberLong("1568295769260"),"verybig":NumberLong("5887391606")}
+```
+
+## Other representation formats
+
+RESTHeart has different options for representing the resources: `STANDARD`, `HAL` and `SHAL` (Simplified HAL).
+
+{: .bs-callout.bs-callout-warning }
+`HAL` and `SHAL` are deprecated in version 6.0 and will likely be removed in a future release.
+
+The default representation can be controlled by the configuration option `default-representation-format` .
+
+```properties
+default-representation-format: STANDARD
+```
+
+The `rep` query parameter can also be used for switching between representations.
+
+```http
+GET /inventory?rep=s HTTP/1.1
+```
+
+```http
+GET /inventory?rep=hal HTTP/1.1
+```
+
+```http
+GET /inventory?rep=shal HTTP/1.1
+```
+
+### HAL
+
+[HAL](http://stateless.co/hal_specification.html) up on 2 simple concepts: **Resources** and **Links**
+
+- **Resources** have state (plain JSON), embedded resources and links
+- **Links** have target (href URI) and relations (aka rel)
+
+{: width="800" height="600" class="img-responsive"}
+
+#### Example
+
+We’ll get the `inventory` collection resource and analyze it.
+A collection represented with `HAL` has its own _properties_, *embedded resources* (in this case, documents) and _link templates_ (for pagination, sorting, etc).
+
+{% include code-header.html
+ type="Request"
+%}
+
+```http
+GET /inventory?rep=hal HTTP/1.1
+```
+
+{% include code-header.html
+ type="Response"
+%}
+
+```http
+HTTP/1.1 200 OK
+
+Access-Control-Allow-Credentials: true
+Access-Control-Allow-Origin: *
+Access-Control-Expose-Headers: Location, ETag, X-Powered-By
+Connection: keep-alive
+Content-Encoding: gzip
+Content-Length: 384
+Content-Type: application/hal+json
+Date: Mon, 08 Jul 2019 12:56:14 GMT
+ETag: 5d233840dd860b259a3bad45
+X-Powered-By: restheart.org
+
+{
+ "_id":"inventory",
+ "_etag":{
+ "$oid":"5d233840dd860b259a3bad45"
+ },
+ "metadata_field": "metadata_value",
+ "_returned": 6,
+ "_embedded":{
+ "rh:doc":[
+ {
+ "_id":{
+ "$oid":"5d233aeb93dc53162739e172"
+ },
+ "_etag":{
+ "$oid":"5d233aeb93dc53162739e16d"
+ },
+ "item":"postcard",
+ "qty":45,
+ "size":{
+ "h":10,
+ "w":15.25,
+ "uom":"cm"
+ },
+ "status":"A"
+ },
+ ...
+ ]
+ }
+}
+```
+
+#### Properties
+
+In this case, the collection properties comprise the field *metadata_field*; this
+is user defined.
+
+The other fields are reserved properties (i.e. are managed automatically
+by RESTHeart for you); these always starts with \_:
+
+{: .table }
+| Property | Description |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| `_type` | the type of this resource. in this case ‘COLLECTION’ (only returned on HAL full mode) |
+| `_id` | the name of the collection |
+| `_etag` | entity tag, used for caching and to avoid ghost writes. |
+| `_returned` | the number of the documents embedded in this representation |
+
+#### Documents as embedded resources
+
+Collection's embedded resources are the collection documents,
+recursively represented as HAL documents.
+
+The `_embedded` property looks like:
+
+```json
+{
+ "_embedded": {
+ "rh:doc": [
+ {
+ "_id": {
+ "$oid": "5d233aeb93dc53162739e172"
+ },
+ "_etag": {
+ "$oid": "5d233aeb93dc53162739e16d"
+ },
+ "item": "postcard",
+ "qty": 45,
+ "size": {
+ "h": 10,
+ "w": 15.25,
+ "uom": "cm"
+ },
+ "status": "A"
+ },
+ {
+ "_id": {
+ "$oid": "5d233aeb93dc53162739e171"
+ },
+ "_etag": {
+ "$oid": "5d233aeb93dc53162739e16d"
+ },
+ "item": "planner",
+ "qty": 75,
+ "size": {
+ "h": 22.85,
+ "w": 30,
+ "uom": "cm"
+ },
+ "status": "D"
+ }
+ ]
+ }
+}
+```
+
+#### Links
+
+
diff --git a/docs/v7/mongodb-rest/resource-uri.md b/docs/v7/mongodb-rest/resource-uri.md
new file mode 100644
index 00000000..6a36ac80
--- /dev/null
+++ b/docs/v7/mongodb-rest/resource-uri.md
@@ -0,0 +1,248 @@
+---
+title: Resource URI
+layout: docs
+menu: mongodb
+---
+
+
+
+
+
+
+
+
+ _links are only returned on hal full mode. The only exception are with
+ relationships. If a collection defines a relationship,
+ the representation of the documents always include the links to related
+ data.
+
+
+
+
+The `_links` property looks like:
+
+```json
+{ "_links": {
+ "self": {
+ "href": "/inventory?hal=f"
+ },
+ "first": {
+ "href": "/inventory?pagesize=100&hal=f"
+ },
+ "next": {
+ "href": "/inventory?page=2&pagesize=100&hal=f"
+ },
+ "rh:coll": {
+ "href": "//{collname}",
+ "templated": true
+ },
+ "rh:document": {
+ "href": "/inventory/{docid}{?id_type}",
+ "templated": true
+ },
+ "rh:indexes": {
+ "href": "/inventory/_indexes"
+ },
+ "rh:filter": {
+ "href": "/inventory{?filter}",
+ "templated": true
+ },
+ "rh:sort": {
+ "href": "/inventory{?sort_by}",
+ "templated": true
+ },
+ "rh:paging": {
+ "href": "/inventory{?page}{&pagesize}",
+ "templated": true
+ }
+}
+```
+
+| Link | +Description | +
|---|---|
self |
+link to itself | +
first |
+link to the first page | +
last |
+link to the last page | +
rh:db |
+templated link for db | +
rh:coll |
+templated link for collection | +
rh:document |
+templated link for document | +
rh:filter |
+templated link for filtering | +
rh:sort |
+templated link for sorting | +
rh:indexes |
+link to the collection indexes resource | +
rh:paging |
+templated link for paging | +
curies |
+(compacts URIes) bind links to documentation. For instance the rh:db rel is documented at https://restheart.org/curies/2.0/db.html |
+
+
+
+#### HAL Mode
+
+The query parameter `hal` controls the verbosity of HAL representation.
+Valid values are `hal=c` (for compact) and `hal=f` (for full); the default value
+(if the param is omitted) is compact mode.
+
+When `hal=f` is specified, the representation is more verbose and includes special properties (such as links).
+
+### Simplified HAL
+
+In the following response the collection /inventory has the properties `_id`, `_etag`, `metadata_field` and two embedded documents and the special property `_returned`
+
+{% include code-header.html
+ type="Request"
+%}
+
+```http
+GET /inventory?rep=shal HTTP/1.1
+```
+
+{% include code-header.html
+ type="Response"
+%}
+
+```http
+HTTP/1.1 200 OK
+
+...
+
+{
+ "_embedded": [
+ {
+ "_id": {
+ "$oid": "5d0b4dff2ec9ff0d92ddc2b7"
+ },
+ "_etag": {
+ "$oid": "5d0b4dff2ec9ff0d92ddc2b2"
+ },
+ "item": "postcard",
+ "qty": 45,
+ "size": {
+ "h": 10,
+ "w": 15.25,
+ "uom": "cm"
+ },
+ "status": "A"
+ }
+ ],
+ "_id": "inventory",
+ "_etag": {
+ "$oid": "5d1e13dbdde87c62e98a4595"
+ },
+ "metadata_field": "metadata_value",
+ "_returned": 6
+}
+```
+
+
+
+* [Introduction](#introduction)
+* [Resources URIs](#resources-uris)
+* [Document id](#document-id)
+ * [Examples](#examples)
+* [URL encoding](#url-encoding)
+
+
+
+
+{% include docs-head.html %}
+
+## Introduction
+
+This page explains the resource URI format, i.e. how the resources
+are identified.
+
+
+
+
diff --git a/docs/v7/mongodb-rest/sample-data.adoc b/docs/v7/mongodb-rest/sample-data.adoc
new file mode 100644
index 00000000..ab2c0db4
--- /dev/null
+++ b/docs/v7/mongodb-rest/sample-data.adoc
@@ -0,0 +1,85 @@
+---
+title: Load Sample Data into MongoDB
+layout: docs-adoc
+menu: mongodb
+sitemap: false
+---
+
+MongoDB provides a sample data set for testing and development.
+
+This section describes how to load it into your MongoDB instance and configure RESTHeart to use it.
+
+== Install the Database tools
+
+You need `mongorestore` that is part of the MongoDB Database Tool.
+
+To install it please refer to link:https://docs.mongodb.com/database-tools/[https://docs.mongodb.com/database-tools]
+
+== Download the sample data
+
+Download the sample data via the curl command:
+
+[source,bash]
+----
+$ curl https://atlas-education.s3.amazonaws.com/sampledata.archive -o sampledata.archive
+----
+
+TIP: The data set is also available at the following address `https://download.restheart.com/sampledata.archive`. DISCLAIMER: the original data set is provided by MongoDB and available at this address only for educational purposes, MongoDB license terms might apply.
+
+== Restore the sample data
+
+Make sure MongoDB is running on `localhost:27017` (this command assumes it is not running with authentication required).
+
+[source,bash]
+----
+$ mongorestore --archive=sampledata.archive
+----
+
+== The sample data
+
+The sample data consist of the following databases:
+
+[source,json]
+----
+[ "sample_airbnb",
+ "sample_analytics",
+ "sample_geospatial",
+ "sample_mflix",
+ "sample_restaurants",
+ "sample_supplies",
+ "sample_training",
+ "sample_weatherdata"
+]
+----
+
+Note that the default configuration of RESTHeart does not expose the sample data. It exposes only the database `restheart`.
+
+You can expose all databases setting the `mongo-mounts` in the `restheart.yml` configuration file as follows:
+
+[source,yml]
+----
+mongo-mounts:
+ - what: "*" # default value is /restheart. "*" means expose all databases
+ where: /
+----
+
+NOTE: With this configuration the URI of a collection is `/
+
+
+## Resources URIs
+
+ Default RESTHeart configuration binds / to the database restheart.
+
+ Being the most general case, the following table refers to the configuration exposing all MongoDB resources (/mongo/mongo-mounts[0]/what->'*')
+
+
+
+
+## Document id
+
+In MongoDB, the \_id can be of any type. For instance, it can be an
+ObjectId, a String or even a JSON object, as in the following document:
+
+
+```
+{ "_id": {"a":1,"b":2} }
+```
+
+RESTHeart needs to be able to assign a unique URI to each document. For
+this reason, only a subset of \_id types are supported.
+
+The following table shows the supported types:
+
+| Resource | +URI | +Notes | +
|---|---|---|
Root |
+/ |
+The root resource is the API entry point. | +
| Database | +/<db> |
+<db> is the database name. |
+
| Database Metadata | +/<db>/_meta |
+Metadata associated to the database named <db>. |
+
| Collection | +/<db>/<coll> |
+<coll> is the collection name. |
+
| Collection Metadata | +/<db>/<coll>/_meta |
+Metadata associated to the collection named <coll>. |
+
| Document | +/<db>/<coll>/<doc_id>[?id_type=TYPE] |
+
|
+
| Bulk Documents | +/<db>/<coll>/*?filter=[filter expression] |
+The wildcard can be used for bulk updates; in this case the filter query parameter is mandatory, see Write Requests. |
+
| Indexes | +/<db>/<coll>/_indexes |
+
|
+
| Index | +/<db>/<coll>/_indexes/<idx_id> |
+
|
+
| File bucket | +/<db>/<bucket>/.files |
+
|
+
| File | +/<db>/<bucket>.files/<file_id>[?id_type=TYPE] |
+
|
+
| Schema Store | +/<db>/<coll>/_schemas |
++ |
| Schema | +/<db>/<coll>/_schemas/<schema_id> |
+<schema_id> is the _id of the schema. |
+
| Aggregation | +/<db>/<coll>/_aggrs/<aggr_name> |
+<aggr_name> is the name of the aggregation (specified in it declaration, see Aggregations). |
+
| Change Stream | +/<db>/<coll>/_streams/<stream_name> |
+<stream_name> is the name of the change stream (specified in it declaration, see Change Streams). |
+
+
+
+
+
+
+
+{: .bs-callout.bs-callout-info }
+**\*** The default value of the id\_type query parameter
+is **STRING\_OID**. In this case, the value of the **<doc_id>** is
+interpreted either as an ObjectId or a String. The former applies if the
+value is a valid ObjectId.
+
+{: .bs-callout.bs-callout-info }
+**\*\*** **STRING** is useful if the \_id value would be a valid
+ObjectId and it is actually a String.
+
+
+### Examples
+
+| type | +id_type | +
|---|---|
| ObjectId | +OID or STRING_OID* | +
| String | +STRING** or STRING_OID* | +
| Number | +NUMBER | +
| Date | +DATE | +
| MinKey | +MINKEY | +
| MaxKey | +MAXKEY | +
| Boolean | +BOOLEAN | +
| null | +NULL | +
+
+
+
+
+
+## URL encoding
+
+If a resource URL contains one or more RFC 3986 reserved characters,
+they must be [percent
+encoded](https://en.wikipedia.org/wiki/Percent-encoding). However most
+of the HTTP client will encode the URL for you, including all the
+browsers. For instance, the URL of the database `my database` is
+actually `https://whatever.org/my%20database`.
+
+**Special attention must be paid with + (plus sign)**. The + sign in the
+query string is URL-decoded to a space! %2B in the query string is
+URL-decoded to a + sign. So the request
+
+`GET /db/coll/a+b` will actually find the document with id "a b". GET
+/db/coll/a%2Bb finds the document with id "a+b"
+
+Have a look at this issue
+/db/coll/1 |
+ { "_id": "1" } |
+
/db/coll/1?id_type=NUMBER |
+ { "_id": 1 } |
+
/db/coll/1?id_type=DATE |
+ { "_id": { "$date": 1} } |
+
/db/coll/54f77f0fc2e6ea386c0752a5 |
+ { "_id": { "$oid": "54f77f0fc2e6ea386c0752a5" } } |
+
/db/coll/54f77f0fc2e6ea386c0752a5?id_type=STRING |
+ { "_id": "54f77f0fc2e6ea386c0752a5" } |
+
+
+{% include docs-head.html %}
+
+{: .bs-callout.bs-callout-info}
+The shard key determines the distribution of the collection’s documents among a cluster’s shards.
+
+When a shared collection has shard key different than \_id or a compound shard key, the `shardkey` query parameter must be used.
+
+Example: if the shard key is `X`
+
+```http
+GET /db/coll/5ac9f95563445900062144aa?shardkey={"X":1} HTTP/1.1
+```
+
+
diff --git a/docs/v7/mongodb-rest/transactions.md b/docs/v7/mongodb-rest/transactions.md
new file mode 100644
index 00000000..27d5d1d3
--- /dev/null
+++ b/docs/v7/mongodb-rest/transactions.md
@@ -0,0 +1,206 @@
+---
+title: Transactions
+layout: docs
+menu: mongodb
+---
+
+
+
+- [Introduction](#introduction)
+- [Sessions](#sessions)
+ - [Start a session](#start-a-session)
+ - [Execute a request in a session](#execute-a-request-in-a-session)
+- [Transactions](#transactions)
+ - [Transaction Status](#transaction-Status)
+ - [Error handling](#error-handling)
+ - [Start the transaction](#start-the-transaction)
+ - [Get the current transaction status](#get-the-current-transaction-status)
+ - [Execute requests in the transaction](#execute-requests-in-the-transaction)
+ - [Commit the transaction](#commit-the-transaction)
+ - [Abort the transaction](#abort-the-transaction)
+
+
+
+
+{% include docs-head.html %}
+
+,
+ "stages": [
+ "",
+ "",
+ ...
+ ]
+ }
+]}
+```
+
+[options="header"]
+[cols="1,3,1"]
+|===
+|Property |Description |Mandatory
+|uri
+|specifies the URI when the stream is bound under the path `///_streams`
+|yes
+|stages
+|the MongoDB aggregation pipeline stages. For more information refer to link:https://docs.mongodb.org/manual/core/aggregation-pipeline/[Aggregation Pipeline] on MongoDb documentation.
+|yes
+|===
+
+NOTE: Stages take as input link:https://docs.mongodb.com/manual/reference/change-events/[Change Events] instead of the documents. For example, the modified version of a document after a `PATCH` request is present at `event.fullDocument` property of the stages input event. (See link:/docs/mongodb-websocket/examples[examples]).
+
+== Optional Stages
+
+The aggregation of the stream can include optional stages. These optional stages are only executed when one or more variables are specified.
+
+NOTE: Optional stages in the Websocket API are available from RESTHeart v7.6
+
+For a more comprehensive understanding of how to use optional stages, please refer to the link:/docs/mongodb-rest/aggregations#optional-stages[Aggregation documentation].
+
+== Escaped stage properties
+
+MongoDB (up to v5) does not allow to store fields with names starting with `$` or
+containing _dots_ (`.`).
+
+To store stages with dollar prefixed operators or use
+the dot notation, RESTHeart _automatically_ and _transparently_ escapes
+the properties keys as follows:
+
+- the `$` prefix is "underscore escaped", e.g. `$exists` is stored as `_$exists`
+- if the dot notation has to be used in a key name, dots are replaced with `::` e.g. `SD.prop` is stored as `SD::prop`
\ No newline at end of file
diff --git a/docs/v7/mongodb-websocket/examples.adoc b/docs/v7/mongodb-websocket/examples.adoc
new file mode 100644
index 00000000..de85741c
--- /dev/null
+++ b/docs/v7/mongodb-websocket/examples.adoc
@@ -0,0 +1,172 @@
+---
+title: Examples of the WebSocket API
+layout: docs-adoc
+menu: mongodb
+---
+
+:page-liquid:
+
+The following requests upsert a collection defining three change streams:
+
+- *all* bound at `/messages/_streams/all`
+- *mine* bound at `/messages/_streams/mine`
+
+++++
+{% include code-header.html type="Request" %}
+++++
+
+[source,http]
+PUT /messages HTTP/1.1
+
+++++
+{% include code-header.html type="Request body" %}
+++++
+[source,json]
+----
+{
+ "streams" : [
+ { "stages" : [
+ {
+ "_$match": {
+ "_$or" : [ { "operationType": "insert" }, { "operationType": "update" } ]
+ }
+ }
+ ],
+ "uri" : "all"
+ },
+ { "stages" : [
+ { "_$match" : { "fullDocument::name" : { "_$var" : "n" } } }
+ ],
+ "uri" : "mine"
+ }
+ ]
+}
+----
+
+Note that the `$match` stage specifies a condition on the `name` property using `fullDocument::name`.
+
+This is because the Change Event looks like:
+
+[source,json]
+----
+{
+ "fullDocument": {
+ "_id": { "$oid": "5e15ff5779ca449eb20fdd09" },
+ "message": "hi uji, how are you?",
+ "name": "uji",
+ "_etag": { "$oid": "5e15ff57a2e5700c3459e801" }
+ },
+ "documentKey": {
+ "_id": { "$oid": "5e15ff5779ca449eb20fdd09" }
+ },
+ "updateDescription": null,
+ "operationType": "insert"
+}
+----
+
+Note between the `_links` collection property the URIs of the
+change streams (returned with `?rep=SHAL`).
+
+++++
+{% include code-header.html type="Request" %}
+++++
+
+[source,http]
+GET /messages?rep=SHAL HTTP/1.1
+
+++++
+{% include code-header.html type="Response" %}
+++++
+
+[source,json]
+----
+{
+ "_links": {
+ "all": {
+ "href": "/messages/_streams/all"
+ },
+ "mine": {
+ "href": "/messages/_streams/mine"
+ }
+ }
+}
+----
+
+Alternatively, we can define a single change stream that either returns all messages or only those sent by a specific `name``. This can be achieved through a definition that utilizes optional stages:
+
+
+[source,json]
+----
+{
+ "streams" : [
+{ "stages" : [
+ { "$ifvar": [ "n", { "_$match" : { "fullDocument::name" : { "_$var" : "n" } } } ] }
+ ],
+ "uri" : "withOptionalStage"
+ }
+ ]
+}
+----
+
+To subscribe to the change streams, we will use `websocat`, a Command-line client for WebSockets, like netcat (or curl) for `ws://`
+
+TIP: You can install `websocat` following the instructions at link:https://github.com/vi/websocat#installation[] or downloading binaries from link:https://github.com/vi/websocat/releases[]
+
+Connect to the change streams using the following command, given that the default user `admin` exists with the default password:
+
+[source,bash]
+$ websocat --text - autoreconnect:ws://admin:secret@127.0.0.1:8080/messages/_streams/all
+
+
+To allow connections without authentication, you can define the following permission
+
+[source,http]
+POST /acl HTTP/1.1
+
+++++
+{% include code-header.html type="Request body" %}
+++++
+[source,json]
+
+
+[source,json]
+----
+{
+ "_id": "unauthenticatedCanConnectToMyWebSocket",
+ "predicate": "path-prefix('/messages/_streams/all')",
+ "priority": 0,
+ "roles": [ "$unauthenticated" ]
+}
+----
+
+With this permission in place, you can connect to the WebSocket without authentication:
+
+[source,bash]
+$ websocat --text - autoreconnect:ws://127.0.0.1:8080/messages/_streams/all
+
+If we now create a new document in the collection `messages`
+
+[source,http]
+POST /messages HTTP/1.1
+
+++++
+{% include code-header.html type="Request body" %}
+++++
+[source,json]
+
+
+[source,json]
+----
+{
+ "message": "Hello WebSockets!",
+ "name": "uji"
+}
+----
+
+We get the following output from `websocat`:
+
+[source,bash]
+----
+$ websocat --text - autoreconnect:ws://admin:secret@127.0.0.1:8080/messages/_streams/all
+{"fullDocument":{"_id":{"$oid":"62166d53ebdcd56455a1a7ab"},"message":"Hello WebSockets!","name":"uji","_etag":{"$oid":"62166d53ebdcd56455a1a7aa"}},"documentKey":{"_id":{"$oid":"62166d53ebdcd56455a1a7ab"}},"operationType":"insert"}
+----
\ No newline at end of file
diff --git a/docs/v7/mongodb-websocket/index.adoc b/docs/v7/mongodb-websocket/index.adoc
new file mode 100644
index 00000000..79512df7
--- /dev/null
+++ b/docs/v7/mongodb-websocket/index.adoc
@@ -0,0 +1,44 @@
+---
+title: WebSocket API Overview
+layout: docs-adoc
+menu: mongodb
+---
+
+== Introduction
+
+This section describes the WebSocket API that allows publishing data events to WebSocket clients.
+
+> The WebSocket API is an advanced technology that makes it possible to open a two-way interactive communication session between the user's browser and a server. With this API, you can send messages to a server and receive event-driven responses without having to poll the server for a reply.
+
+Ref: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API
+
+> MongoDB's Change streams allow applications to access real-time data changes without the complexity and risk of tailing the oplog. Applications can use change streams to subscribe to all data changes on a single collection, a database, or an entire deployment, and immediately react to them. Because change streams use the aggregation framework, applications can also filter for specific changes or transform the notifications at will.
+
+Ref: https://docs.mongodb.com/manual/changeStreams
+
+== RESTHeart Change Stream
+
+__RESTHeart embeds a WebSocket server implementation__ that allows to expose MongoDB's Change Streams to Web browsers and any kind of HTTP/WebSocket client.
+
+With RESTHeart is possible to __create Web or Mobile apps that can be asynchronously notified in real time of data changes__. Because change streams use the link:https://docs.mongodb.com/manual/aggregation/[aggregation framework], applications can also filter for specific changes.
+
+For example, if the stream `all` is defined on the collection `messages`, clients can connect via WebSocket to `ws://mydomain.com/messages/_streams/all` and receive real time notification of data changes occurring in the collection.
+
+++++
+
+++++
+
+Exposing a WebSocket Server, clients may be promptly notified about these changes only if necessary, avoiding network expensive common practices like polling.
+
+++++
+`. This tagging does not apply when using wildcards in path templates.
+
+Now, let's proceed by making a few requests to /acme/ping using httpie.
+
+[source,bash]
+----
+$ http -b :8080/acme/ping
+Greetings from RESTHeart!
+
+$http -b :8080/acme/ping
+Greetings from RESTHeart!
+
+$http -b :8080/acme/ping
+Greetings from RESTHeart!
+----
+
+Now we can ask for available metrics:
+
+[source,bash]
+----
+$ http -b -a admin:secret :8080/metrics
+[
+ "/jvm",
+ "/{tenant}/ping"
+]
+----
+
+Let's get the metrics for requests matching `"/{tenant}/*"`:
+
+[source,bash]
+----
+$ http -b -a admin:secret :8080/metrics/{tenant}/\*
+
+(omitting many rows)
+http_requests_count{request_method="GET",path_template="/{tenant}/*",response_status_code="200",path_template_param_tenant="acme",} 3.0
+----
+
+The response is in prometheus format. The highlighted row is the metrics `http_requests_count` with value `3` and the following tags:
+
+[source,bash]
+----
+request_method="GET"
+path_template="/{tenant}/*"
+response_status_code="200",
+path_template_param_tenant="acme"
+----
+
+## Use prometheus to display metrics
+
+Define the following prometheus configuration file `prometheus.yml`
+
+[source,yml]
+----
+global:
+ scrape_interval: 5s
+ evaluation_interval: 5s
+
+scrape_configs:
+ - job_name: 'restheart http /{tenant}/*'
+ static_configs:
+ - targets: ['host.docker.internal:8080']
+ metrics_path: '/metrics/{tenant}/*'
+ basic_auth:
+ username: admin
+ password: secret
+ - job_name: 'restheart jvm'
+ static_configs:
+ - targets: ['host.docker.internal:8080']
+ metrics_path: '/metrics/jvm'
+ basic_auth:
+ username: admin
+ password: secret
+----
+
+Run prometheus with:
+
+[source,bash]
+----
+$ docker run --rm --name prometheus -p 9090:9090 -v ./prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus --config.file=/etc/prometheus/prometheus.yml
+----
+
+Prometheus will start scraping restheart metrics. Note that given the default `exclude` path templates, metrics for prometheus requests are not collected.
+
+Open `localhost:9090` with your browser and check the metrics:
+
+image::https://github.com/SoftInstigate/restheart/assets/6876503/154b3e6c-bc42-4751-af2d-7e2928746fa4[restheart metrics shown in prometheus]
+
+## Add custom metrics labels from a Service
+
+The `org.restheart.metrics.Metrics.attachMetricLabels(Request request, List labels)` method provides the capability to include custom labels in the metrics that are being collected.
+
+For example, the `GraphQLService` utilizes this method to include the `query` label in the metrics, which corresponds to the name of the executed GraphQL query.
diff --git a/docs/v7/performances.md b/docs/v7/performances.md
new file mode 100644
index 00000000..ed8ac6af
--- /dev/null
+++ b/docs/v7/performances.md
@@ -0,0 +1,174 @@
+---
+title: Performances
+layout: docs
+menu: overview
+---
+
+
+
+
+
+## Introduction
+
+An operation on a single document is atomic. This is enough in most use cases since embedded documents can capture relationships between data in a single document.
+
+However, for situations that require atomicity for multiple write requests or consistency between multiple read requests, multi-document transactions must be used.
+
+{: .bs-callout.bs-callout-info }
+Multi-document transaction requires at least MongoDB v4.0 configured as a [Replica Set](https://docs.mongodb.com/manual/replication/).
+
+Stay consistent!
++
Enforce Atomicity, Consistency, Isolation and Durability with multi-document transactions.
+
+
+
+
+{: .bs-callout.bs-callout-info }
+The demo application shown during the talk is available from github at [restheart-txn-demo](https://github.com/softInstigate/restheart-txn-demo)
+
+## Sessions
+
+MongoDB v3.6 introduced _sessions_, defined as follows:
+
+> A session is an abstract concept that represents a set of sequential operations executed by an application that are related in some way.
+
+Sessions allows to enforce casual consistency and are the foundation for transactions.
+
+{: .bs-callout.bs-callout-success }
+Sessions are available also in the OS version of RESTHeart. RESTHeart adds support for multi-document transactions on top of sessions.
+
+### Start a session
+
+```http
+POST /_sessions HTTP/1.1
+{ "causallyConsistent": true }
+
+HTTP/1.1 201 Created
+Access-Control-Allow-Credentials: true
+Access-Control-Allow-Origin: *
+Access-Control-Expose-Headers: Location, ETag, X-Powered-By
+Connection: keep-alive
+Content-Length: 0
+Content-Type: application/json
+Date: Wed, 19 Jun 2019 09:01:04 GMT
+Location: http://localhost:8009/_sessions/11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0
+X-Powered-By: restheart.org
+```
+
+The _causallyConsistent_ property is optional, true by default.
+
+The session id is returned via the _Location_ response header. In this case
+
+```
+sid=11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0
+```
+
+### Execute a request in a session
+
+Requests can be executed in a session using the |`sid` query parameter.
+
+```http
+POST /coll?sid=11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0 HTTP/1.1
+{"foo": "bar"}
+
+HTTP/1.1 201 Created
+```
+
+```http
+GET /coll?sid=11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0 HTTP/1.1
+
+HTTP/1.1 200 OK
+```
+
+## Transactions
+
+Transactions are handled in sessions; per each session, one transaction at a time can be started.
+
+### Transaction Status
+
+The following tables lists all possible transactions status.
+
+{: .table }
+|status|description|
+|IN|The transaction is in progress|
+|ABORTED|The transaction has been aborted, either explicitly or due to an error or because it expired|
+|COMMITTED|The transaction has been successfully committed|
+
+### Error handling
+
+{: .bs-callout.bs-callout-warning }
+The client is responsible of handling the following errors when executing requests inside a transaction and incorporate retry logic.
+
+The following table shows the most important error status that should be handled.
+
+{: .table }
+|error|response status|description|
+|-|-|
+|The given transaction is not in-progress|406|A request is executed in a transaction whose status is not IN|
+|Write conflict inside transaction|409|This error occurs when a transaction updating one of more documents tries to commit after a second transaction have been successfully committed updating the same data.|
+
+{: .bs-callout.bs-callout-warning }
+By default, a transaction must have a runtime of less than one minute. After that, the transaction is automatically ABORTED.
+Check
+MongoDB Documentation for more information.
+
+### Start the transaction
+
+Transaction are started in sessions.
+
+The following POST request starts the transaction in session `11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0`
+
+```http
+POST /_sessions/11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0/_txns HTTP/1.1
+
+HTTP/1.1 201 Created
+Location: http://localhost:8009/_sessions/11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0/_txns/1
+...
+```
+
+Note that the `Location` response header returns the id of the transaction or `txn`. In this case:
+
+```
+txn=1
+```
+
+### Get the current transaction status
+
+```http
+GET /_sessions/11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0/_txns HTTP/1.1
+
+HTTP/1.1 200 Ok
+...
+{
+ "currentTxn": {
+ "id": 1,
+ "status": "IN"
+ }
+}
+```
+
+### Execute requests in the transaction
+
+Requests can be executed in the transaction using the `sid` and `txn` query parameters.
+
+```http
+POST /coll?sid=11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0&txn=1 HTTP/1.1
+{"foo": "bar"}
+
+HTTP/1.1 201 Created
+```
+
+```http
+GET /coll?sid=11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0&txn=1 HTTP/1.1
+
+HTTP/1.1 200 Ok
+```
+
+### Commit the transaction
+
+Use the method PATCH to commit the transaction.
+
+```http
+PATCH /_sessions/11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0/_txns/1 HTTP/1.1
+
+HTTP/1.1 200 OK
+```
+
+### Abort the transaction
+
+Use the method DELETE to abort the transaction.
+
+```http
+DELETE /_sessions/11c3ceb6-7b97-4f34-ba3f-689ea22ce6e0/_txns/1 HTTP/1.1
+
+HTTP/1.1 204 No Content
+```
diff --git a/docs/v7/mongodb-rest/tutorial.md b/docs/v7/mongodb-rest/tutorial.md
new file mode 100644
index 00000000..17a2ad87
--- /dev/null
+++ b/docs/v7/mongodb-rest/tutorial.md
@@ -0,0 +1,223 @@
+---
+title: REST API Tutorial with RESTHeart
+layout: docs
+menu: mongodb
+---
+
+Tech talk on Transaction in RESTHeart at MongoDB Live 2020
+
+
+- [Running the example requests](#before-running-the-example-requests)
+- [GET Documents](#get-documents)
+- [GET Documents with filter](#get-documents-with-filter)
+- [POST a new document](#post-a-new-document)
+- [PUT a new document](#put-a-new-document)
+- [PATCH an existing document](#patch-an-existing-document)
+- [DELETE a document](#delete-a-document)
+
+
+
+
+{% include docs-head.html %}
+
+{: .bs-callout.bs-callout-warning}
+*Execute on rest ninja* doesn't work with Safari because it requires HTTPS. Since configuring HTTPS requires a valid certificate and takes some time to [configure](/docs/security/tls/), we suggest to just use Chrome or Firefox for this tutorial.
+
+{: .bs-callout.bs-callout-info }
+Watch [Practical testing with Rest Ninja](https://www.youtube.com/watch?v=9KroH-RvjS0&t=291s)
+
+{% include running-examples.md %}
+
+### GET Documents
+
+Now let’s get all documents in a row. For this, we send a GET request to the whole collection:
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/e1d4fc9769d1fd15fc11f8b0b360897668ff11a9/1"
+%}
+
+```http
+GET /inventory HTTP/1.1
+```
+
+{% include code-header.html
+ type="Response"
+%}
+
+```json
+[
+ {
+ "_id": {
+ "$oid": "5d0b3dbc2ec9ff0d92ddc2aa"
+ },
+ "_etag": {
+ "$oid": "5d0b3dbc2ec9ff0d92ddc2a5"
+ },
+ "item": "postcard",
+ "qty": 45,
+ "size": {
+ "h": 10,
+ "w": 15.25,
+ "uom": "cm"
+ },
+ "status": "A"
+ },
+ {
+ "_id": {
+ "$oid": "5d0b3dbc2ec9ff0d92ddc2a9"
+ },
+ "_etag": {
+ "$oid": "5d0b3dbc2ec9ff0d92ddc2a5"
+ },
+ "item": "planner",
+ "qty": 75,
+ "size": {
+ "h": 22.85,
+ "w": 30,
+ "uom": "cm"
+ },
+ "status": "D"
+ },
+ ...
+]
+```
+
+### GET Documents with filter
+
+It's possible to apply a filter at the end of the request to reduce the number of output documents.
+The following request asks for all documents with a "qty" property greater than 75:
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/2f4fa18afdfd17aa5b1ce0af0e99316015d905a4/1"
+%}
+
+```http
+GET /inventory?filter={"qty":{"$gt":75}} HTTP/1.1
+```
+
+{% include code-header.html
+ type="Response"
+%}
+
+```json
+[
+ {
+ "_id": {
+ "$oid": "5d0b3dbc2ec9ff0d92ddc2a8"
+ },
+ "_etag": {
+ "$oid": "5d0b3dbc2ec9ff0d92ddc2a5"
+ },
+ "item": "paper",
+ "qty": 100,
+ "size": {
+ "h": 8.5,
+ "w": 11,
+ "uom": "in"
+ },
+ "status": "D"
+ }
+]
+```
+
+{: .bs-callout.bs-callout-info}
+Note that only the retrieved document meets the filter's condition.
+
+{: .bs-callout.bs-callout-info }
+Watch [How to filter data](https://www.youtube.com/watch?v=9KroH-RvjS0&t=610s)
+
+### POST a new document
+
+Now we are going to insert a new document to the collection.
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/39921ec3386f81ff963b070a64171e3c3968bd1f/0"
+%}
+
+```http
+POST /inventory HTTP/1.1
+
+{"item": "newItem", "qty": 10, "size": { "h": 2, "w": 4, "uom": "cm" }, "status": "C"}
+```
+
+{% include code-header.html
+ type="Response"
+%}
+
+```
+ETag: 5d0b47422ec9ff0d92ddc2ad
+X-Powered-By: restheart.org
+Content-Type: application/json
+Location: http://localhost:8080/inventory/5d0b47425beb2029a8d1bc72
+```
+
+{: .bs-callout.bs-callout-info}
+Note the `Location` header in the response, as it contains a link to the newly created document! To get the document you can directly copy that link and use it in a subsequent query.
+
+### PUT a new document
+
+It's possible to PUT a document into the collection by specifying the document identifier at the end of the request, in this case we need to use the query parameter `?wm=upsert` since PUT default write mode is `update`:
+
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/fe7c43013f9a9f8bc9e0f35d7e0980d14e2fd64c/4"
+%}
+
+```http
+PUT /inventory/newDocument?wm=upsert HTTP/1.1
+
+{ "item": "yetAnotherItem", "qty": 90, "size": { "h": 3, "w": 4, "uom": "cm" }, "status": "C" }
+```
+
+### PATCH an existing document
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/a2cad148132e2fa8a5c95e4e681b6c3a85f60215/0"
+%}
+
+```http
+PATCH /inventory/newDocument HTTP/1.1
+
+{ "qty": 40, "status": "A", "newProperty": "value" }
+```
+
+{% include code-header.html
+ type="Response"
+%}
+
+```json
+{
+ "_id": "newDocument",
+ "item": "yetAnotherItem",
+ "qty": 40,
+ "size": {
+ "h": 3,
+ "w": 4,
+ "uom": "cm"
+ },
+ "status": "A",
+ "_etag": {
+ "$oid": "5d0b4b9e2ec9ff0d92ddc2af"
+ },
+ "newProperty": "value"
+}
+```
+
+{: .bs-callout.bs-callout-info}
+The previous request changes the document created in the previous example as indicated in the request body.
+
+### DELETE a document
+
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/311d230363a4c073a1e67ef327bd403cadb1238f/0"
+%}
+
+```http
+DELETE /inventory/newDocument HTTP/1.1
+```
+
+
diff --git a/docs/v7/mongodb-rest/write-docs.adoc b/docs/v7/mongodb-rest/write-docs.adoc
new file mode 100644
index 00000000..fcb61058
--- /dev/null
+++ b/docs/v7/mongodb-rest/write-docs.adoc
@@ -0,0 +1,356 @@
+---
+title: Write Documents
+layout: docs-adoc
+menu: mongodb
+---
+
+:page-liquid:
+
+== Introduction
+
+You will learn how to insert, update and delete documents in a collection.
+
+{% include running-examples.adoc %}
+
+== Content-Type
+
+For write requests use `Content-Type: application/json`
+
+In this case the request body is just the JSON representation of the MongoDB BSON format, see link:/docs/mongodb-rest/representation-format[Representation format] for more information.
+
+See the following example:
+
+[source,http]
+----
+POST /coll HTTP/1.1
+Content-Type: application/json
+
+{
+ "b": true,
+ "n": 1,
+ "ns": "1",
+ "obj": {
+ "foo": "bar"
+ }
+}
+----
+
+Starting from RESTHeart 7.4.0, the MongoService also supports the content types `application/x-www-form-urlencoded` and `multipart/form-data`.
+
+In those cases the request body is transformed to a BSON document by parsing the fields/parts. The example below will help make it clearer to understand how this works:
+
+[source,http]
+----
+POST /coll HTTP/1.1
+Content-Type: application/x-www-form-urlencoded; charset=utf-8
+
+n=1&ns=%221%22&b=true&obj=%7B%22foo%22%3A+%22bar%22%7D
+----
+
+In this case, the request content (whose url-decoded value is `n=1&ns="1"&b=true&obj={"foo":"bar"}`) is transformed in the following document:
+
+[source,json]
+----
+{
+ "b": true,
+ "n": 1,
+ "ns": "1",
+ "obj": {
+ "foo": "bar"
+ }
+}
+----
+
+NOTE: The karate test link:https://github.com/SoftInstigate/restheart/blob/master/core/src/test/java/karate/mongoservice-multipart-form-content-type.feature[mongoservice-multipart-form-content-type.feature] includes more examples on how `form-urlencoded` and `multipart` requests are handled.
+
+== Write Mode
+
+The default write modes for each HTTP verb are:
+
+- `POST` verb has *insert* write mode
+- `PUT` and `PATCH` verbs have *update* write mode
+
+*Use `POST` to _create_ a document, `PUT` to _replace_ an existing document and `PATCH` to _update_ selected properties of an existing document.*
+
+The query parameter `?wm=insert|update|upsert` allows specifying the **w**rite **m**ode.
+
+IMPORTANT: *the qparam `?wm` is forbidden by default*; to allow it, the following permission must be granted to the client (the default user `admin` can use it because it has the `root` role that provides all permissions).
+
+[source,json]
+----
+{
+ "_id": "user-can-wse-wm-qparam",
+ "roles": [ "user" ],
+ "predicate": "path-prefix(/collection)",
+ "mongo": {
+ "allowWriteMode": true
+ }
+}
+----
+
+## Create a document
+
+To create a document use the `POST` method.
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/fcf2a3da225dc2018581416fee19f96fb105cca3/6"
+%}
+++++
+
+
+[source,http]
+----
+POST /inventory HTTP/1.1
+
+{ "_id": "newItem", "item": "rubber", "qty": 15, "size": { "h": 2, "w": 1, "uom": "cm" }, "status": "A" }
+----
+
+NOTE: If `_id` field is not specified in the request body, it will generated by MongoDB as an `ObjectId` and returned to the client via the `Location` response header.
+
+== Replace a document
+
+To replace a document use the `PUT` method.
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/21de47ede7d9e910b80ac0d998184bf992b98895/6"
+%}
+++++
+
+[source,http]
+----
+PUT /inventory/newItem HTTP/1.1
+
+
+{ "item": "pencil", "qty": 55, "size": { "h": 10, "w": 0.5, "uom": "cm" }, "status": "B", "suppliers": ["brand_1", "brand_2", "brand_3"] }
+----
+
+## Update a document's property
+
+To update one or more properties of a document use the `PATCH` method.
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/cad8a808b52787063c7544d396d7b4ba30be489f/0"
+%}
+++++
+
+[source,http]
+----
+PATCH /inventory/newItem HTTP/1.1
+
+{ "status": "A" }
+----
+
+NOTE: the `PATCH` verb allows passing update operator expressions; the body can contain update operators.
+
+## DELETE a document
+
+To delete a document use the `DELETE` method.
+
+++++
+{% include code-header.html
+ type="Request"
+ link="https://restninja.io/share/c83643990fe2ba9857d267d9203445fd4a5ecef5/0"
+%}
+++++
+
+[source,http]
+----
+DELETE /inventory/newItem HTTP/1.1
+----
+
+== Dot Notation
+
+RESTHeart always allows using the dot notation to access the elements of an array and to access the fields of an embedded document.
+
+The dot notation can be used in `PUT`, `PATCH` and `POST` verbs.
+
+=== Update an array element
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/d891c0dfaf794019f7cebf79dafa895cd9697da7/0"
+%}
+++++
+
+[source,http]
+----
+PATCH /inventory/newItem HTTP/1.1
+
+{ "suppliers.1": "new_brand" }
+----
+
+==== Update the property of an embedded document
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/fef0424bf8e69d11a7aae35f41a82e67164a1dfc/0"
+%}
+++++
+
+
+[source,http]
+----
+PATCH /inventory/newItem HTTP/1.1
+
+{ "size.h": 20 }
+----
+
+== Update with Operators
+
+Update with operators allows applying MongoDb's update operators to a document. For example, you can use `$unset` to remove a property from a document.
+
+NOTE: See link:https://www.mongodb.com/docs/manual/reference/operator/update/[Update
+Operators] in MongoDb documentation for more information.
+
+Use the `PATCH` verb to update a document with update operators, passing an update operator expression document.
+
+NOTE: To use update operators you need to use the verb `PATCH`. Anyway `PUT` and `POST` can still use the `$currentDate` update operator.
+
+Example: update `newItem` document with update operators:
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/1f3c2941dc649dfb8a3ba6628451093f83d02fea/0"
+%}
+++++
+
+[source,http]
+----
+PATCH /inventory/newItem HTTP/1.1
+
+{
+ "$inc": { "qty": 1 },
+ "$push": { "suppliers": "pushed_brand" },
+ "$unset": { "status": null },
+ "$currentDate": { "timestamp": true }
+}
+----
+
+== Update with Aggregation Pipeline
+
+WARNING: Update with Aggregation Pipeline are available from RESTHeart 7.3
+
+Update with aggregation pipeline allows for a more expressive update statement.
+
+NOTE: See link:https://www.mongodb.com/docs/manual/tutorial/update-documents-with-aggregation-pipeline/[Updates with Aggregation Pipeline] in MongoDb documentation for more information.
+
+Use the `PATCH` verb to update a document with an Aggregation Pipeline, passing an array or aggregation stages.
+
+Example: update `newItem` adding two items to the current `suppliers` array:
+
+[source,http]
+----
+PATCH /inventory/newItem HTTP/1.1
+
+[ { "$set": { "suppliers": { "$concatArrays": [ "$suppliers", [ "brand_4", "brand_5", ] ] } } } ]
+----
+
+== Bulk Write Requests
+
+Bulk write requests create, update or delete multiple documents with a
+single request.
+
+A bulk request response contains the URIs of the created documents.
+
+IMPORTANT: *bulk requests are forbidden by default*; to allow them, the following permission must be granted to the client (the default user `admin` can execute them because it has the `root` role that provides all permissions):
+
+[source,json]
+----
+{
+ "_id": "user-can-execute-bulk-requests",
+ "roles": [ "user" ],
+ "predicate": "path-prefix(/collection)",
+ "mongo": {
+ "allowBulkPatch": true,
+ "allowBulkDelete": true,
+ "allowWriteMode": true
+ }
+}
+----
+
+=== Create an array of documents
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/cf5cba6e1d391b475e04c33d01715b883e1a5490/0"
+%}
+++++
+
+
+[source,http]
+----
+POST /inventory HTTP/1.1
+
+[
+ { "item": "journal", "qty": 25, "size": { "h": 14, "w": 21, "uom": "cm" }, "status": "A" },
+ { "item": "notebook", "qty": 50, "size": { "h": 8.5, "w": 11, "uom": "in" }, "status": "A" },
+ { "item": "paper", "qty": 100, "size": { "h": 8.5, "w": 11, "uom": "in" }, "status": "D" },
+ { "item": "planner", "qty": 75, "size": { "h": 22.85, "w": 30, "uom": "cm" }, "status": "D" },
+ { "item": "postcard", "qty": 45, "size": { "h": 10, "w": 15.25, "uom": "cm" }, "status": "A" }
+]
+----
+
+IMPORTANT: Its a `POST` request, then the default write mode is `insert`. As usual, you can use the `?wm=insert|update|upsert` query parameter to change write mode.
+
+=== Update properties in multiple documents
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/0e5b13f1e048ea373f86c19e8fb48be7c70c7531/0"
+%}
+++++
+
+[source,http]
+----
+PATCH /inventory/*?filter={"qty":{"$gte":50}} HTTP/1.1
+
+{
+ "qty":1000
+}
+----
+
+=== DELETE multiple documents
+
+++++
+{% include code-header.html
+ type="Request"
+ link="http://restninja.io/share/acba248263a0be8e55ed03d7ff52e79a27449bbd/0"
+%}
+++++
+
+[source,http]
+----
+DELETE /inventory/*?filter={"qty":{"$lte":50}} HTTP/1.1
+----
+
+== MongoDB write operations
+
+The MongoDB write operation depends on the request method and on the write mode as follows:
+
+[options="header"]
+[cols="1,1,2,3,2"]
+|============================================================================================
+| write mode | method | URI | MongoDB write operation | write operation argument
+| *insert* | *POST* | `/coll` | `insertOne` | *document*
+| insert | PUT | `/coll/docid` | `insertOne` | document
+| insert | PATCH | `/coll/docid` | `findOneAndUpdate(upsert:true)` (1) | update operator expression or update aggregation pipeline
+| update | POST | `/coll` | `findOneAndReplace(upsert:false)` | document
+| *update* | *PUT* | `/coll/docid` | `findOneAndReplace(upsert:false)` | *document*
+| *update* | *PATCH* | `/coll/docid` | `findOneAndUpdate(upsert:false)` | *update operator expression or update aggregation pipeline*
+| upsert | POST | `/coll` | `findOneAndReplace(upsert:true)` | document
+| upsert | PUT | `/coll/docid` | `findOneAndReplace(upsert:true)` | document
+| upsert | PATCH | `/coll/docid` | `findOneAndUpdate(upsert:true)` | update operator expression or update aggregation pipeline
+|============================================================================================
+
+(1) uses a find condition that won't match any existing document, making sure the operation is an insert
diff --git a/docs/v7/mongodb-websocket/change-streams.adoc b/docs/v7/mongodb-websocket/change-streams.adoc
new file mode 100644
index 00000000..455f80c7
--- /dev/null
+++ b/docs/v7/mongodb-websocket/change-streams.adoc
@@ -0,0 +1,66 @@
+---
+title: Change streams
+layout: docs-adoc
+menu: mongodb
+---
+
+== The "streams" collection metadata
+
+In RESTHeart, not only documents but also databases and collections have
+properties. Some properties are metadata, i.e. they have a special
+meaning for RESTheart that influences its behavior.
+
+The collection metadata property `streams` allows to declare change streams that client can watch for to be aware about changes to documents and bind them to given URI.
+
+Change streams need to be defined as collection metadata. This way clients are not able to open up arbitrary change streams but only those defined (and tested) by the developers.
+
+`streams` is an array of _stream_ definitions.
+
+== Stream definition format
+
+```json
+{ "streams": [
+ {
+ "uri":
+++++
+
+Exposing a WebSocket Server, clients may be promptly notified about these changes only if necessary, avoiding network expensive common practices like polling.
+
+++++
+
+
+
+++++
+
+NOTE: Change streams require at least MongoDB configured as a link:https://docs.mongodb.com/manual/replication/[Replica Set]
+
+NOTE: When the `stream` collection metadata is modified or the collection or the db is deleted, all related WebSocket connections are closed and the change streams are consequently updated.
\ No newline at end of file
diff --git a/docs/v7/mongodb-websocket/variables.adoc b/docs/v7/mongodb-websocket/variables.adoc
new file mode 100644
index 00000000..4a69e925
--- /dev/null
+++ b/docs/v7/mongodb-websocket/variables.adoc
@@ -0,0 +1,99 @@
+---
+title: Using Variables
+layout: docs-adoc
+menu: mongodb
+---
+
+== Passing Variables to Change Stream
+
+The aggregation stages of the change stream can use _variables_, as in the following example:
+
+[source,json]
+----
+{
+ "uri": "mine",
+ "stages": [
+ { "$match": { "fullDocument::name": { "$var": "n" } } }
+ ]
+}
+----
+
+The `$match` stage uses the variable `n`, specified as `{ "$var": "n" }`.
+
+The client can pass the variable using the `avars` query parameter.
+
+[source,http]
+----
+GET /messages/_streams/mine?avars={"n":"Andrea"} HTTP/1.1
+----
+
+In case of the change stream *mine* described in the link:/docs/mongodb-websocket/examples[examples], the variable `n` is used to restrict notifications only to changes on documents with the property _name_ matching it.
+
+== Dot Notation support for `$var`
+
+`$var` in RESTHeart change streams can utilize dot notation to access nested properties. This allows you to specify a complex variable structure and reference its components for more flexible filtering.
+
+NOTE: Variable Dot Notation is available from RESTHeart v7.6
+
+For example, if a client passes a variable as `avar={"options": {"name": "Andrea"}}`, you can access the nested property `name` using the dot notation within an aggregation stage, like this:
+
+[source,json]
+----
+{
+ "uri": "mine",
+ "stages": [
+ { "$match": { "fullDocument::name": { "$var": "options.name" } } }
+ ]
+}
+----
+
+The `$match` stage in the previous example uses the dot notation in `{ "$var": "options.name" }` to reference the nested property `name`, in this case `Andrea`.
+
+By employing dot notation, you can work with structured and nested data effectively and make your change stream filtering more versatile and powerful.
+
+== Variables with Default Values
+
+Variables can have a default value. This default value is used when the variable is not specified in the `?avar` query parameter.
+
+NOTE: Variables with Default Values are available from RESTHeart v7.6
+
+For more detailed information on using variables with default values, please refer to the link:/docs/mongodb-rest/aggregations#variables-with-default-values[Aggregation documentation].
+
+== Predefined variables
+
+The change stream aggregation can use _predefined variables_, as in the following example:
+
+[source,json]
+----
+{
+ "uri": "mine",
+ "stages": [
+ { "$match": { "fullDocument::name": { "$var": "@user._id" } } }
+ ]
+}
+----
+
+The `$match` stage uses the predefined variable `@user._id`, specified as `{ "$var": "@user._id" }`.
+
+NOTE: the predefined variables are resolved server side, i.e. the client does not need to pass the variable and the server will resolve it, making sure its value is trusted. In the example, the `name` property is matched against the user id of the authenticated user.
+
+Refer to link:/docs/mongodb-rest/aggregations#predefined-variables[Aggregation] documentation page for more information.
+
+== Security considerations
+
+By default RESTHeart makes sure that the variables passed as query parameters don't contain MongoDB operators.
+
+This behavior is required to protect data from undesirable malicious query injection.
+
+Even though is highly discouraged, is possible to disable this check by editing the following property in the `restheart.yml` configuration file.
+
+[source]
+----
+## Security
+
+# Check if aggregation variables use operators.
+# Allowing operators in aggregation variables is risky
+# because requester can inject operators modifying the query
+
+aggregation-check-operators: true
+----
diff --git a/docs/v7/monitoring.adoc b/docs/v7/monitoring.adoc
new file mode 100644
index 00000000..7f8cbe30
--- /dev/null
+++ b/docs/v7/monitoring.adoc
@@ -0,0 +1,139 @@
+---
+title: Monitoring
+layout: docs-adoc
+menu: setup
+---
+
+NOTE: Available from v7.5. For earlier releases only requests handled by the `MongoService` can be monitored, see link:/docs/mongodb-rest/monitoring[Monitoring MongoService requests]
+
+RESTHeart enables the tracking of various key performance indicators (KPIs) for HTTP requests and the JVM. These metrics can be accessed through an API in Prometheus format, enabling you to query and visualize graphs using Prometheus.
+
+The following HTTP requests metrics are collected by RESTHeart:
+
+- http_requests_count (Count of HTTP requests)
+- http_requests_duration (Duration of HTTP requests)
+- http_requests_rate (Rate of HTTP requests)
+
+Additionally, RESTHeart captures JVM metrics such as memory usage and garbage collector data.
+
+## Tutorial
+
+Run restheart enabling metrics and specifying a configuration:
+
+[source,bash]
+----
+$ docker run --rm -p "8080:8080" -e RHO="/http-listener/host->'0.0.0.0';/mclient/connection-string->'mongodb://host.docker.internal';/ping/uri->'/acme/ping';/requestsMetricsCollector/enabled->true;/jvmMetricsCollector/enabled->true;/requestsMetricsCollector/include->['/{tenant}/*']" softinstigate/restheart
+----
+
+With the given `RHO` env variable, the configuration is:
+
+[source,yml]
+----
+ping:
+ uri: /acme/ping # change the ping service uri for testing purposes
+requestsMetricsCollector:
+ enabled: true
+ uri: /metrics
+ include:
+ - /{tenant}/*
+ exclude:
+ - /metrics
+ - /metrics/*
+jvmMetricsCollector:
+ enabled: true
+----
+
+Metrics will be gathered for requests that match the path templates specified in the `include` criteria and do not match those listed in the `exclude` criteria.
+
+Please note that when using the variable `{tenant}` in the include path templates, the metrics will be tagged with `path_template_param_tenant=Blazing fast.
++
Handle hundreds of thousands of concurrent clients.
+Check the performance tests!
+
+
+* [Change Streams](#change-streams)
+
+* [Read and Write JSON documents](#read-and-write-json-documents)
+ * [Test case 1](#test-case-1)
+ * [Test case 2](#test-case-2)
+ * [Test case 3](#test-case-3)
+
+* [How we tested](#how-we-tested)
+
+
+
+
+{% include docs-head.html %}
+
+RESTHeart has been designed and developed with lightness and
+performances as fundamental parameters.
+
+This section includes the performance test results gathered by the
+SoftInstigate’s development team and includes all the information needed
+to autonomously reproduce the tests.
+
+## Change Streams
+
+Measure RESTHeart's notification throughput while _n_ Websockets are listening for targeted notifications.
+RESTHeart will process 180 POSTs in 60 seconds while testing (3 RPS) and every client will wait until all notification have been received.
+
+
+{: class="img-responsive"}
+
+Observing the graph, RESTHeart delivers almost real-time notification for a very huge amount of clients:
+
+{: .table }
+| Clients | TPS | Mean Notification Time (333ms = Real Time) |
+|:-------------|-----------------------------:|-------------------------------------------:|
+| **10** | 27 | 357ms |
+| **100** | 278 | 359ms |
+| **1000** | 2790 | 358ms |
+| **10000** | 27909 | 358ms |
+| **15000** | 41812 | 358ms |
+| **20000** | 54125 | 369ms |
+| **25000** | 61995 | 403ms |
+
+
+## Read and Write JSON documents
+
+### Test case 1
+
+Measure the execution time to create **1 million documents** with random
+data, using **200 test threads.**
+
+{: class="img-responsive"}
+
+In this scenario, RESTHeart introduces just a **2,41% overhead** over
+the total execution time:
+
+{: .table }
+| | Execution Time | TPS |
+|---------------|:--------------:|:--------:|
+| **RESTHeart** | 250s | 3990 tps |
+| **Direct** | 244s | 4086 tps |
+
+### Test case 2
+
+Measure the execution time to **query a collection 100.000 times**,
+getting 5 documents each time (limit 5) and skipping just 25 documents,
+under different concurrency levels.
+
+{: class="img-responsive"}
+
+{: class="img-responsive"}
+
+RESTHeart delivers better performances under any concurrency level over
+direct access via MongoDB driver:
+
+{: .table }
+| Threads | 50| 100| 200| 250| 400| 500|
+|---------------|----:|----:|----:|----:|-----:|-----:|
+| **RESTHeart** | 78s| 82s| 78s| 76s| 76s| 76s|
+| **Direct** | 97s| 95s| 96s| 96s| 109s| 112s|
+
+### Test case 3
+
+Measure the execution time to **query a collection 2.000 times**,
+getting 5 documents each time (limit 5) and skipping just 250.000
+documents, under different concurrency levels.
+
+{: class="img-responsive"}
+
+{: class="img-responsive"}
+
+Thanks to the eager pre-allocation DBCursor engine, queries with
+significant skip parameter executes much faster (50 times in this case)
+with RESTHeart:
+
+{: .table }
+| Threads | 1 | 2 | 4 | 5 | 8 | 10 | 20 | 40 | 50 | 80 | 100 | 200 | 400 | 500 |
+|---------------|:------:|:-----:|:-----:|:-----:|:-----:|:----:|:-----:|:-----:|:-----:|:------:|:-----:|:-----:|:-----:|:------:|
+| **RESTHeart** | 16,28s | 6,22s | 5,05s | 2,53s | 3,76s | 3,6s | 2,98s | 5,65s | 9,04s | 10,74s | 6,76s | 9,24s | 6,76s | 12,71s |
+| **Direct** | 1091s | 627s | 324s | 328s | 329s | 325s | 324s | 321s | 321s | 304s | 302s | 305s | 327s | 327s |
+
+## How we tested
+
+### Reading and Writing JSON Documents
+
+#### Hardware
+
+MongoDB and RESTHeart running on Sunfire X2200 M2 with 2 CPU with 16
+Gbyte of RAM. See full
+specification [here](https://docs.oracle.com/cd/E19121-01/sf.x2200m2/819-6597-12/Chap1.html).
+This is an *old *server with 2 dual core 2,2GHz AMD Opteron CPUs.
+
+Test cases run by MacBook Pro client with 2,66 GHz Intel Core i7 and 8
+GB 1067 MHz DDR3
+
+The client and the server on the same local network linked by a 10/100
+Ethernet switch.
+
+#### Software
+
+- **Server OS**: Ubuntu server 64bit 14.04.1 LTS
+- **Client OS**: Mac OS X Yosemite 10.10.1
+- **MongoDB**: 2.6.7
+- **RESTHeart**: commit 01d403a5db8b765ad5b0a8eec1fda420c392ab58
+
+#### Configurations
+
+**MongoDB**: run (without authentication enabled) with the following
+command
+
+
+```
+$numactl --interleave=all /opt/mongodb/bin/mongod --fork --syslog
+```
+
+**RESTHeart**: run with default parameters with the following exception:
+
+- logging to file off
+- eager-cursor-allocation-linear-slice-heights set to \[50\]
+- io-threads: 8
+- worker-threads: 64
+
+#### Test code
+
+We used the brilliant [load test
+tool](https://github.com/bazhenov/load-test-tool).
+
+The test case code is available on Github as part of the RESTHeart source code baseline. You can find
+it [here](https://github.com/SoftInstigate/restheart/tree/master/core/src/test/java/org/restheart/test/performance).
+
+### Change Streams
+
+Tests have been made simulating a production environment composed by ***3 EC2 t3a.medium instances*** running with ***Ubuntu 18.04***
+
+_Check [this repository](https://github.com/SoftInstigate/restheart-perftest) to learn how to setup by your own a local testing environment._
+
+RESTHeart has been designed and developed with lightness and
+performances as fundamental parameters. On this regards, also thanks to
+its caching capabilities, RESTHeart often overcomes the results that can
+be achieved accessing MongoDB directly via its Java driver.
+
+This section includes the performance test results gathered by the
+SoftInstigate’s development team and includes all the information needed
+to autonomously reproduce the tests.
diff --git a/docs/v7/plugins/authentication-mechanisms.adoc b/docs/v7/plugins/authentication-mechanisms.adoc
new file mode 100644
index 00000000..c47576b4
--- /dev/null
+++ b/docs/v7/plugins/authentication-mechanisms.adoc
@@ -0,0 +1,165 @@
+---
+title: Authentication Mechanisms
+layout: docs-adoc
+menu: framework
+---
+
+== Authentication Mechanisms
+
+An *Authentication Mechanism* authenticates incoming requests.
+
+RESTHeart provides different implementations:
+
+- link:https://github.com/SoftInstigate/restheart/blob/master/security/src/main/java/org/restheart/security/mechanisms/BasicAuthMechanism.java[Basic Authentication]
+- link:https://github.com/SoftInstigate/restheart/blob/master/security/src/main/java/org/restheart/security/mechanisms/DigestAuthMechanism.java[Digest Authentication]
+- link:https://github.com/SoftInstigate/restheart/blob/master/security/src/main/java/org/restheart/security/mechanisms/JwtAuthenticationMechanism.java[JSON Web Token Authentication]
+- link:https://github.com/SoftInstigate/restheart/blob/master/security/src/main/java/org/restheart/security/mechanisms/TokenBasicAuthMechanism.java[Token Authentication]
+
+These are all different methods for the client to pass some sort of credentials to the server. For example, `BasicAuthMechanism` extracts the credentials from the `Authorization` request header following the Basic Authentication specs link:https://tools.ietf.org/html/rfc7617[RFC 7617].
+
+Once the Authentication Mechanism has retrieved the credentials from the request, it can delegate the actual verification to an `Authenticator` that checks them against a credentials db that can be as simple as a configuration file or a database or an LDAP server.
+
+Multiple Authentication Mechanisms can be enabled. The request is authenticated if any of the enabled Authentication Mechanisms successfully verifies the request.
+
+=== Implementation
+
+The Authentication Mechanism class must implement the `org.restheart.plugins.security.AuthMechanism` interface.
+
+[source,java]
+----
+public interface AuthMechanism extends AuthenticationMechanism, ConfigurablePlugin {
+ @Override
+ public AuthenticationMechanismOutcome authenticate(final HttpServerExchange exchange, final SecurityContext securityContext);
+
+ @Override
+ public ChallengeResult sendChallenge(final HttpServerExchange exchange, final SecurityContext securityContext);
+
+ default String getMechanismName() {
+ return PluginUtils.name(this);
+ }
+}
+----
+
+==== Registering
+
+The Authentication Mechanism implementation class must be annotated with `@RegisterPlugin`:
+
+[source,java]
+----
+@RegisterPlugin(name="myAuthMechanism",
+ description = "my custom auth mechanism")
+public class MyAuthMechanism implements AuthMechanism {
+
+}
+----
+
+==== Configuration
+
+The Authentication Mechanism can receive parameters from the configuration file using the `@Inject("config")` annotation:
+
+[source,java]
+----
+@Inject("config")
+private Map config;
+
+@OnInit
+public void init() throws ConfigurationException {
+ // get configuration arguments
+ int number = argValue(this.config, "number");
+ String string = argValue(this.config, "string");
+}
+----
+
+The parameters are defined in the configuration using the name of the mechanism as defined by the `@RegisterPlugins` annotation:
+
+```yaml
+myAuthMechanism:
+ number: 10
+ string: a string
+```
+
+==== authenticate()
+
+The method `authenticate()` must return:
+
+- *NOT_ATTEMPTED*: the request cannot be authenticated because it doesn't fulfill the authentication mechanism requirements. An example is in `BasicAuthMechanism` when the request does not include the header `Authorization` or its value does not start with `Basic`.
+- *NOT_AUTHENTICATED*: the Authentication Mechanism handled the request but could not authenticate the client, for instance because of wrong credentials.
+- *AUTHENTICATED*: the Authentication Mechanism successfully authenticated the request.
+
+To mark the authentication as failed in `authenticate()`:
+
+```java
+securityContext.authenticationFailed("authentication failed", getMechanismName());
+return AuthenticationMechanismOutcome.NOT_AUTHENTICATED;
+```
+
+To mark the authentication as successful in `authenticate()`:
+
+```java
+// build the account
+final Account account;
+
+securityContext.authenticationComplete(account, getMechanismName(), false);
+
+return AuthenticationMechanismOutcome.AUTHENTICATED;
+```
+
+==== sendChallenge()
+
+`sendChallenge()` is executed when the authentication fails.
+
+The mechanism should not set the response code; instead, that should be indicated in the `AuthenticationMechanism.ChallengeResult`, and the most appropriate overall response code will be selected.
+
+This is due to the fact that several mechanisms can be enabled, and as an in-bound request is received, the authenticate method is called on each mechanism in turn until one of the following occurs: a mechanism successfully authenticates the incoming request, or the list of mechanisms is exhausted.
+
+`sendChallenge()` can also be used to set a response header.
+
+An example is `BasicAuthMechanism` that, in case of failure, indicates the response code `401 Not Authenticated` and sets the following challenge header:
+
+```
+WWW-Authenticate: Basic realm="RESTHeart Realm"
+```
+
+This is the code:
+
+```java
+@Override
+public ChallengeResult sendChallenge(HttpServerExchange exchange, SecurityContext securityContext) {
+ exchange.getResponseHeaders().add(WWW_AUTHENTICATE, challenge);
+ return new ChallengeResult(true, UNAUTHORIZED);
+}
+```
+
+==== Build the Account
+
+To build the account, the Authentication Mechanism can use a configurable `Authenticator`. This allows extending the Authentication Mechanism with different `Authenticator` implementations. For instance, the _BasicAuthMechanism_ can use Authenticator implementations that hold accounts information on a DB or on an LDAP server.
+
+TIP: Use the `@Inject("config")` and `@Inject("registry")` to retrieve the instance of the `Authenticator` from its name.
+
+```java
+private Authenticator authenticator;
+
+@Inject("config")
+private Map config;
+
+@Inject("registry")
+private PluginsRegistry registry;
+
+@OnInit
+public void init() throws ConfigurationException {
+ // the authenticator specified in auth mechanism configuration
+ this.authenticator = this.registry.getAuthenticator(argValue(this.config, "authenticator")).getInstance();
+}
+
+@Override
+public AuthenticationMechanismOutcome authenticate(final HttpServerExchange exchange, final SecurityContext securityContext) {
+ var account = this.authenticator.verify(id, credential);
+ if (account != null) {
+ securityContext.authenticationComplete(account, "IdentityAuthenticationManager", true);
+ return AuthenticationMechanism.AuthenticationMechanismOutcome.AUTHENTICATED;
+ } else {
+ securityContext.authenticationFailed("authentication failed", getMechanismName());
+ return AuthenticationMechanismOutcome.NOT_AUTHENTICATED;
+ }
+}
+```
\ No newline at end of file
diff --git a/docs/v7/plugins/authenticators.adoc b/docs/v7/plugins/authenticators.adoc
new file mode 100644
index 00000000..532259a8
--- /dev/null
+++ b/docs/v7/plugins/authenticators.adoc
@@ -0,0 +1,70 @@
+---
+title: Authenticators
+layout: docs-adoc
+menu: framework
+---
+
+Authenticators verify credentials passed by the client and build the `Account`.
+
+An Authentication Mechanism can delegate the verification of credentials to an Authenticator. For example, the default configuration enables the `basicAuthMechanism` that uses by default the `mongoRealmAuthenticator`.
+
+RESTHeart provides two implementations of `Authenticator`:
+
+* link:https://github.com/SoftInstigate/restheart/blob/master/security/src/main/java/org/restheart/security/plugins/authenticators/FileRealmAuthenticator.java[FileRealmAuthenticator] that handle credentials in a configuration file
+* link:https://github.com/SoftInstigate/restheart/blob/master/security/src/main/java/org/restheart/security/plugins/authenticators/MongoRealmAuthenticator.java[MongoRealmAuthenticator] that handle credentials on a MongoDB collection.
+
+== Implementations
+
+The Authenticator class must implement the `org.restheart.plugins.security.Authenticator` interface.
+
+[source,java]
+----
+public interface Authenticator extends IdentityManager {
+ @Override
+ public Account verify(Account account);
+
+ @Override
+ public Account verify(String id, Credential credential);
+
+ @Override
+ public Account verify(Credential credential);
+}
+----
+
+== Registering
+
+The Authenticator class must be annotated with `@RegisterPlugin`:
+
+[source,java]
+----
+@RegisterPlugin(name="myAuthenticator",
+ description = "my custom authenticator")
+public class MyAuthenticator implements Authenticator {
+
+}
+----
+
+== Configuration
+
+The Authenticator can receive parameters from the configuration file using the `@Inject("config")` annotation:
+
+[source,java]
+----
+@Inject("config")
+private Map config;
+
+@OnInit
+public void init() throws ConfigurationException {
+ // get configuration arguments
+ int number = argValue(this.config, "number");
+ String string = argValue(this.config, "string");
+}
+----
+
+The parameters are defined in the configuration using the name of the authenticator as defined by the `@RegisterPlugins` annotation:
+
+```yaml
+myAuthenticator:
+ number: 10
+ string: a string
+```
\ No newline at end of file
diff --git a/docs/v7/plugins/authorizers.adoc b/docs/v7/plugins/authorizers.adoc
new file mode 100644
index 00000000..46bf9378
--- /dev/null
+++ b/docs/v7/plugins/authorizers.adoc
@@ -0,0 +1,79 @@
+---
+title: Authorizers
+layout: docs-adoc
+menu: framework
+---
+
+Authorizers check if the authenticated client can execute the request according to the security policy.
+
+RESTHeart provides two implementations of `Authorizer`:
+
+* link:https://github.com/SoftInstigate/restheart/blob/master/security/src/main/java/org/restheart/security/authorizers/FileAclAuthorizer.java[FileAclAuthorizer] that handle the ACL in a configuration file
+* link:https://github.com/SoftInstigate/restheart/blob/master/security/src/main/java/org/restheart/security/authorizers/MongoAclAuthorizer.java[MongoAclAuthorizer] that handle the ACL on a MongoDb collection.
+
+Multiple Authorizers can be enabled; an Authorizer can be either a `VETOER` or an `ALLOWER`.
+
+IMPORTANT: A request is allowed when no `VETOER` denies it and any `ALLOWER` allows it.
+
+== Implementation
+
+The Authorizer implementation class must implement the `org.restheart.plugins.security.Authorizer` interface.
+
+[source,java]
+----
+public interface Authorizer extends ConfigurablePlugin {
+
+ /**
+ *
+ * @param request
+ * @return true if request is allowed
+ */
+ boolean isAllowed(final Request request);
+
+ /**
+ *
+ * @param request
+ * @return true if not authenticated user won't be allowed
+ */
+ boolean isAuthenticationRequired(final Request request);
+}
+----
+
+=== Registering
+
+The Authorizer class must be annotated with `@RegisterPlugin`:
+
+[source,java]
+----
+@RegisterPlugin(name="myAuthorizer",
+ description = "my custom authorizer",
+ authorizerType = ALLOWER)
+public class MyAuthorizer implements Authorizer {
+
+}
+----
+
+=== Configuration
+
+The Authorizer can receive parameters from the configuration file using the `@Inject("config")` annotation:
+
+[source,java]
+----
+@Inject("config")
+private Map config;
+
+@OnInit
+public void init() throws ConfigurationException {
+ // get configuration arguments
+ int number = argValue(this.config, "number");
+ String string = argValue(this.config, "string");
+}
+----
+
+The parameters are defined in the configuration using the name of the authorizer as defined by the `@RegisterPlugins` annotation:
+
+```yaml
+myAuthorizer:
+ number: 10
+ string: a string
+```
\ No newline at end of file
diff --git a/docs/v7/plugins/core-plugins-js.adoc b/docs/v7/plugins/core-plugins-js.adoc
new file mode 100644
index 00000000..b73581aa
--- /dev/null
+++ b/docs/v7/plugins/core-plugins-js.adoc
@@ -0,0 +1,258 @@
+---
+title: Develop Core Plugins in JavaScript
+layout: docs-adoc
+menu: framework
+---
+:page-liquid:
+
+== Introduction
+
+_Services_ and _Interceptors_ can be developed in _JavaScript_ and _TypeScript_ when running RESTHeart with the GraalVM or using RESTHeart native.
+
+TIP: See link:https://github.com/SoftInstigate/restheart/tree/master/examples/js-plugin[example JS plugins]
+
+NOTE: The default RESTHeart native binaries, can only be extended with JavaScript plugins. With Java plugins, you need to build RESTHeart and the plugins with the `native-image` tool. See link:https://restheart.org/docs/graalvm#build-restheart-with-custom-plugins-as-native-image[Build RESTHeart with custom plugins as native-image]
+
+== RESTHeart Concurrency Model
+
+RESTHeart is a multi-threaded application and it handles each request in a dedicated thread. This makes all code running in a request thread safe, and this also applies to JavaScript services and interceptors.
+
+This is different than usual JavaScript concurrency model, where all code is usually executed in a single thread and requires asynchronous programming, with callbacks, promises, observable, etc.
+
+In RESTHeart, you can write simple JavaScript code that also includes blocking calls, without incurring in performance problems.
+
+== Service
+
+The JavaScript code that defines a `Service` must export the object `options` and the function `handle(req, res)`.
+
+The resulting service will be a special instance of link:https://javadoc.io/doc/org.restheart/restheart-commons/latest/org/restheart/plugins/StringService.html[StringService], that delegates the handling logic to the JavaScript code. For this reason, the request and response bodies are treated as strings.
+
+[source,javascript]
+----
+export const options = {
+ name: "helloWorldService",
+ description: "just another Hello World",
+ uri: "/hello"
+}
+
+export function handle(req, res) {
+ res.setContent(`{ "msg": `Hello ${rc.name || 'World'}` } `);
+ res.setContentTypeAsJson();
+}
+----
+
+=== The object `options`
+
+The `options` object must contain the following properties:
+
+[.table]
+|===
+|param |description |mandatory |default value
+
+|`name`
+|the name of the service
+|yes
+|*none*
+
+|`description`
+|description of the service
+|yes
+|*none*
+
+|`uri`
+|the uri of the service
+|yes
+|*none*
+
+|`secured`
+|`true` to require successful authentication and authorization to be invoked;
+|no
+|`false`
+
+|`matchPolicy`
+| `PREFIX` to match request paths starting with `/`,`EXACT` to only match the request path `/` | no | `PREFIX`
+
+|`modulesReplacements`
+| experimental support for module replacements. See *Node.js core modules mockups* on link:https://www.graalvm.org/22.0/reference-manual/js/Modules/[Using JavaScript Modules and Packages in GraalVM JavaScript] for modules. Example `buffer:my-buffer-implementation` | no | `""` (empty) |
+
+|===
+
+=== The function `handle(req, res)`
+
+The `handle` functions accepts two parameters: the request and the response. These are Java objects of link:https://javadoc.io/doc/org.restheart/restheart-commons/latest/org/restheart/exchange/StringRequest.html[StringRequest] and link:https://javadoc.io/doc/org.restheart/restheart-commons/latest/org/restheart/exchange/StringResponse.html[StringResponse] respectively.
+
+== Interceptor
+
+The JavaScript code that defines an `Interceptor` export the object `options` and the functions `handle(req, res)` and `resolve(req)`.
+
+[source,javascript]
+----
+export const options = {
+ name: "helloWorldInterceptor",
+ description: "modifies the response of helloWorldService",
+ interceptPoint: "RESPONSE"
+}
+
+export function handle(request, response) {
+ const rc = JSON.parse(response.getContent() || '{}');
+
+ let modifiedBody = {
+ msg: rc.msg + ' from Italy with Love';
+ }
+
+ response.setContent(JSON.stringify(modifiedBody));
+ response.setContentTypeAsJson();
+}
+
+export function resolve(request) {
+ return request.isHandledBy("helloWorldService");
+}
+----
+
+=== The object `options`
+
+The `options` object must contain the following properties:
+
+[.table]
+|===
+|param |description |mandatory |default value
+
+|`name`
+|the name of the interceptor
+|yes
+|*none*
+
+|`description`
+|description of the interceptor
+|yes
+|*none*
+
+|`interceptPoint`
+| the intercept point: `REQUEST_BEFORE_AUTH`, `REQUEST_AFTER_AUTH`, `RESPONSE`, `RESPONSE_ASYNC` | no | REQUEST_AFTER_AUTH
+
+|`pluginClass`
+| the class of the interceptor that must match the service to intercept (e.g. `MongoInterceptor` can intercept a request handled by the `MongoService`), `StringInterceptor`, `BsonInterceptor`, `ByteArrayProxyInterceptor`, `CsvInterceptor`, `JsonInterceptor`, `MongoInterceptor`
+|no
+|`StringInterceptor`
+
+
+|`modulesReplacements`
+| experimental support for module replacements. See *Node.js core modules mockups* on link:https://www.graalvm.org/22.0/reference-manual/js/Modules/[Using JavaScript Modules and Packages in GraalVM JavaScript] for modules. Example `buffer:my-buffer-implementation` | no | `""` (empty) |
+
+|===
+
+=== The function `resolve(req)`
+
+The function `resolve()` accepts one parameter `req`, a Java object of the concrete subclass of link:https://javadoc.io/doc/org.restheart/restheart-commons/latest/org/restheart/exchange/Request.html[Request] defined by the parameter `pluginClass`, e.g. with `pluginClass: "StringInterceptor"`, the request class is link:https://javadoc.io/doc/org.restheart/restheart-commons/latest/org/restheart/exchange/StringRequest.html[StringRequest].
+
+An interceptor of a given class, can intercept requests handled by all services with matching types, e.g. `MongoInterceptor` can intercept requests handled by the `MongoService`.
+
+When `resolve()` returns `true` the interceptor will be actually invoked, i.e. this function allows to select the requests to intercept.
+
+=== The function `handle(req, res)`
+
+The `handle()` functions accepts two parameters: the request and the response.
+These a Java objects of the concrete subclasses of link:https://javadoc.io/doc/org.restheart/restheart-commons/latest/org/restheart/exchange/Request.html[Request] and link:https://javadoc.io/doc/org.restheart/restheart-commons/latest/org/restheart/exchange/Response.html[Response] respectively. For the default `pluginClass: "StringInterceptor"`, these are link:https://javadoc.io/doc/org.restheart/restheart-commons/latest/org/restheart/exchange/StringRequest.html[StringRequest] and link:https://javadoc.io/doc/org.restheart/restheart-commons/latest/org/restheart/exchange/StringResponse.html[StringResponse] respectively.
+
+== Packaging
+
+The plugins js files must be placed in a folder with a `package.json` file.
+
+NOTE: a single plugin folder can contain multiple Services and Interceptors.
+
+The `package.json` muse declare the services in the `rh:services` array and interceptors in the `rh:interceptors` array.
+
+[source,json]
+----
+{
+ "name": "restheart-js-foo",
+ "version": "1.0.0",
+ "description": "test js plugins for RESTHeart",
+ "rh:services": [ "foo.js" ],
+ "rh:interceptors": [ "foo-interceptor.js" ]
+}
+----
+
+== Modules
+
+The plugins can use npm `modules` via `require` statements. See link:https://github.com/SoftInstigate/restheart/blob/master/examples/js-plugin/require-module-service.mjs[require-module-service.mjs] for an example.
+
+IMPORTANT: The imported modules cannot use functionalities that are available in Node.js’ built-in modules (e.g., 'fs' and 'buffer', etc.).
+
+For instance, you cannot use the module `http`, and there is no pure JS implementation available. In this case, you can rely on <> and use the standard Java libraries and all the libraries that are available in RESTHeart.
+
+See link:https://www.graalvm.org/22.0/reference-manual/js/Modules/[GraalVM Modules] for more details.
+
+== Deploy
+
+To the JavaScript plugin, just copy the folder containing the scripts and the file `package.json` into the `plugins` directory of RESTHeart.
+
+NOTE: JS plugins can be added or updated without requiring to restart the server, ie RESTHeart supports JS plugins hot deployment.
+
+If you modify the code, you can force RESTHeart to update it by touching the plugin folder.
+
+[source,bash]
+$ touch plugins/my-plugin
+
+== Configuration parameters
+
+It is possible to pass configuration parameters to a plugin by defining them in the RESTHeart's configuration file using the plugin's name:
+
+[source,yml]
+----
+foo: # <-- name of the plugin
+ arg: value
+----
+
+The arguments are available in the `pluginArgs` object.
+
+[source,javascript]
+----
+const arg = pluginArgs.arg
+----
+
+== Java/JavaScript interoperability [[interop]]
+
+GraalVM allows to execute JavaScript code from RESTHeart and allows interoperability with Java code.
+
+This means that all the Java classes shipped with RESTHeart can be used in JavaScript code.
+
+For example, see the link:https://github.com/SoftInstigate/restheart/blob/master/examples/js-plugin/http-client.mjs[http-client.mjs] plugins, which uses `java.net.http.HttpClient` to execute an HTTP request.
+
+== MongoDB driver
+
+The MongoDb Java driver, configured by RESTHeart configuration file and already connected to MongoDB, is available in the JavaScript code as `mclient`.
+
+See link:https://github.com/SoftInstigate/restheart/blob/master/examples/js-plugin/mclient-service.mjs[mclient-service.mjs] for an example of how to use it.
+
+== Logging
+
+The RESTHeart Java logger can be used from JavaScript code.
+
+[source,javascript]
+----
+LOGGER.debug("pluginArgs {}", pluginArgs);
+----
+
+Pay attention to logging null values. With:
+
+[source,javascript]
+----
+var foo = null;
+LOGGER.debug("this is null {}", foo);
+----
+
+An error will be raised.
+
+[source,bash]
+----
+org.graalvm.polyglot.PolyglotException: TypeError: invokeMember (debug) on ch.qos.logback.classic.Logger@697713cb failed due to: Multiple applicable overloads found for method name debug...
+----
+
+To avoid it, use the following code:
+
+[source,javascript]
+----
+var foo = null;
+LOGGER.debug("this is null {}", foo ? foo : "null");
+----
\ No newline at end of file
diff --git a/docs/v7/plugins/core-plugins.adoc b/docs/v7/plugins/core-plugins.adoc
new file mode 100644
index 00000000..aad40248
--- /dev/null
+++ b/docs/v7/plugins/core-plugins.adoc
@@ -0,0 +1,456 @@
+---
+title: Develop Core Plugins
+layout: docs-adoc
+menu: framework
+---
+
+== Introduction
+
+Plugins allow to extend RESTHeart:
+
+- **Services** extend the API adding web services.
+- **Interceptors** snoop and modify requests and responses at different stages of the request lifecycle.
+- **Initializers** execute initialization logic at system startup time.
+- **Providers** provide object to other plugins via the `@Inject` annotation.
+
+It is also possible developing security plugins to customize the security layer. Refer to link:/docs/plugins/security-plugins[Develop Security Plugins] for more information.
+
+For code examples of Plugins please refer to link:https://github.com/SoftInstigate/restheart/tree/master/examples[RESTHeart Examples] repository on GitHub.
+
+TIP: Watch link:https://www.youtube.com/watch?v=GReteuiMUio&t=0s[Introduction]
+
+=== Dependency
+
+The only required dependency to develop a plugin is `restheart-commons`.
+
+With maven:
+
+[source,xml]
+----
+
+ org.restheart
+ restheart-commons
+ VERSION
+
+----
+
+=== @RegisterPlugin annotation
+
+All plugins must be a annotated with `@RegisterPlugin` to:
+- allow RESTHeart to find plugins' implementation classes in deployed jars (see link:/docs/plugins/deploy[How to Deploy Plugins])
+- specify parameters such us the URI of a `Service` or the intercept point of an `Interceptor`.
+
+An example follows:
+
+[source,java]
+----
+@RegisterPlugin(name = "foo",
+ description = "just an example service",
+ defaultUri="/foo", // optional, default /
+ secure=false, // optional, default false
+ enabledByDefault=false) // optional, default true
+public class MyPlugin implements JsonService {
+...
+}
+----
+
+The following table describes the arguments of the annotation:
+
+[options="header"]
+[cols="2,1,3,1,1"]
+|===
+|param |plugin |description |mandatory |default value
+|`name`
+|all
+|the name of the plugin
+|yes
+|*none*
+|`description`
+|all
+|description of the plugin
+|yes
+|*none*
+|`enabledByDefault`
+|all
+|`true` to enable the plugin; can be overridden by the plugin configuration option `enabled`
+|no
+|`true`
+|`defaultURI`
+|service
+|the default URI of the Service; can be overridden by the service configuration option `uri`
+|no
+|/<srv-name>
+|`matchPolicy`
+|service
+|`PREFIX` to match request paths starting with `/`,`EXACT` to only match the request path `/`
+|no
+|`PREFIX`
+|`secure`
+|service
+|`true` to require successful authentication and authorization to be invoked; can be overridden by the service configuration option `secure`
+|no
+|`false`
+|`dontIntercept`
+|service
+|list of interceptPoints to be executed on requests handled by the service, e.g. `dontIntercept = { InterceptPoint.REQUEST_BEFORE_AUTH, InterceptPoint.RESPONSE }`
+|no
+|`{}`
+|`interceptPoint`
+|interceptor
+|the intercept point: `REQUEST_BEFORE_AUTH`, `REQUEST_AFTER_AUTH`, `RESPONSE`, `RESPONSE_ASYNC`
+|no
+|REQUEST_AFTER_AUTH
+|`initPoint`
+|initializer
+|specify when the initializer is executed: `BEFORE_STARTUP`, `AFTER_STARTUP`
+|no
+|`AFTER_STARTUP`
+|`requiresContent`
+|proxy interceptor
+|Only used by Interceptors of proxied resources (the content is always available to Interceptor of Services) Set it to true to make available the content of the request (if interceptPoint is REQUEST_BEFORE_AUTH or REQUEST_AFTER_AUTH) or of the response (if interceptPoint is RESPONSE or RESPONSE_ASYNC)
+|no
+|`false`
+|`priority`
+|interceptor, initializer
+|the execution priority (less is higher priority)
+|no
+|`10`
+|`blocking`
+|service
+|With blocking = `false` the execution of the service is not dispatched to a working thread and executed by the io-thread, thus avoiding the overhead of the thread handling and switching.
+|no
+|`true`
+|`authorizerType`
+|authorizer
+|`ALLOWER` can authorize a request unless no `VETOER` vetoes it.
+|no
+|ALLOWER
+|===
+
+TIP: Watch link:https://www.youtube.com/watch?v=GReteuiMUio&t=108s[Dependencies, annotations and parameters]
+
+=== Plugin Configuration
+
+A plugins has a name as defined by the the `@RegisterPlugin` annotation. To define a configuration object for a plugin just use its name in the configuration:
+
+[source,yml]
+----
+ping:
+ enabled: true
+ secure: false
+ uri: /ping
+ msg: 'Ping!'
+----
+
+`enabled` `secure` and `uri` are special configuration options that are automatically managed by RESTHeart:
+
+- *enabled*: for enabling or disabling the plugin via configuration overwriting the `enabledByDefault` property of `@RegisterPlugin`
+- *uri*: applies to Services to bind them to the URI overwriting the `defaultUri` property of `@RegisterPlugin`
+- *secure*: applies to Services, with `secure: true` the service request goes thought the authentication and authorization phases, with `secure: false` the service is fully open.
+
+WARNING: `secure` is `false` by default. If you don't specify `secure=true` your Service is fully open. If your service needs to be protected either define `secure=true` in the `@RegisterPlugin` annotation of add a configuration for it with `secure: true`
+
+The plugin consumes the configuration with a field annotated with `@Inject("conf")`:
+
+[source,java]
+----
+@Inject("config")
+Map config;
+
+@OnInit
+public void init() throws ConfigurationException {
+ this.msg = argValue(this.config, "msg");
+}
+----
+
+`argValue()` is an helper method to simplify retrieving the value of the configuration argument.
+
+TIP: Watch link:https://www.youtube.com/watch?v=GReteuiMUio&t=356s[Plugin configuration]
+
+### Dependency injection
+
+Available providers allow to inject the following objects:
+
+- `@Inject("config")` - injects the plugins configuration as a `Map`
+- `@Inject("rh-config")` - injects the RESTHeart `org.restheart.configuration.Configuration` object.
+- `@Inject("registry")` - injects the `PluginsRegistry` singleton that allows a plugin to get the reference of other plugins.
+- `@Inject("mclient")` - injects the `MongoClient` object that has been already initialized and connected to MongoDB by the `mongo-client-provider`.
+- `@Inject("mclient-reactive")` - injects the reactive `MongoClient` object that has been already initialized and connected to MongoDB by the `mongo-client-provider`.
+
+[source,java]
+----
+@Inject("registry")
+private PluginsRegistry registry;
+----
+
+[source,java]
+----
+@Inject("mclient")
+private MongoClient mclient;
+----
+
+=== Request and Response Generic Classes
+
+*Services* and *Interceptor* are generic classes. They use type parameters for `Request` and `Response` classes.
+
+Many concrete implementations of specialized `Request` and `Response` exist in the `org.restheart.exchange` package to simplify development:
+
+- `JsonRequest` and `JsonResponse`
+- `BsonRequest` and `BsonResponse`
+- `MongoRequest` and `MongoResponse`
+- `ByteArrayRequest` and `ByteArrayResponse`
+- `StringRequest` and `StringResponse`
+- `BsonFromCsvRequest`
+- `UninitializedRequest` and `UninitializedResponse`
+
+Those implementations differ on the data type used to hold the request and response content. For example, `ByteArrayRequest` and `BsonRequest` hold content as `byte[]` and `BsonValue` respectively.
+
+Different implementation can also provide some helper methods to cope with specific request parameter. For instance, the `MongoRequest`, i.e. the request used by the MongoService, has the method `getPageSize()` because this is a query parameter used by that service.
+
+When a request hits RESTHeart, it determines which service will handle it. The Service implementation is responsible of instantiating the correct Request and Response objects that will be used along the whole exchange processing chain.
+
+
+== Services
+
+Depending on the content type, the Service class implements one of the specialized `org.restheart.plugins.Service` interfaces. The following implementation are provided by `restheart-commons`:
+
+- `ByteArrayService`
+- `JsonService`
+- `BsonService`
+
+The code of example link:https://github.com/SoftInstigate/restheart/tree/master/examples/mongo-status-service[mongo-status-service] implementing `BsonService` and using the `MongoClient` obtained via `@Inject("mclient")` follows:
+
+[source,java]
+----
+@RegisterPlugin(
+ name = "serverstatus",
+ description = "returns MongoDB serverStatus",
+ enabledByDefault = true,
+ defaultURI = "/status")
+public class MongoServerStatusService implements BsonService {
+
+ private static final Logger LOGGER = LoggerFactory.getLogger(MongoServerStatusService.class);
+
+ @Inject("mclient")
+ private MongoClient mongoClient;
+
+ private static final BsonDocument COMMAND = document().put("serverStatus", 1);
+
+ @Override
+ public void handle(BsonRequest request, BsonResponse response) throws Exception {
+ if (request.isGet()) {
+ var serverStatus = mongoClient.getDatabase("admin").runCommand(COMMAND, BsonDocument.class);
+
+ response.setContent(serverStatus);
+ response.setStatusCode(HttpStatus.SC_OK);
+ response.setContentTypeAsJson();
+ } else {
+ // Any other HTTP verb is a bad request
+ response.setStatusCode(HttpStatus.SC_BAD_REQUEST);
+ }
+ }
+}
+----
+
+The key method is `handle()` that is executed when a request to the service URI hits RESTHeart.
+
+=== Create Service with custom generic type
+
+To implement a Service that handles different types of Request and Response, it must implement the base `Service` interface.
+
+The base `Service` interface requires to implement methods to initialize and retrieve the Request and Response objects.
+
+The following example shows how to handle XML content:
+
+[source,java]
+----
+@RegisterPlugin(name = "myXmlService",
+ description = "example service consuming XML requests",
+ enabledByDefault = true,
+ defaultURI = "/xml")
+public class MyXmlService implements Service {
+ @Override
+ default Consumer requestInitializer() {
+ return e -> XmlRequest.init(e);
+ }
+
+ @Override
+ default Consumer responseInitializer() {
+ return e -> XmlResponse.init(e);
+ }
+
+ @Override
+ default Function request() {
+ return e -> XmlRequest.of(e);
+ }
+
+ @Override
+ default Function response() {
+ return e -> XmlResponse.of(e);
+ }
+}
+----
+
+The example follows a pattern that delegates the actual initialization (in `requestInitializer()` and `responseInitializer()`) and retrieval of the object from the exchange (in `request()` and `response()`) to the concrete class, as follows:
+
+[source,java]
+----
+public class XmlRequest extends ServiceRequest {
+ private XmlRequest(HttpServerExchange exchange) {
+ super(exchange);
+ }
+
+ public static XmlRequest init(HttpServerExchange exchange) {
+ var ret = new XmlRequest(exchange);
+
+ try {
+ ret.injectContent();
+ } catch (Throwable ieo) {
+ ret.setInError(true);
+ }
+
+ return ret;
+ }
+
+ public static XmlRequest of(HttpServerExchange exchange) {
+ return of(exchange, XmlRequest.class);
+ }
+
+ public void injectContent() throws SAXException, IOException {
+ var dBuilder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
+ var rawContent = ChannelReader.read(wrapped.getRequestChannel());
+
+ setContent(dBuilder.parse(rawContent)ml);
+ }
+}
+----
+
+In the constructor a call to `super(exchange)` attaches the object to the `HttpServerExchange`. The object is retrieved using the inherited `of()` method that gets the instance attachment from the `HttpServerExchange`. This is fundamental for two reasons: first the same request and response objects must be shared by the all handlers of the processing chain. Second, this avoid the need to parse the content several times for performance reasons.
+
+TIP: Watch link:https://www.youtube.com/watch?v=GReteuiMUio&t=680s[Services]
+
+== Interceptors
+
+Interceptors allow to snoop and modify requests and responses at different
+stages of the request lifecycle as defined by the interceptPoint parameter of
+the annotation `@RegisterPlugin`.
+
+An interceptor can intercept either proxied requests or requests handled by Services.
+
+An interceptor, but `WildcardInterceptor`, can intercept requests handled by a Service when its request and response types are equal to the ones declared by the Service.
+
+An interceptor can intercept a proxied request, when its request and response
+types extends `BufferedRequest` and `BufferedResponse`.
+
+The following implementation are provided by `restheart-commons`:
+
+- `WildcardInterceptor` intercepts requests handled by any service
+- `ByteArrayInterceptor` intercepts requests handled by services implementing `ByteArrayService`
+- `JsonInterceptor` intercepts requests handled by services implementing `JsonService`
+- `BsonInterceptor` intercepts requests handled by services implementing `BsonService`
+- `MongoInterceptor` intercepts requests handled by the MongoService
+
+The last one is particularly useful as it allows intercepting requests to the MongoDb API.
+
+[source,java]
+----
+@RegisterPlugin(name = "secretFilter",
+ interceptPoint = InterceptPoint.RESPONSE,
+ description = "removes the property 'secret' from GET /coll")
+public class ReadOnlyPropFilter implements MongoInterceptor {
+ @Override
+ public void handle(MongoRequest request, MongoResponse response) throws Exception {
+ if (response.getContent().isDocument()) {
+ response.getContent().asDocument().remove("secret");
+ } else if (request.getContent().isArray()) {
+ response.getContent().asArray().stream()
+ .map(doc -> doc.asDocument())
+ .forEach(doc -> doc.remove("secret"));
+ }
+ }
+
+ @Override
+ public boolean resolve(MongoRequest request, MongoResponse response) {
+ return request.isGet()
+ && response.getContent() != null
+ && "coll".equalsIgnoreCase(request.getCollectionName());
+ }
+}
+----
+
+The `handle()` method is invoked only if the `resolve()` method returns true.
+
+TIP: Watch link:https://www.youtube.com/watch?v=GReteuiMUio&t=986s[Interceptors]
+
+== Initializers
+
+An _Initializer_ allows executing custom logic at startup time.
+
+The Initializer implementation class must extend the `org.restheart.plugins.Initializer` interface:
+
+[source,java]
+----
+public interface Initializer extends ConfigurablePlugin {
+ public void init();
+}
+----
+
+With the following code the Initializer hangs restheart startup until the user confirms.
+
+[source,java]
+----
+@RegisterPlugin(name = "confirmStartupInitializer",
+ description = "hangs restheart startup until the user hits "
+ priority = 100,
+ initPoint = InitPoint.BEFORE_STARTUP)
+public class confirmStartupInitializer implements Initializer {
+ public void init() {
+ System.out.println("Hit to start RESTHeart");
+ System.console().readLine();
+ }
+}
+----
+
+TIP: Watch https://www.youtube.com/watch?v=GReteuiMUio&t=1274s[Initializers]
+
+== Providers
+
+`@Inject` works together with the plugin type `Provider`, as in the following example:
+
+Given the following `Provider`:
+
+[source,java]
+----
+RegisterPlugin(name="hello-world-message", description="a dummy provider")
+class MyProvider implements Provider {
+ @Override
+ public String get(PluginRecord caller) {
+ return "Hello World!";
+ }
+}
+----
+
+We can inject it into a Plugin with the `@Inject` annotation:
+
+[source,java]
+----
+@RegisterPlugin(name = "greetings", description = "just another Hello World")
+public class GreeterService implements JsonService {
+ @Inject("hello-world-message")
+ private String message;
+
+ @OnInit
+ public void init() {
+ // called after all @Inject fields are resolved
+ }
+
+ @Override
+ public void handle(JsonRequest req, JsonResponse res) {
+ switch(req.getMethod()) {
+ case GET -> res.setContent(object().put("message", message));
+ case OPTIONS -> handleOptions(req);
+ default -> res.setStatusCode(HttpStatus.SC_METHOD_NOT_ALLOWED);
+ }
+ }
+}
+----
diff --git a/docs/v7/plugins/deploy.adoc b/docs/v7/plugins/deploy.adoc
new file mode 100644
index 00000000..9a37f690
--- /dev/null
+++ b/docs/v7/plugins/deploy.adoc
@@ -0,0 +1,198 @@
+---
+title: How to deploy Plugins
+layout: docs-adoc
+menu: framework
+---
+
+== Introduction
+
+This section provides information on how to package and deploy plugins.
+
+NOTE: To quick start a new Java plugin, you can clone the link:https://github.com/SoftInstigate/restheart-plugin-skeleton[plugin skeleton repository]. It contains a basic skeleton for a plugin and an helper script that allows to build, deploy the plugin.
+
+== Java Plugins
+
+Java and Kotlin plugins must be packaged as jar files.
+
+To deploy a plugin, *just copy its jar file into the directory `./plugins` of RESTHeart*.
+
+IMPORTANT: After deploying a jar plugin, you must restart RESTHeart.
+
+=== Example
+
+As an example we will build and deploy the simple link:https://github.com/SoftInstigate/restheart/tree/master/examples/greeter-service[Greeter Service] example plugin.
+
+Let's clone the RESTHeart repository that includes the `examples` directory and build the `greeter-service` example.
+
+[source,bash]
+----
+$ git clone --depth 1 git@github.com:SoftInstigate/restheart.git
+$ cd restheart/examples/greeter-service
+$ ../mvnw clean package
+----
+
+The built plugin jar file is `target/greeter-service.jar`. Copy it into the RESTHeart plugins directory.
+
+[source,bash]
+$ cp target/greeter-service.jar /plugins
+
+Restarting RESTHeart will produce the following log message:
+
+[source,bash]
+----
+$ java -jar restheart.jar
+INFO org.restheart.Bootstrapper - Starting RESTHeart instance default
+...
+INFO org.restheart.plugins.PluginsFactory - Found plugin jar file:/Users/uji/development/restheart/core/target/plugins/greeter-service.jar
+...
+INFO org.restheart.Bootstrapper - URI /greetings bound to service greetings, secured: false, uri match PREFIX
+....
+----
+
+Let's test it (for example, using the link:https://httpie.io[httpie] client):
+
+[source,bash]
+----
+$ http -b :8080/greetings
+{
+ "message": "Hello World!"
+}
+----
+
+=== External dependencies
+
+The link:https://github.com/SoftInstigate/restheart/tree/master/examples/random-string-service[Random String Service] example plugin shows how to add to the classpath an external dependency required by a plugin.
+
+By _external dependency_ we mean a dependency that is not included in restheart.jar, thus it must be added to the classpath for the service to work.
+
+IMPORTANT: *To add an external dependency to the classpath just copy it into the RESTHeart plugins directory*.
+
+The plugin link:https://github.com/SoftInstigate/restheart/blob/master/examples/random-string-service/pom.xml[pom.xml] file defines the following dependencies:
+
+[source,xml]
+----
+
+
+ org.restheart
+ restheart-commons
+ provided
+
+
+ org.apache.commons
+ commons-lang3
+ 3.10
+
+
+----
+
+The scope of `restheart-commons` is `provided` since it is provided by the RESTHeart runtime, together with many others.
+
+To get a list of all the dependencies included in the RESTHeart runtime, you can use the following command:
+
+[source,bash]
+----
+$ cd /core
+$ ../mvnw dependency:tree -Dscope=compile
+----
+
+On the other side, the scope of `commons-lang3` is `compile` as it is not provided by the RESTHeart runtime. Thus it is an external dependency and it must be copied into the RESTHeart plugins directory.
+
+Let's build the plugin.
+
+[source,bash]
+----
+$ git clone --depth 1 git@github.com:SoftInstigate/restheart.git
+$ cd restheart/examples/random-string-service
+$ ../mvnw clean package
+----
+
+The link:https://github.com/SoftInstigate/restheart/blob/master/examples/random-string-service/pom.xml[pom.xml] uses the `maven-dependency-plugin` to copy the jars of the external dependencies into the directory `target/lib`
+
+To deploy the plugin copy its jar file and the jars of the dependencies into the plugins directory.
+
+[source,bash]
+$ cp target/random-string-service.jar target/lib/* /plugins/
+
+== JavaScript Plugins
+
+IMPORTANT: JavaScript plugins can be deployed only running link:/docs/graalvm/#run-restheart-with-graalvm[RESTHeart on GraalVM] and on restheart native.
+
+NOTE: Deploying JavaScript plugins does not require restarting RESTHeart, they can be hot-deployed! To update an already deployed JavaScript plugin, `touch` its root directory.
+
+The JavaScript plugins are packaged in directories containing the JavaScript files and the `package.json` file.
+
+The JavaScript plugin link:https://github.com/SoftInstigate/restheart/blob/master/examples/credit-card-hider/README.md[Credit Card Hider] is an example.
+
+Its link:https://github.com/SoftInstigate/restheart/blob/master/examples/credit-card-hider/package.json[package.json] file declares the Interceptor `cc-hider.js` via the property `rh:interceptors` (Services are declared with `rh:services`):
+
+[source,json]
+----
+{
+ "name": "restheart-demo-cc-hider",
+ "version": "1.0.0",
+ "description": "demo plugins for RESTHeart",
+ "rh:interceptors": [ "cc-hider.js" ]
+}
+----
+
+Let's deploy it.
+
+[source,bash]
+----
+$ git clone --depth 1 git@github.com:SoftInstigate/restheart.git
+$ cp -r restheart/examples/credit-card-hider /plugins
+----
+
+RESTHeart log files shows the following message:
+
+[source,bash]
+----
+INFO o.r.polyglot.PolyglotDeployer - Added interceptor ccHider, description: hides credit card numbers
+----
+
+Refer to the Credit Card Hider link:https://github.com/SoftInstigate/restheart/blob/master/examples/credit-card-hider/README.md[README.md] for more information on how to play with this JavaScript plugin.
+
+NOTE: More JavaScript plugins examples are available in the link:https://github.com/SoftInstigate/restheart/tree/master/examples/js-plugin[examples/js-plugin] directory of RESTHeart repository.
+
+== Deploy Java plugins on RESTHeart Native
+
+RESTHeart native can run JavaScript plugins as previously described.
+
+However *you cannot deploy Java plugins in RESTHeart native by merely copying jars file into the plugins directory* (this will be allowed in the future).
+
+In order to use Java plugins on RESTHeart native you must build them as native image together with RESTHeart.
+
+The repository link:https://github.com/SoftInstigate/restheart-plugin-skeleton[restheart-plugin-skeleton] defines a skeleton project for Java plugins. Its link:https://github.com/SoftInstigate/restheart-plugin-skeleton/blob/master/pom.xml[pom.xml] maven file defines the `native` profile that uses the `native-maven-plugin` to build the native image, defining the required dependencies.
+
+Fork the repository
+
+[source,bash]
+----
+$ git clone git@github.com:SoftInstigate/restheart-plugin-skeleton.git
+$ cd restheart-plugin-skeleton
+----
+
+Make sure you are using GraalVM.
+
+[source,bash]
+----
+$ java -version
+java version "17.0.8" 2023-07-18 LTS
+Java(TM) SE Runtime Environment Oracle GraalVM 17.0.8+9.1 (build 17.0.8+9-LTS-jvmci-23.0-b14)
+Java HotSpot(TM) 64-Bit Server VM Oracle GraalVM 17.0.8+9.1 (build 17.0.8+9-LTS-jvmci-23.0-b14, mixed mode, sharing)
+----
+
+Make sure you have `native-image` and `graalvm.js` installed.
+
+[source,bash]
+----
+$ gu install native-image
+$ gu install graalvm.js
+----
+
+Build it.
+
+[source,bash]
+----
+$ ./mvnw clean package -Pnative
+----
diff --git a/docs/v7/plugins/dev-env.md b/docs/v7/plugins/dev-env.md
new file mode 100644
index 00000000..9dc0ed12
--- /dev/null
+++ b/docs/v7/plugins/dev-env.md
@@ -0,0 +1,76 @@
+---
+title: Development Environment Setup
+layout: docs
+menu: framework
+---
+
+
+
+* [Introduction](#introduction)
+* [Plugin Project Skeleton](#plugin-project-skeleton)
+* [HTTP Shell](#http-shell)
+
+
+
+
+{% include docs-head.html %}
+
+## Introduction
+
+Here at [SoftInstigate](https://softinstigate.com) we have developed many projects with RESTHeart.
+
+During our projects we have been constantly enhancing our development environment and building tools to make our life easier.
+
+This page summarizes our findings and provides you with links and tips to setup your development environment in the most effective way.
+
+## Plugin Project Skeleton
+
+You can start developing a plugin by forking the repository [restheart-plugin-skeleton](https://github.com/SoftInstigate/restheart-plugin-skeleton)
+
+This repository includes a sample service and provides you with the following features:
+
+{: .table }
+|feature|description|
+|-|-|
+|**Easy Execution**|A script allows to automatically download and run RESTHeart with your plugin. `docker compose` can be used to start MongoDB configured as a single instance Replica Set to enable transactions and change streams|
+|**Watch Mode**|You can develop in *Watch Mode* so that the code is automatically rebuilt, and RESTHeart automatically restarted as soon as you change a source or configuration file.|
+|**Notifications**| get notifications on OSX when the *watcher* builds and restarts RESTHeart, so you know when you can try your changes.|
+|**microD profile**|Start RESTHeart without the MongoDB Service. We call this profile *microD*, because it is an effective runtime environment for micro-services.|
+|**Debugging and Hot Code Replace**|RESTHeart runs in development mode, i.e. with the JVM configured for remote debugging. This also allows IDEs to dynamically apply Hot Code Replace, i.e, the code changes are automatically applied (to some extent) to the running service, without the need for rebuilding and restarting.|
+|**Native builds**|The skeleton `pom.xml` includes the native profile to build RESTHeart with the custom plugin as a native binary.|
+
+## HTTP Shell
+
+**HTTP Shell** provides developers with a modern alternative to HTTP clients for interacting with RESTHeart.
+
+{: .bs-callout.bs-callout-info}
+Download HTTP Shell from [https://github.com/SoftInstigate/http-shell](https://github.com/SoftInstigate/http-shell)
+
+Let's see it as something between a low-level command line interface, like curl or httpie, and a more user friendly GUI client, like Postman.
+
+The idea is that tools like curl are very powerful but a bit cumbersome, it is often hard for us to remember the exact syntax for each HTTP verb. HTTP Shell instead is still a command line interface, but with a much straightforward user experience.
+
+> HTTP Shell combines the power of familiar CLIs with visualizations in high-impact areas. HTTP Shell enables you to execute HTTP requests, manipulate complex JSON and YAML data models, integrate disparate tooling, and provides quick access to aggregate views of operational data.
+
+
+{: .img-fluid }
+
+### Commands
+
+{: .table }
+| command | description | example
+|---|---|---|
+| `h set auth ` | opens a dialog to sets the basic authentication credentials to use in further requests | `> set auth` |
+| `h reset auth` | clear the basic authentication credentials | `> reset auth` |
+| `h set url ` | sets the *base-url* to be used in further requests | `> set url http://127.0.0.1:8080` |
+| `h get url` | prints the base url | `> get url` |
+| `h get ` | executes the GET request to URL *<base-url>+<uri>* | `> get /collection` |
+| `edit ` | opens *<file>* for editing with the Monaco Editor | > `edit body.json` |
+| `h post ` | executes the POST request request to URL *<base-url>+<uri>*, sending the content of *<file>* as the request body | > `post /collection body.json` |
+| `h put ` | executes the PUT request to URL *<base-url>+<uri>*, sending the content of *<file>* as the request body | `> put /collection body.json` |
+| `h patch ` | executes the PATCH request to URL *<base-url>+<uri>*, sending the content of *<file>* as the request body | `> patch /collection body.json` |
+| `h delete ` | executes the DELETE request to URL *<base-url>+<uri>* | `> delete /collection` |
+| `h set header ` | sets the header *<name>* to *<value>* | `> set header If-Match 5f7f35efcb800f2502f95cb5` |
+| `h get headers` | prints the current set headers | `> get headers` |
+| `h clear headers` | clears the headers | `> clear headers` |
+
diff --git a/docs/v7/plugins/initializers.adoc b/docs/v7/plugins/initializers.adoc
new file mode 100644
index 00000000..86711219
--- /dev/null
+++ b/docs/v7/plugins/initializers.adoc
@@ -0,0 +1,60 @@
+---
+title: Initializers
+layout: docs-adoc
+menu: framework
+---
+
+An _Initializer_ allows executing custom logic at startup time.
+
+== The Initializer class
+
+An Initializer consists of a class implementing the `Initializer` interface annotated with `@RegisterPlugin`.
+
+The following Initializer hangs restheart startup until the user confirms:
+
+[source,java]
+----
+@RegisterPlugin(name = "confirmStartupInitializer",
+ description = "hangs restheart startup until the user hits "
+ priority = 100,
+ initPoint = InitPoint.BEFORE_STARTUP)
+public class confirmStartupInitializer implements Initializer {
+ public void init() {
+ System.out.println("Hit to start RESTHeart");
+ System.console().readLine();
+ }
+}
+----
+
+With the following code the Initializer hangs restheart startup until the user confirms.
+
+TIP: Watch https://www.youtube.com/watch?v=GReteuiMUio&t=1274s[Initializers]
+
+== @RegisterPlugin annotation
+
+The following table describes the arguments of the annotation:
+
+[options="header"]
+|===
+|param |description |mandatory |default value
+|`name`
+|the name of the Initializer
+|yes
+|*none*
+|`description`
+|description of the Initializer
+|yes
+|*none*
+|`enabledByDefault`
+|`true` to enable the plugin; can be overridden by the plugin configuration option `enabled`
+|no
+|`true`
+|`initPoint`
+|specify when the initializer is executed: `BEFORE_STARTUP`, `AFTER_STARTUP`
+|no
+|`AFTER_STARTUP`
+|`priority`
+|the execution priority (less is higher priority)
+|no
+|`10`
+|===
\ No newline at end of file
diff --git a/docs/v7/plugins/interceptors.adoc b/docs/v7/plugins/interceptors.adoc
new file mode 100644
index 00000000..971292d2
--- /dev/null
+++ b/docs/v7/plugins/interceptors.adoc
@@ -0,0 +1,136 @@
+---
+title: Interceptors
+layout: docs-adoc
+menu: framework
+---
+
+Interceptors play a crucial role in the RESTHeart framework, allowing developers to observe and modify requests and responses throughout the request lifecycle. This document provides an overview of the Interceptor class, available interceptor interfaces, and usage examples.
+
+== The Interceptor Class
+
+An `Interceptor` is comprised of a class implementing one of the `Interceptor` interfaces, such as `MongoInterceptor`, and annotated with `@RegisterPlugin`.
+
+The `Interceptor` interface encompasses two pivotal methods: `handle(req, res)` and `resolve(req, res)`. The paramount method is `handle(req, res)`, which is triggered only when `resolve(req, res)` evaluates to `true`. This design ensures that the interceptor's logic is selectively applied, allowing developers to execute customized actions precisely when conditions specified in the `resolve()` method are met.
+
+The `req` and `res` arguments allow you to retrieve and modify the content, query parameters, and headers of both the request and response objects.
+
+The special interceptor interface, `WildcardInterceptor`, intercepts requests handled by any `Service`. Other interceptors can handle requests with matching types between the Service and the Interceptor:
+
+- `WildcardInterceptor`: Intercepts requests handled by any service
+- `ByteArrayInterceptor`: Intercepts requests handled by services implementing `ByteArrayService`
+- `JsonInterceptor`: Intercepts requests handled by services implementing `JsonService`
+- `BsonInterceptor`: Intercepts requests handled by services implementing `BsonService`
+- `MongoInterceptor`: Intercepts requests handled by the `MongoService`
+- `GraphQLInterceptor`: Intercepts GraphQL requests (available from v7.6.2)
+- `ProxyInterceptor`: Intercepts proxied requests
+
+NOTE: `MongoInterceptor` is particularly useful as it allows intercepting requests to the `MongoService`, adding logic to its data API. For instance, the following response interceptor removes the property `secret` from `GET /coll`.
+
+[source,java]
+----
+@RegisterPlugin(name = "secretFilter",
+ interceptPoint = InterceptPoint.RESPONSE,
+ description = "removes the property 'secret' from GET /coll")
+public class ReadOnlyPropFilter implements MongoInterceptor {
+ @Override
+ public void handle(MongoRequest request, MongoResponse response) throws Exception {
+ if (response.getContent().isDocument()) {
+ response.getContent().asDocument().remove("secret");
+ } else if (request.getContent().isArray()) {
+ response.getContent().asArray().stream()
+ .map(doc -> doc.asDocument())
+ .forEach(doc -> doc.remove("secret"));
+ }
+ }
+
+ @Override
+ public boolean resolve(MongoRequest request, MongoResponse response) {
+ return request.isGet()
+ && response.getContent() != null
+ && "coll".equalsIgnoreCase(request.getCollectionName());
+ }
+}
+----
+
+TIP: Watch link:https://www.youtube.com/watch?v=GReteuiMUio&t=986s[Interceptors]
+
+== @RegisterPlugin Annotation
+
+All plugins, including `Interceptors`, must be annotated with `@RegisterPlugin`. This annotation serves two primary purposes:
+
+- *Discovery*: Allows RESTHeart to discover plugin implementation classes in deployed JARs (see link:/docs/plugins/deploy[How to Deploy Plugins]).
+- *Configuration*: Specifies parameters such as the URI of a service or the intercept point of an interceptor.
+
+**Example**:
+
+[source,java]
+----
+@RegisterPlugin(name = "foo",
+ description = "just an example service",
+ defaultUri="/foo", // optional, default /
+ secure=false, // optional, default false
+ enabledByDefault=false) // optional, default true
+public class MyPlugin implements JsonService {
+...
+}
+----
+
+**Annotation Parameters:**
+
+[options="header"]
+[cols="1,3,1,1"]
+|===
+|param |description |mandatory |default value
+|`name`
+|the name of the Interceptor
+|yes
+|*none*
+|`description`
+|description of the Interceptor
+|yes
+|*none*
+|`enabledByDefault`
+|`true` to enable the plugin; can be overridden by the plugin configuration option `enabled`
+|no
+|`true`
+|`interceptPoint`
+|the intercept point: `REQUEST_BEFORE_EXCHANGE_INIT`, `REQUEST_BEFORE_AUTH`, `REQUEST_AFTER_AUTH`, `RESPONSE`, `RESPONSE_ASYNC`
+|no
+|`requiresContent`
+|proxy interceptor
+|Only used by Interceptors of proxied resources (the content is always available to Interceptor of Services) Set it to `true` to make available the content of the request (if interceptPoint is `REQUEST_BEFORE_AUTH` or `REQUEST_AFTER_AUTH`) or of the response (if interceptPoint is `RESPONSE` or `RESPONSE_ASYNC`)
+|no
+|`false`
+|`priority`
+|the execution priority (less is higher priority)
+|no
+|`10`
+|===
+
+== Transforming Request Content Format
+
+Interceptors at `REQUEST_BEFORE_EXCHANGE_INIT` can inspect and modify the request before it is initialized. `The handle(req, res)` and `resolve(req, res)` methods receive the request as `UninitializedRequest` and the response as `UninitializedResponse`. This is particularly useful for transforming request content formats.
+
+Example:
+
+[source,java]
+----
+@RegisterPlugin(name = "xmlToBsonTransformer",
+ interceptPoint = InterceptPoint.REQUEST_BEFORE_EXCHANGE_INIT,
+ description = "transforms XML request to Bson for MongoService")
+public class XmlToBsonTransformer implements WildcardInterceptor {
+ @Override
+ public void handle(UninitializedRequest req, UninitializedResponse res) throws Exception {
+ // Transforming XML to Bson
+ }
+
+ @Override
+ public boolean resolve(UninitializedRequest req, UninitializedResponse res) {
+ // Logic to determine when to apply the transformer
+ }
+}
+----
+
+IMPORTANT: Only `WildcardInterceptor` can use the `REQUEST_BEFORE_EXCHANGE_INIT` intercept point.
+
+For a practical example of transforming request and response content to and from a different format than expected by a service, refer to the link:https://github.com/SoftInstigate/restheart/tree/master/examples/protobuffer-contacts[protobuffer-contacts] example.
\ No newline at end of file
diff --git a/docs/v7/plugins/overview.adoc b/docs/v7/plugins/overview.adoc
new file mode 100644
index 00000000..73e871e1
--- /dev/null
+++ b/docs/v7/plugins/overview.adoc
@@ -0,0 +1,230 @@
+---
+title: Plugins
+layout: docs-adoc
+menu: framework
+---
+
+RESTHeart is ready to go as soon as you install and configure it.
+
+It comes equipped with a comprehensive MongoDB API and security functionality, so for many standard web applications the basic features of RESTHeart are more than enough.
+
+These functionalities are actually provided by the standard plugins that are distributed with RESTHeart. If you look at the `./plugins` directory you'll find them:
+
+[source,bash]
+----
+plugins
+├── restheart-graphql.jar
+├── restheart-mongoclient-provider.jar
+├── restheart-mongodb.jar
+├── restheart-polyglot.jar
+└── restheart-security.jar
+----
+
+Developing plugins for RESTHeart is a great way to extend the basic API. RESTHeart gives you the flexibility of developing plugins in Java, Kotlin and JavaScript.
+
+The are 4 types of plugins:
+
+- **Services** extend the API adding Web Services
+- **Interceptors** snoop and modify requests and responses at different stages of the request lifecycle
+- **Initializers** execute initialization logic at startup time
+- **Providers** implements the Dependency Injection mechanism to provide objects to other plugins via the `@Inject` annotation.
+
+It is also possible to extend the security layer by developing security plugins. Refer to the link:/docs/plugins/security-plugins[Develop Security Plugins] documentation for more information.
+
+IMPORTANT: Have a look at the link:https://github.com/SoftInstigate/restheart/tree/master/examples[plugin examples] for some code examples.
+
+== Plugin Skeleton Project
+
+To quick start a new plugin, you can clone the link:https://github.com/SoftInstigate/restheart-plugin-skeleton[plugin skeleton repository].
+
+[source,bash]
+----
+$ git clone --depth 1 git@github.com:SoftInstigate/restheart-plugin-skeleton.git && cd restheart-plugin-skeleton
+$ ./bin/rh.sh build -o "-s"
+----
+
+The script `./bin/rh.sh` automatically builds, deploys the plugin and restart RESTHeart to apply changes. At first run, it also automatically downloads the latest version of RESTHeart.
+
+The project skeleton defines a dummy Service bound at `/srv`:
+
+[source,bash]
+----
+$ curl localhost:8080/srv
+{"message":"Hello World!","rnd":"njXZksfKFW"}%
+----
+
+IMPORTANT: check the repository link:https://github.com/SoftInstigate/restheart-plugin-skeleton/blob/master/README.md[README.md] for more information.
+
+== Dependency
+
+The only required dependency to develop a plugin is `restheart-commons`.
+
+With maven:
+
+[source,xml]
+----
+
+ org.restheart
+ restheart-commons
+ VERSION
+
+----
+
+== @RegisterPlugin annotation
+
+All plugins must be a annotated with `@RegisterPlugin` to:
+
+- allow RESTHeart to find plugins' implementation classes in deployed jars (see link:/docs/plugins/deploy[How to Deploy Plugins])
+- specify parameters such us the URI of a Service or the intercept point of an Interceptor.
+
+An example follows:
+
+[source,java]
+----
+@RegisterPlugin(name = "foo",
+ description = "just an example service",
+ defaultUri="/foo", // optional, default /
+ secure=false, // optional, default false
+ enabledByDefault=false) // optional, default true
+public class MyPlugin implements JsonService {
+...
+}
+----
+
+The following table describes the arguments of the annotation:
+
+[options="header"]
+|===
+|param |plugin |description |mandatory |default value
+|`name`
+|all
+|the name of the plugin
+|yes
+|*none*
+|`description`
+|all
+|description of the plugin
+|yes
+|*none*
+|`enabledByDefault`
+|all
+|`true` to enable the plugin; can be overridden by the plugin configuration option `enabled`
+|no
+|`true`
+|`defaultURI`
+|service
+|the default URI of the Service; can be overridden by the service configuration option `uri`
+|no
+|/<srv-name>
+|`matchPolicy`
+|service
+|`PREFIX` to match request paths starting with `/`,`EXACT` to only match the request path `/`
+|no
+|`PREFIX`
+|`secure`
+|service
+|`true` to require successful authentication and authorization to be invoked; can be overridden by the service configuration option `secure`
+|no
+|`false`
+|`dontIntercept`
+|service
+|list of interceptPoints to be executed on requests handled by the service, e.g. `dontIntercept = { InterceptPoint.REQUEST_BEFORE_AUTH, InterceptPoint.RESPONSE }`
+|no
+|`{}`
+|`interceptPoint`
+|interceptor
+|the intercept point: `REQUEST_BEFORE_AUTH`, `REQUEST_AFTER_AUTH`, `RESPONSE`, `RESPONSE_ASYNC`
+|no
+|REQUEST_AFTER_AUTH
+|`initPoint`
+|initializer
+|specify when the initializer is executed: `BEFORE_STARTUP`, `AFTER_STARTUP`
+|no
+|`AFTER_STARTUP`
+|`requiresContent`
+|proxy interceptor
+|Only used by Interceptors of proxied resources (the content is always available to Interceptor of Services) Set it to true to make available the content of the request (if interceptPoint is REQUEST_BEFORE_AUTH or REQUEST_AFTER_AUTH) or of the response (if interceptPoint is RESPONSE or RESPONSE_ASYNC)
+|no
+|`false`
+|`priority`
+|interceptor, initializer
+|the execution priority (less is higher priority)
+|no
+|`10`
+|===
+
+NOTE: Watch link:https://www.youtube.com/watch?v=GReteuiMUio&t=108s[Dependencies, annotations and parameters]
+
+== Plugin Configuration
+
+A plugins has a name as defined by the the `@RegisterPlugin` annotation. To define a configuration for a plugin just use its name in the configuration file:
+
+[source,yml]
+----
+ping:
+ enabled: true
+ secure: false
+ uri: /ping
+ msg: 'Ping!'
+----
+
+`enabled` `secure` and `uri` are special configuration options that are automatically managed by RESTHeart:
+
+- *enabled*: for enabling or disabling the plugin via configuration overwriting the `enabledByDefault` property of `@RegisterPlugin`
+- *uri*: applies to Services to bind them to the URI overwriting the `defaultUri` property of `@RegisterPlugin`
+- *secure*: applies to Services, with `secure: true` the service request goes thought the authentication and authorization phases, with `secure: false` the service is fully open.
+
+WARNING: Service have `secure: false` by default. If a service is deployed and has no configuration it will be fully open. If your service needs to be protected, add a configuration for it with `secure: true`
+
+The plugin consumes the configuration with a field annotated with `@Inject("conf")`:
+
+[source,java]
+----
+@Inject("conf")
+Map conf;
+----
+
+`argValue()` is an helper method to simplify retrieving the value of the configuration argument.
+
+NOTE: Watch link:https://www.youtube.com/watch?v=GReteuiMUio&t=356s[Plugin configuration]
+
+== Dependency injection
+
+Available providers allow to inject the following objects:
+
+- `@Inject("config")` - injects the plugins configuration as a `Map`
+- `@Inject("rh-config")` - injects the RESTHeart `org.restheart.configuration.Configuration` object.
+- `@Inject("registry")` - injects the `PluginsRegistry` singleton that allows a plugin to get the reference of other plugins.
+- `@Inject("mclient")` - injects the `MongoClient` object that has been already initialized and connected to MongoDB by the `mongo-client-provider`.
+- `@Inject("mclient-reactive")` - injects the reactive `MongoClient` object that has been already initialized and connected to MongoDB by the `mongo-client-provider`.
+
+[source,java]
+----
+@Inject("registry")
+private PluginsRegistry registry;
+----
+
+[source,java]
+----
+@Inject("mclient")
+private MongoClient mclient;
+----
+
+== Request and Response Generic Classes
+
+*Services* and *Interceptor* are generic classes. They use type parameters for Request and Response classes.
+
+Many concrete implementations of specialized Request and Response exist in the `org.restheart.exchange` package to simplify development:
+
+- `JsonRequest` and `JsonResponse`
+- `BsonRequest` and `BsonResponse`
+- `MongoRequest` and `MongoResponse`
+- `ByteArrayRequest` and `ByteArrayResponse`
+- `StringRequest` and `StringResponse`
+- `BsonFromCsvRequest`
+
+Those implementations differ on the data type used to hold the request and response content. For example, `ByteArrayRequest` and `BsonRequest` hold content as `byte[]` and `BsonValue` respectively.
+
+Different implementation can also provide some helper methods to cope with specific request parameter. For instance, the `MongoRequest`, i.e. the request used by the MongoService, has the method `getPageSize()` because this is a query parameter used by that service.
+
+When a request hits RESTHeart, it determines which service will handle it. The Service implementation is responsible of instantiating the correct Request and Response objects that will be used along the whole exchange processing chain.
diff --git a/docs/v7/plugins/providers.adoc b/docs/v7/plugins/providers.adoc
new file mode 100644
index 00000000..9adc28ad
--- /dev/null
+++ b/docs/v7/plugins/providers.adoc
@@ -0,0 +1,64 @@
+---
+title: Providers
+layout: docs-adoc
+menu: framework
+---
+
+`Provider` classes in RESTHeart work together with the `@Inject` and `@OnInit` annotations to form a Dependency Injection mechanism.
+
+== The Provider class
+
+A Provider class must implements the interface `Provider` and must be annotated with `@RegisterPlugin`:
+
+[source,java]
+----
+RegisterPlugin(name="hello-world-message", description="a dummy provider")
+class MyProvider implements Provider {
+ @Override
+ public String get(PluginRecord caller) {
+ return "Hello World!";
+ }
+}
+----
+
+Given the `hello-world-message` provider, we can inject its provided object into any Plugin with the `@Inject` annotation:
+
+[source,java]
+----
+@RegisterPlugin(name = "greetings", description = "just another Hello World")
+public class GreeterService implements JsonService {
+ @Inject("hello-world-message")
+ private String message;
+
+ @OnInit
+ public void init() {
+ // called after all @Inject fields are resolved
+ }
+
+ @Override
+ public void handle(JsonRequest req, JsonResponse res) {
+ switch(req.getMethod()) {
+ case GET -> res.setContent(object().put("message", message));
+ case OPTIONS -> handleOptions(req);
+ default -> res.setStatusCode(HttpStatus.SC_METHOD_NOT_ALLOWED);
+ }
+ }
+}
+----
+
+== @RegisterPlugin annotation
+
+The following table describes the arguments of the annotation:
+
+[options="header"]
+|===
+|param |description |mandatory |default value
+|`name`
+|the name of the provider
+|yes
+|*none*
+|`description`
+|description of the provider
+|yes
+|*none*
+|===
diff --git a/docs/v7/plugins/services.adoc b/docs/v7/plugins/services.adoc
new file mode 100644
index 00000000..8954e076
--- /dev/null
+++ b/docs/v7/plugins/services.adoc
@@ -0,0 +1,254 @@
+---
+title: Services
+layout: docs-adoc
+menu: framework
+---
+
+A **Service** hooks up a web service to an URI. Whenever there's a request that matches with the URI, its `handle(req, res)` method will be executed.
+
+IMPORTANT: A `Service` consists of a class implementing one of the `Service` interfaces such as `JsonService` and annotated with `@RegisterPlugin`.
+
+The `req` and `res` arguments allow to retrieve request content, query parameters and headers and set the response status code, content and headers respectively. For instance, `res.setStatusCode(200)` sets the response status code.
+
+NOTE: No need to worry about the actual HTTP data transmission - RESTHeart will handle that for you automatically using the data set in the `res` object.
+
+== The Service class
+
+A `Service` consists of a class implementing one of the `Service` interfaces such as `JsonService` and annotated with `@RegisterPlugin`.
+
+The following Service interfaces are provided and differ from the data type used to hold the request and response content:
+
+- `ByteArrayService`
+- `StringService`
+- `JsonService`
+- `BsonService`
+
+For instance, `BsonService` uses `BsonValue` to hold request and response content: this is useful when you cope with MongoDb that represents data using this class.
+
+The code of example link:https://github.com/SoftInstigate/restheart/tree/master/examples/greeter-service[greeter-service] implementing `JsonService` follows:
+
+[source,java]
+----
+RegisterPlugin(name = "greetings", description = "just another Hello World")
+public class GreeterService implements JsonService {
+ @Override
+ public void handle(JsonRequest req, JsonResponse res) {
+ switch(req.getMethod()) {
+ case GET -> res.setContent(object().put("message", "Hello World!"));
+ case OPTIONS -> handleOptions(req);
+ default -> res.setStatusCode(HttpStatus.SC_METHOD_NOT_ALLOWED);
+ }
+ }
+}
+----
+
+The key method is `handle(req, res)` that is executed when a request matching the service's URI hits RESTHeart.
+
+NOTE: the verb `OPTIONS` is handled by the ready-to-use `handleOptions(req)` method. It copes with link:/docs/plugins/cors[CORS headers] making sure the Web Service can be safely invoked by browsers.
+
+== @RegisterPlugin annotation
+
+The class implementing the `Service` interfaces must be a annotated with `@RegisterPlugin` to:
+
+- allow RESTHeart to find plugins' implementation classes in deployed jars (see link:/docs/plugins/deploy[How to Deploy Plugins])
+- specify parameters such us the URI of a Service or the intercept point of an Interceptor.
+
+The following table describes the arguments of the annotation for Services:
+
+[options="header"]
+[cols="1,3,1,1"]
+|===
+|param |description |mandatory |default value
+|`name`
+|the name of the Service
+|yes
+|*none*
+|`description`
+|description of the Service
+|yes
+|*none*
+|`enabledByDefault`
+|`true` to enable the plugin; can be overridden by the plugin configuration option `enabled`
+|no
+|`true`
+|`defaultURI`
+|the default URI of the Service; can be overridden by the service configuration option `uri`
+|no
+|/<srv-name>
+|`matchPolicy`
+|`PREFIX` to match request paths starting with `/`,`EXACT` to only match the request path `/`
+|no
+|`PREFIX`
+|`secure`
+|`true` to require successful authentication and authorization to be invoked; can be overridden by the service configuration option `secure`
+|no
+|`false`
+|`dontIntercept`
+|list of interceptPoints to be executed on requests handled by the service, e.g. `dontIntercept = { InterceptPoint.REQUEST_BEFORE_AUTH, InterceptPoint.RESPONSE }`
+|no
+|`{}`
+|===
+
+== Service with custom generic types
+
+To implement a `Service` that handles different types of `Request` and `Response`, it must implement the base `Service` interface.
+
+The base `Service` interface requires to implement methods to initialize and retrieve the `Request` and `Response` objects.
+
+The following example shows how to handle XML content:
+
+[source,java]
+----
+@RegisterPlugin(name = "myXmlService",
+ description = "example service consuming XML requests",
+ enabledByDefault = true,
+ defaultURI = "/xml")
+public class MyXmlService implements Service {
+ public void handle(XmlRequest req, XmlResponse res) {
+ // handling logic omitted
+ }
+
+ @Override
+ default Consumer requestInitializer() {
+ return e -> XmlRequest.init(e);
+ }
+
+ @Override
+ default Consumer responseInitializer() {
+ return e -> XmlResponse.init(e);
+ }
+
+ @Override
+ default Function request() {
+ return e -> XmlRequest.of(e);
+ }
+
+ @Override
+ default Function response() {
+ return e -> XmlResponse.of(e);
+ }
+}
+----
+
+The example follows a pattern that delegates the actual initialization (in `requestInitializer()` and `responseInitializer()`) and retrieval of the object from the exchange (in `request()` and `response()`) to the concrete class, as follows:
+
+[source,java]
+----
+public class XmlRequest extends ServiceRequest {
+ private XmlRequest(HttpServerExchange exchange) {
+ super(exchange);
+ }
+
+ public static XmlRequest init(HttpServerExchange exchange) {
+ var ret = new XmlRequest(exchange);
+
+ try {
+ ret.injectContent();
+ } catch (Throwable ieo) {
+ ret.setInError(true);
+ }
+
+ return ret;
+ }
+
+ public static XmlRequest of(HttpServerExchange exchange) {
+ return of(exchange, XmlRequest.class);
+ }
+
+ public void injectContent() throws SAXException, IOException {
+ var dBuilder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
+ var rawContent = ChannelReader.read(wrapped.getRequestChannel());
+
+ setContent(dBuilder.parse(rawContent)ml);
+ }
+}
+----
+
+In the constructor a call to `super(exchange)` attaches the object to the `HttpServerExchange`. The object is retrieved using the inherited `of()` method that gets the instance attachment from the `HttpServerExchange`. This is fundamental for two reasons: first the same request and response objects must be shared by the all handlers of the processing chain. Second, this avoid the need to parse the content several times for performance reasons.
+
+TIP: Watch link:https://www.youtube.com/watch?v=GReteuiMUio&t=680s[Services]
+
+== CORS Headers
+
+CORS stands for link:https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing]
+and it is a mechanism to allow resources on a web page to be requested
+from another domain outside the domain from which the resource
+originated.
+
+Imagine the case of a web site, where the static resources (html, css
+and javascript) are served by **domain1.com**. On the other end,
+RESTHeart is running on a different server in **domain2.com**.
+
+Without CORS support, the javascript logic could not actually request
+data to RESTHeart, forcing to have both static resources and RESTHeart
+running in the same domain.
+
+What happens behind the scene, for AJAX and HTTP request methods that
+can modify data, the CORS specification mandates that browsers
+"preflight" the request, soliciting supported methods from the server
+with an HTTP OPTIONS request header, and then, upon "approval" from the
+server, sending the actual request with the actual HTTP request method.
+
+=== CORS Support
+
+RESTHeart always returns CORS headers to allow requests originated
+from different domains.
+
+The following example, highlights the CORS headers returned by
+RESTHeart, in the case of a collection resource.
+
+**Request**
+
+[source,bash]
+OPTIONS /test/coll HTTP/1.1
+
+**Response**
+
+[source,bash]
+----
+HTTP/1.1 200 OK
+Access-Control-Allow-Credentials: true
+Access-Control-Allow-Headers: Accept, Accept-Encoding, Authorization, Content-Length, Content-Type, Host, If-Match, Origin, X-Requested-With, User-Agent, No-Auth-Challenge
+Access-Control-Allow-Methods: GET, PUT, POST, PATCH, DELETE, OPTIONS
+Access-Control-Allow-Origin: *
+Access-Control-Expose-Headers: Location, ETag, Auth-Token, Auth-Token-Valid-Until, Auth-Token-Location
+----
+
+=== Customize CORS Headers
+
+The `Service` interface extends the following interface:
+
+[source,java]
+----
+public interface CORSHeaders {
+ /**
+ * @return the values of the Access-Control-Expose-Headers
+ *//
+ default String accessControlExposeHeaders() {
+ // return the defaults headers
+ }
+
+ /**
+ * @return the values of the Access-Control-Allow-Credentials
+ *//
+ default String accessControlAllowCredentials() {
+ // return the defaults headers
+ }
+
+ /**
+ * @return the values of the Access-Control-Allow-Origin
+ *//
+ default String accessControlAllowOrigin() {
+ // return the defaults headers
+ }
+
+ /**
+ * @return the values of the Access-Control-Allow-Methods
+ *//
+ default String accessControlAllowMethods() {
+ // return the defaults headers
+ }
+ }
+----
+
+RESTHeart uses those methods to return the CORS headers. Overriding the methods allow to set or add custom CORS headers.
\ No newline at end of file
diff --git a/docs/v7/plugins/token-managers.adoc b/docs/v7/plugins/token-managers.adoc
new file mode 100644
index 00000000..c82b1358
--- /dev/null
+++ b/docs/v7/plugins/token-managers.adoc
@@ -0,0 +1,96 @@
+---
+title: Token Managers
+layout: docs-adoc
+menu: framework
+---
+
+A `Token Manager` is responsible for generating and verifying authentication tokens. When a request is authenticated through any configured method, such as Basic Authentication, the response includes the `Auth-Token` header. The value of this token is generated by the Token Manager. Subsequent requests can utilize this authentication token in lieu of actual credentials.
+
+NOTE: The Token Manager works in conjunction with the Authentication Mechanism `tokenBasicAuthMechanism`. This mechanism handles the token and delegates its verification to the configured token manager.
+
+== Implementation
+
+The Token Manager implementation class must implement the `org.restheart.plugins.security.TokenManager` interface.
+
+TIP: For an example implementation check the code of link:https://github.com/SoftInstigate/restheart/blob/master/security/src/main/java/org/restheart/security/plugins/tokens/RndTokenManager.java[RndTokenManager], which generates random tokens.
+
+Note that `TokenManager` extends `Authenticator` for token verification methods.
+
+[source,java]
+----
+public interface TokenManager extends Authenticator, ConfigurablePlugin {
+ public static final HttpString AUTH_TOKEN_HEADER = HttpString.tryFromString("Auth-Token");
+ public static final HttpString AUTH_TOKEN_VALID_HEADER = HttpString.tryFromString("Auth-Token-Valid-Until");
+ public static final HttpString AUTH_TOKEN_LOCATION_HEADER = HttpString.tryFromString("Auth-Token-Location");
+ public static final HttpString ACCESS_CONTROL_EXPOSE_HEADERS = HttpString.tryFromString("Access-Control-Expose-Headers");
+
+ /**
+ * retrieves or generates a token valid for the account
+ *
+ * @param account
+ * @return the token for the account
+ */
+ public PasswordCredential get(final Account account);
+
+ /**
+ * invalidates the token bound to the account
+ *
+ * @param account
+ */
+ public void invalidate(final Account account);
+
+ /**
+ * updates the account bound to a token
+ *
+ * @param account
+ */
+ public void update(final Account account);
+
+ /**
+ * injects the token headers in the response
+ *
+ * @param exchange
+ * @param token
+ */
+ public void injectTokenHeaders(final HttpServerExchange exchange, final PasswordCredential token);
+}
+----
+
+== Registering
+
+The Token Manager class must be annotated with `@RegisterPlugin`:
+
+[source,java]
+----
+@RegisterPlugin(name="myTokenManager", description = "my custom token manager")
+public class MyTokenManager implements TokenManager {
+
+}
+----
+
+NOTE: Only one token manager can be used. If more than one token manager is defined and enabled, only the first one will be used.
+
+== Configuration
+
+The Token Manager can receive parameters from the configuration file using the `@Inject("config")` annotation:
+
+[source,java]
+----
+@Inject("config")
+private Map config;
+
+@OnInit
+public void init() throws ConfigurationException {
+ // get configuration arguments
+ int number = argValue(this.config, "number");
+ String string = argValue(this.config, "string");
+}
+----
+
+The parameters are defined in the configuration using the name of the token manager as defined by the `@RegisterPlugins` annotation:
+
+```yaml
+myTokenManager:
+ number: 10
+ string: a string
+```
\ No newline at end of file
diff --git a/docs/v7/plugins/tutorial.adoc b/docs/v7/plugins/tutorial.adoc
new file mode 100644
index 00000000..54a67963
--- /dev/null
+++ b/docs/v7/plugins/tutorial.adoc
@@ -0,0 +1,142 @@
+---
+title: RESTHeart Greetings Services Tutorial
+layout: docs-adoc
+menu: framework
+---
+
+This tutorial introduces two straightforward web services from the **RESTHeart examples collection**: `textGreeter` and `jsonGreeter`. These services generate greeting messages in different formats: `textGreeter` delivers messages in `text/plain` format, while `jsonGreeter` uses `application/json`.
+
+This plugin serves as an example of how to create services in RESTHeart by implementing various specialized `Service` interfaces, such as `JsonService` and `ByteArrayService`. It demonstrates handling requests and responses, retrieving query parameters, and setting the `Content-Type` header.
+
+IMPORTANT: **Explore Comprehensive RESTHeart Examples!** If you're looking to dive deeper into developing with RESTHeart, visit the link:https://github.com/SoftInstigate/restheart/blob/master/examples/README.md[RESTHeart examples^] to discover a rich collection of use cases and code samples. **Highly recommended for an in-depth learning experience!**
+
+== What you need
+
+To run this tutorial, the following are required:
+
+1) **Java 17**: Install it using link:https://sdkman.io[sdkman^]
+
+[source,bash]
+$ sdk install java 17.0.9-tem
+
+2) **Docker**: Necessary for running RESTHeart.
+
+3) **HTTPie**: A command-line HTTP client for testing, available at link:https://httpie.io/cli[httpie.io/cli^]
+
+NOTE: The examples use Maven, but it's accessible through the included Maven wrapper (`mvnw`), so a separate installation is not required.
+
+== Building the Plugin
+
+To build the plugin, run the following commands:
+
+[source,bash]
+----
+$ git clone --depth 1 git@github.com:SoftInstigate/restheart.git # clone restheart repo
+$ cd examples/greeter-service # cd into the greeter-service example project root
+$ ../mvnw clean package build the project
+----
+
+== Running RESTHeart with the Plugin
+
+This plugin doesn't require MongoDB, so you can run RESTHeart in standalone mode using the `-s` option.
+
+Use Docker to start RESTHeart with the plugin:
+
+[source,bash]
+----
+$ docker run --rm -p 8080:8080 -e RHO="/fileRealmAuthenticator/users[userid='admin']/password->'secret';/http-listener/host->'0.0.0.0'" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart:latest -s
+----
+
+For more information, see link:/docs/setup-with-docker#run-restheart-with-custom-plugin[RESTHeart with custom Plugin] documentation.
+
+== Testing the Service
+
+You can test the service with the following HTTP requests:
+
+=== GET request, no query parameter
+
+[source,bash]
+----
+$ http -b :8080/textGreeter
+Hello, World
+----
+
+=== GET request, with name query parameter
+
+[source,bash]
+----
+$ http -b :8080/textGreeter?name=Andrea
+Hello, Andrea
+----
+
+=== POST request, with content body
+
+[source,bash]
+----
+$ http --raw 'Sara' :8080/textGreeter
+Hello, Sara
+----
+
+Note: Using HTTP verbs other than `OPTIONS`, `GET`, or `POST` for `/textGreeter` will result in a `HTTP 405 Method Not Allowed` response.
+
+== Plugin Code Description
+
+Below is the code of the `TextGreeterService` class that implements the Web Service `/textGreeter`:
+
+[source,java]
+----
+@RegisterPlugin(
+ name = "textGreeter",
+ description = "just another text/plain Hello World")
+public class TextGreeterService implements ByteArrayService {
+ @Override
+ public void handle(ByteArrayRequest req, ByteArrayResponse res) {
+ res.setContentType("text/plain; charset=utf-8");
+
+ switch (req.getMethod()) {
+ case OPTIONS -> handleOptions(req);
+
+ case GET -> {
+ var name = req.getQueryParameters().get("name");
+ res.setContent("Hello, " + (name == null ? "Anonymous" : name.getFirst()));
+ }
+
+ case POST -> {
+ var content = req.getContent();
+ res.setContent("Hello, " + (content == null ? "Anonymous" : new String(content)));
+ }
+
+ default -> res.setStatusCode(HttpStatus.SC_METHOD_NOT_ALLOWED);
+ }
+ }
+}
+----
+
+The Java class `TextGreeterService` is defined as a plugin for a RESTful service, as indicated by the `@RegisterPlugin` annotation. This class is an implementation of the `ByteArrayService` interface. Let's break down its structure and functionality:
+
+1. **Annotation - @RegisterPlugin**:
+ * This annotation is used to register the class as a RESTHeart plugin.
+ * It has two parameters:
+ ** `name`: the identifier for this service. The endpoint defaults to `/textGreeter` since it is not explicitly defined by the annotation parameter `defaultURI`.
+ ** `description`: provides a brief description of what this service does.
+
+2. **Class Declaration**:
+ * `public class TextGreeterService implements ByteArrayService`: this indicates that `TextGreeterService` is a public class implementing the `ByteArrayService` interface.
+
+3. **Method - handle(ByteArrayRequest req, ByteArrayResponse res)**:
+ * This method is an override from the `ByteArrayService` interface.
+ * It takes two parameters: a `ByteArrayRequest` (named `req`) and a `ByteArrayResponse` (named `res`).
+
+4. **Setting the Content-Type**:
+ * `res.setContentType("text/plain; charset=utf-8")`:
+ * This line sets the content type of the response to `text/plain` with `UTF-8` charset, indicating that the response will be plain text.
+
+5. **Handling Different HTTP Methods**:
+ * The service uses a switch statement to handle different HTTP request methods.
+ * For each case, there's a different way to handle the request:
+ ** `OPTIONS`: Calls a method `handleOptions(req)`, an inherited convenient method that handles it for you providing CORS support.
+ ** `GET`: Retrieves a query parameter `name` from the request. If `name` is not provided, it defaults to `World`. The response content is set to "Hello, [name]".
+ ** `POST`: Gets the content of the request. If no content is provided, it defaults to `World`. The response is similar to the GET method, greeting the content of the request.
+ *For any other HTTP method, the service sets the response status code to `HttpStatus.SC_METHOD_NOT_ALLOWED`, indicating that the method is not supported.
+
+In summary, `TextGreeterService` is a RESTHeart service plugin designed to respond with a simple text greeting. It handles GET and POST requests differently based on the input it receives (either through query parameters or request body) and defaults to greeting "World" if no specific input is provided. It also handles OPTIONS requests and rejects unsupported methods.
\ No newline at end of file
diff --git a/docs/v7/proxy.md b/docs/v7/proxy.md
new file mode 100644
index 00000000..a75e558e
--- /dev/null
+++ b/docs/v7/proxy.md
@@ -0,0 +1,118 @@
+---
+title: Proxing requests
+layout: docs
+menu: setup
+---
+
+
+
+* [Introduction](#introduction)
+* [How to proxy requests](#how-to-proxy-requests)
+
+
+
+
+{% include docs-head.html %}
+
+## Introduction
+
+The `restheart.yml` configuration file allows defining proxied resources. This makes possible to put other microservices under the security domain of RESTHeart.
+
+## How to proxy requests
+
+As an example, we are going to see how to proxy `https://httpbin.org/anything` through RESTHeart.
+
+{: .bs-callout .bs-callout-info }
+`https://httpbin.org/anything` is a popular and simple online HTTP Request & Response Service that returns anything that is passed to request for testing purposes.
+
+Add the following section to the configuration file `restheart.yml `and restart RESTHeart:
+
+```yml
+proxies:
+ - location: /anything
+ proxy-pass: https://httpbin.org/anything
+ name: anything
+```
+
+As a result, requests to URL `http:///anything` are proxied to `https://httpbin.org/anything`as specified by the parameter `proxy-pass`.
+
+{% include code-header.html type="Request" %}
+
+```http
+GET /anything HTTP/1.1
+```
+
+{% include code-header.html type="Response" %}
+
+```http
+HTTP/1.1 401 Unauthorized
+```
+
+With the default configuration RESTHeart uses the Basic Authentication with credentials and permission defined in `/users` and `/acl` MongoDB collections. Let's add a user and a permission for `/anything`
+
+User:
+
+```http
+POST /users HTTP/1.1
+
+{
+ "_id" : "user",
+ "password": "secret",
+ "roles": ["anything"]
+}
+```
+
+### acl.yml
+
+```http
+POST /acl HTTP/1.1
+
+{
+ "role": "anything"
+ "predicate": "path-prefix[path=/anything] and method[GET]"
+}
+```
+
+{% include code-header.html type="Request" %}
+
+```http
+GET /anything?foo=bar HTTP/1.1
+Authorization: Basic dXNlcjpzZWNyZXQ=
+```
+
+{% include code-header.html type="Response" %}
+
+```http
+HTTP/1.1 200 OK
+
+{
+ "args": {
+ "foo": "bar"
+ },
+ "data": "",
+ "files": {},
+ "form": {},
+ "headers": {
+ "Accept": "*/*",
+ "Accept-Encoding": "gzip, deflate",
+ "Host": "httpbin.org",
+ "User-Agent": "HTTPie/1.0.3",
+ "X-Amzn-Trace-Id": "Root=1-5ee2508c-35dd55551c2c0188bba66b8f",
+ "X-Forwarded-Account-Id": "user",
+ "X-Forwarded-Account-Roles": "anything",
+ "X-Forwarded-Host": "localhost:8080",
+ "X-Forwarded-Server": "localhost"
+ },
+ "json": null,
+ "method": "GET",
+ "origin": "127.0.0.1, 93.41.97.239",
+ "url": "https://localhost:8080/anything?foo=bar"
+}
+```
+We can note that RESTHeart:
+
+- has checked the credential specified in `/users/user` passed via Basic Authentication and proxied the request
+- has determined the account `roles`
+- has checked the permission specified in `/acl` for the account roles and determined that the request could be executed.
+- the user id and roles are passed by RESTHeart to the proxied service via the `X-Forwarded-Account-Id` and `X-Forwarded-Account-Roles` request header.
+- the response headers include the header `Auth-Token`. Its value can be used in place of the actual password in the Basic Authentication until its expiration. This is useful in Web Applications, for storing in the browser the less sensitive auth token instead of full username and password.
diff --git a/docs/v7/security.md b/docs/v7/security.md
new file mode 100644
index 00000000..94a21d6c
--- /dev/null
+++ b/docs/v7/security.md
@@ -0,0 +1,6 @@
+---
+layout: redirect
+redirectUrl: "/docs/security/overview/"
+sitemap: false
+---
+
diff --git a/docs/v7/security/authentication.adoc b/docs/v7/security/authentication.adoc
new file mode 100644
index 00000000..76d4c357
--- /dev/null
+++ b/docs/v7/security/authentication.adoc
@@ -0,0 +1,208 @@
+---
+title: Authentication
+layout: docs-adoc
+menu: security
+---
+
+== Introduction
+
+See link:/docs/security/overview[Security Overview] for an high level view of the RESTHeart security model.
+
+**RESTHeart** is built around a **pluggable architecture**. It comes with a strong security implementation but you can easily extend it by implementing plugins. This section documents the authentication plugins available out-of-the-box. You can also develop your own authentication plugins.
+
+== Authentication Mechanisms
+
+=== JWT Authentication
+
+JWT Authentication manages the authentication following the link:https://jwt.io[JSON Web Token standard].
+
+The token is verified against the configured `issuer` and `audience` and according to the specified `algorithm`. If you want to disable checking `issuer` or `audience`, set them to `null`. The property `audience` can be `null`, a String or an array of Strings.
+
+The authenticated client will gain the roles included in the JWT claim set by `rolesClaim` or the roles specified by the configuration option `fixedRoles`. It's not possible to set both `rolesClaim` and `fixedRoles`
+
+Supported algorithms are the HMAC256, HMAC384, HMAC512, RSA256, RSA384, RSA512.
+
+For HMAC the `key` configuration option specifies the secret, for RSA the public key.
+
+[source,yml]
+----
+jwtAuthenticationMechanism:
+ enabled: true
+ algorithm: HS256
+ key: secret
+ base64Encoded: false
+ usernameClaim: sub
+ rolesClaim: roles
+ fixedRoles:
+# - admin
+ issuer: myIssuer
+ audience: myAudience
+----
+
+=== Basic Authentication
+
+**BasicAuthMechanism** manages the Basic Authentication method, where the client credentials are sent via the `Authorization` request header using the format `Authorization: Basic base64(id:pwd)`. The configuration allows specifying the Authenticator that will be used to verify the credentials.
+
+[source,yml]
+----
+basicAuthMechanism:
+ enabled: true
+ authenticator: fileRealmAuthenticator
+----
+
+=== Avoid browsers to open the login popup window
+
+The Basic and Digest Authentication protocols requires responding with a challenge when the request cannot be authenticated as follows:
+
+[source,html]
+----
+WWW-Authenticate: Basic realm="RESTHeart Realm"
+WWW-Authenticate: Digest realm="RESTHeart Realm",domain="localhost",nonce="Toez71bBUPoNMTU0NDAwNDMzNjEwMXBY+Jp7YX/GVMcxAd61FpY=",opaque="00000000000000000000000000000000",algorithm=MD5,qop="auth"
+----
+
+In browsers this leads to the login popup windows. In our web applications we might want to redirect to a fancy login page when the 401 Unauthorized response code.
+
+To avoid the popup window just add to the request the `noauthchallenge` query parameter or the header `No-Auth-Challenge`. This will skip the challenge response.
+
+=== Digest Authentication
+
+**DigestAuthMechanism** manages the Digest Authentication method. The configuration allows specifying the Authenticator that will be used to verify the credentials.
+
+[source,yml]
+----
+digestAuthMechanism:
+ enabled: true
+ realm: RESTHeart Realm
+ domain: localhost
+ authenticator: fileRealmAuthenticator
+----
+
+=== Token Authentication
+
+**TokenBasicAuthMechanism** manages the Basic Authentication method with the actual password replaced by the auth token generated by **RESTHeart**, i.e. the client credentials are sent via the `Authorization` request header using the format `Authorization: Basic base64(id:auth-token)`. It requires a Token Manager to be configured (eg. RndTokenManager).
+
+[source,yml]
+----
+tokenBasicAuthMechanism:
+ enabled: true
+----
+
+=== Identity Authentication
+
+**IdentityAuthMechanism** just authenticates any request building an link:https://github.com/SoftInstigate/restheart/blob/master/commons/src/main/java/org/restheart/security/BaseAccount.java[BaseAccount] with the _username_ and _roles_ specified in the configuration. Useful for testing purposes. Note that enabling this causes the _DigestAuthMechanism_ to fail, you cannot use both.
+
+[source,yml]
+----
+identityAuthMechanism:
+ enabled: false
+ username: admin
+ roles:
+ - admin
+ - user
+----
+
+TIP: Watch link:https://www.youtube.com/watch?v=QVk0aboHayM&t=342s[Authentication mechanisms]
+
+== Authenticators
+
+=== Mongo Realm Authenticator
+
+**mongoRealAuthenticator** authenticates users defined in a MongoDB collection.
+
+NOTE: Mongo Realm Authenticator is suggested for production usage.
+
+The configuration allows:
+
+- defining the collection to use (`users-db` and `users-collection`), the properties of the user document to use as user id, password and roles (`prop-id`, `prop-password` and `json-path-roles`).
+- enabling hashed password using the strong bcrypt hashing algorithm (`bcrypt-hashed-password` and `bcrypt-complexity`); note that the password is automatically hashed on write requests and that the password property is automatically removed from responses.
+- allows initializing the users collection and the admin user if not existing. See `create-user` option.
+- allows controlling the users caching.
+
+[source,yml]
+----
+mongoRealmAuthenticator:
+ users-db: restheart
+ users-collection: users
+ prop-id: _id
+ prop-password: password
+ json-path-roles: $.roles
+ bcrypt-hashed-password: true
+ bcrypt-complexity: 12
+ create-user: true
+ create-user-document: '{"_id": "admin", "password": "$2a$12$lZiMMNJ6pkyg4uq/I1cF5uxzUbU25aXHtg7W7sD2ED7DG1wzUoo6u", "roles": ["admin"]}'
+ # create-user-document.password must be hashed when bcrypt-hashed-password=true
+ # default password is 'secret'
+ # see https://bcrypt-generator.com but replace initial '$2y' with '$2a'
+ cache-enabled: false
+ cache-size: 1000
+ cache-ttl: 60000
+ cache-expire-policy: AFTER_WRITE
+ enforce-minimum-password-strenght: false
+ # Integer from 0 to 4
+ # 0 Weak （guesses < 3^10）
+ # 1 Fair （guesses < 6^10）
+ # 2 Good （guesses < 8^10）
+ # 3 Strong （guesses < 10^10）
+ # 4 Very strong （guesses >= 10^10）
+ minimum-password-strength: 3
+----
+
+=== File Realm Authenticator
+
+**fileRealmAuthenticator** defines users credentials and roles in the configuration or in a simple yml configuration file.
+
+[source,yml]
+----
+fileRealmAuthenticator:
+ enabled: true
+ #conf-file: ./etc/users.yml
+ users:
+ - userid: admin
+ password: null
+ roles: [admin]
+----
+
+The `conf-file` path is either absolute, or relative to the restheart configuration file (if specified) or relative to the plugins directory (if using the default configuration).
+
+See link:https://github.com/SoftInstigate/restheart/blob/master/examples/example-conf-files/users.yml[users.yml] for an example users definition.
+
+NOTE: defining users directly in the configuration rather than on a separate `users.yml` file is available from RESTHeart v7.2
+
+== Token Managers
+
+=== Random Token Manager
+
+**rndTokenService** generates an auth token using a random number generator. It has two arguments, `ttl`, which is the tokens Time To Live in minutes, and `srv-uri` the URI of the service that allows to get and invalidate the user auth token.
+
+[source,yml]
+----
+rndTokenManager:
+ enabled: true
+ ttl: 15
+ srv-uri: /tokens
+----
+
+=== JWT Token Manager
+
+**jwtTokenManager** An implementation of Token Manger that issues and verifies auth tokens in a cluster compatible way.
+
+Each token can be verified by any node of the cluster regardless which one actually issued it (as long as they share the same secret)
+
+[source,yml]
+----
+jwtTokenManager:
+ key: secret
+ enabled: true
+ ttl: 15
+ srv-uri: /tokens
+ issuer: restheart.com
+----
+
+The query parameter renew-auth-token forces the token to be renewed.
+
+Generating a new token is a cryptographic operation,
+and it can have a significant performance overhead.
+It is responsibility of the client to renew the token using this query parameter
+when it is going to expiry somehow soon.
+
+TIP: Watch link:https://www.youtube.com/watch?v=QVk0aboHayM&t=1211s[Authenticators in RESTHeart]
diff --git a/docs/v7/security/authorization.adoc b/docs/v7/security/authorization.adoc
new file mode 100644
index 00000000..efade11c
--- /dev/null
+++ b/docs/v7/security/authorization.adoc
@@ -0,0 +1,326 @@
+---
+title: Authorization
+layout: docs-adoc
+menu: security
+---
+
+== Introduction
+
+See link:/docs/security/overview#understanding-restheart-security[Understanding RESTHeart Security] for an high level view of the RESTHeart security model.
+
+RESTHeart is built around a **pluggable architecture**. It comes with a strong security implementation but you can easily extend it by implementing plugins. This section documents the authorizers available out-of-the-box.
+
+RESTHeart offers two authorizers out-of-the-box:
+
+1. Mongo ACL Authorizer
+2. File ACL Authorizer
+
+Both authorizers provide a simple, declarative and a rich, ACL-based model for authorization.
+
+It's even possible to develop **custom authorizers**. Please refer to link:/docs/plugins/security-plugins[Develop Security Plugins] for more information.
+
+== Mongo ACL Authorizer
+
+_mongoAclAuthorizer_ authorizes requests according to the _Access Control List_ defined in a **MongoDB collection**.
+
+The configuration allows:
+
+- defining the collection to use to store ACL documents (`acl-db` and `acl-collection`).
+- enabling the root role (`root-role`): users with root role, can execute any requests, regardless of the permissions set in the ACL. Set it to null (`root-role: null`) to disable it.
+- controlling the ACL caching.
+
+[source,yml]
+----
+mongoAclAuthorizer:
+ acl-db: restheart
+ acl-collection: acl
+ # clients with root-role can execute any request
+ root-role: admin
+ cache-enabled: true
+ cache-size: 1000
+ cache-ttl: 5000
+ cache-expire-policy: AFTER_WRITE
+----
+
+=== Format of permissions
+
+The properties of the permission document are:
+
+[options="header"]
+[cols="1,1,3"]
+|===
+|property |type |description
+|**predicate**
+|string
+|If the link:https://undertow.io/undertow-docs/undertow-docs-2.1.0/index.html#textual-representation-of-predicates[undertow predicate] resolves the request then the request is authorized. Many examples of predicates can be found in the file link:https://github.com/SoftInstigate/restheart/blob/master/examples/example-conf-files/acl.yml[acl.yml]
+|**roles**
+|JSON array of strings
+|The roles that are applied the ACL document. The special role `$unauthenticated` applies to requests that are not authenticated.
+|**priority**
+|number
+|A request might fulfill several predicates; an ACL document with higher priority has higher evaluation precedence.
+|**mongo**
+|`null` or JSON `MongoPermissions` object
+|For requests handled by the `MongoService` (i.e. the service that implements the REST API for MongoDB) the permission can specify the [MongoPermissions](#mongopermissions) object
+|===
+
+An example permission document follows (for more examples check link:https://github.com/SoftInstigate/restheart/blob/master/examples/example-conf-files/acl.json[acl.json]):
+
+
+[source,json]
+----
+{
+ "_id": "userCanGetOwnCollection",
+ "roles": ["user"],
+ "predicate": "method(GET) and path-template('/{userid}') and equals(@user._id, ${userid}) and qparams-contain(page) and qparams-blacklist(filter, sort)",
+ "priority": 100,
+ "mongo": {
+ "readFilter": { "_$or": [{ "status": "public" }, { "author": "@user._id" }] },
+ "projectResponse": { "log": 0 }
+ }
+}
+----
+
+The permission allows the request if:
+
+- the authenticated user has `user` role
+- the request method is `GET`
+- the request path is `/{userid}`, where the `{userid}` is the id of the authenticated user
+- the request specifies the query parameter `page`, due to predicate `qparams-contain(page)`
+- the request does not specify the query parameters `filter` and `sort`, due to predicate `qparams-blacklist(filter, sort)`
+
+If the request is authorized by this permission then:
+
+- the property `log` is removed from the response, due to `projectResponse`
+- a `readFilter` applies, so only document with `status=public` or `author=` are returned
+
+=== Predicates
+
+The ACL permissions use the link:https://undertow.io/undertow-docs/undertow-docs-2.1.0/index.html#textual-representation-of-predicates[undertow predicate language] to define the condition a request must met to be authorized.
+
+A simple example of predicate is `(method(GET) or method(POST)) and path('/coll')` that authorizes `GET` or `POST` requests when the URI is `/coll`
+
+RESTHeart extends this language introducing the following new predicates that extend and simplify the ACL permission definition:
+
+[options="header"]
+[cols="1,2,2"]
+|===
+|predicate | |
+|`qparams-contain`
+|`true` if the request query string contains the specified parameter
+|`qparams-contain(page,pagesize)`
+|`qparams-blacklist`
+|`true` if the request query string does not contain the blacklisted parameters
+|`qparams-contain(filter,sort)`
+|`qparams-whitelist`
+|`true` if the request query string contains only whitelisted parameters
+|`qparams-whitelist(page,pagesize)`
+|`qparams-size`
+|`true` if the request query string the specified number of parameters
+|`qparams-size(3)`
+|`bson-request-contains`
+|`true` if the request content is BSON and contains the specified properties
+|`bson-request-contains(foo,bar.sub)`
+|`bson-request-whitelist`
+|`true` if the request content is BSON and only contains whitelisted properties
+|`bson-request-whitelist(foo,bar.sub)`
+|`bson-request-blacklist`
+|`true` if the request content is BSON and doesn't contain blacklisted properties
+|`bson-request-blacklist(foo,bar.sub)`
+|`in`
+|checks if `value` is contained in `array`
+|`path-template('/{tenant}') and in(value=${tenant}, array=@user.tenants)`
+
+|`bson-request-prop-equals` _from v7.5_
+|`true` if the request content is bson and the value of the property `key` (can use the dot notation) is equal to `value`
+|if the request content is `{"sub": { "foo": "bar" }}` then `bson-request-prop-equals(key=sub.foo, value='"bar"')` and `bson-request-prop-equals(key=sub, value='{"foo": "bar"}')` are `true`; `bson-request-prop-equals(key=sub.foo, value='"baz"')` is `false`
+|`bson-request-array-contains` _from v7.5_
+|`true` if the request content is bson and the property `key` (can use the dot notation) is an array that contains all `values`
+|if the request content is `{ "a": [ "foo", "bar" ] }` then `bson-request-array-contains(key=a, values='"foo"' )` and `bson-request-array-contains(key=a, values={ '"foo"', '"bar"' } )` are `true`; `bson-request-array-contains(key=a, values={ '"foo"', '"baz"' } )` is `false`
+|`bson-request-array-is-subset` _from v7.5_
+|`true` if the request content is bson and the property `key` (can use the dot notation) is an array that is a subset of `values` |if the request content is `{ "a": [ "foo", "bar" ] }` then `bson-request-array-is-subset(key=a, values={ '"foo"', '"bar"', '"baz"' })` is `true`; `bson-request-array-is-subset(key=a, values={ '"foo"', '"baz"' })` is `false`
+|===
+
+*Note*: the double quotes in `values` since each element must be valid bson such as `1` (number), `"1"` (string), `"bar"` (string) or `{"foo": "bar"}` (object)
+
+=== MongoPermissions
+
+For requests handled by the `MongoService` (i.e. the service that implements the REST API for MongoDB) the permission can specify the `MongoPermissions` object.
+
+[source,json]
+----
+{
+ "mongo": {
+ "allowManagementRequests": false,
+ "allowBulkPatch": false,
+ "allowBulkDelete": false,
+ "allowWriteMode": false,
+ "readFilter": {"$or": [ {"status": "public"}, {"author": "@user._id"} ] },
+ "writeFilter": {"author": "@user._id"},
+ "mergeRequest": {"author": "@user._id"},
+ "projectResponse": {"secret": 0 }
+ }
+}
+----
+
+[options="header"]
+[cols="2,1"]
+|===
+|mongo permission |description
+|`allowManagementRequests`
+|DB Management Requests are forbidden by default (create/delete/update dbs, collection, file buckets schema stores and schemas, list/create/delete indexes, read db and collection metadata). To allow these requests, `allowManagementRequests` must be set to `true`
+|`allowBulkPatch`
+|bulk PATCH requests are forbidden by default, to allow these requests, `allowBulkPatch` must be set to `true`
+|`allowBulkDelete`
+|bulk DELETE requests are forbidden by default, to allow these requests, `allowBulkDelete` must be set to `true`
+|`allowWriteMode`
+|requests cannot use the query parameter `?wm=insert\|update\|upsert` by default. To allow it, `allowWriteMode` must be set to `true`
+|===
+
+Note that, in order to allow those requests, not only the corresponding flag must be set to `true` but the permission `predicate` must resolve to `true`.
+
+Consider the following examples.
+
+The next one won't allow the role `user` to execute a bulk PATCH even if the `allowBulkPatch` is `true` since the `predicate` requires the request verb to be `GET`
+
+[source,json]
+----
+{
+ "roles": [ "user" ],
+ "predicate": "path-prefix('coll') and method(GET)"
+ "mongo": {
+ "allowBulkPatch": true
+ }
+}
+----
+
+The next request allows to PATCH the collection `coll` and all documents in it, but won't allow to execute a bulk PATCH (i.e. the request `PATCH /coll/*?filter={ "status": "draft" }` since the `allowBulkPatch` is `false`
+
+[source,json]
+----
+{
+ "roles": [ "user" ],
+ "predicate": "path-prefix('coll') and method(PATCH)",
+ "mongo": {
+ "allowBulkPatch": false
+ }
+}
+----
+
+==== readFilter and writeFilter
+
+TIP: `readFilter` and `writeFilter` allows to partition data by roles.
+
+These are optional filters that are added to read and write requests respectively when authorized by an ACL permission that defines them.
+
+The `readFilter` applies to GET requests to limits the returned document to the ones that match the specified condition.
+
+The `writeFilter` applies to write request to allow updating only the documents that match the specified condition.
+
+WARNING: `writeFilter` only limits updates and cannot avoid creating documents that don't match the filter. The properties used in the filter should be set using `mongo.mergeRequest`.
+
+==== mergeRequest
+
+`mergeRequest` allows to merge the specified properties to the request content. In this way, server-side evaluated properties can be enforced.
+
+In the following example:
+
+[source,json]
+----
+{
+ "roles": [ "user" ],
+ "predicate": "path-prefix('coll') and method(PATCH)",
+ "mongo": {
+ "mergeRequest": {"author": "@user._id"}
+ }
+}
+----
+
+the property `author` is evaluated to be the `userid` of the authenticated client.
+
+`@user` is a special variable that allows accessing the properties of the user object. The following variables are available:
+
+[options="header"]
+[cols="2,1"]
+|===
+|variable |description
+|`@user`
+|the user object (excluding the password), e.g. `@user.userid` (for users defined in acl.yml by `FileRealmAuthenticator`) or `@user._id` (for users defined in MongoDB by `MongoRealmAuthenticator`)
+|`@request`
+|the properties of the request, e.g. `@request.remoteIp`
+|`@mongoPermissions`
+|the `MongoPermissions` object, e.g. `@mongoPermissions.writeFilter`
+|`@now`
+|the current date time
+|`@filter`
+|the value of the `filter` query parameter
+|===
+
+==== projectResponse
+
+`projectResponse` allows to project the response content, i.e. to remove properties.
+
+It can be used with positive or negative logic.
+
+The following hides the properties `secret` and `a.nested.secret` (you can use the dot notation!). All other properties are returned.
+
+[source,json]
+----
+{
+ "roles": [ "user" ]
+ "predicate": "path-prefix('coll') and method(PATCH)",
+ "mongo": {
+ "projectResponse": {"secret": 0, "a.nested.secret": 0 }
+ }
+}
+----
+
+The following only returns the property `public` (you can use the dot notation!). All other properties are hidden.
+
+[source,json]
+----
+{
+ "roles": [ "user" ]
+ "predicate": "path-prefix('coll') and method(PATCH)",
+ "mongo": {
+ "projectResponse": {"public": 1 }
+ }
+}
+----
+
+== File ACL Authorizer
+
+_fileAclAuthorizer_ allows defining roles permissions in the configuration or in a separate YAML configuration file.
+
+[source,yml]
+----
+fileAclAuthorizer:
+ #conf-file: ./acl.yml
+ permissions:
+ - role: admin
+ predicate: path-prefix('/')
+ priority: 0
+----
+
+NOTE: defining the ACL directly in the configuration rather than on a separate `acl.yml` file is available from RESTHeart v7.2
+
+The `conf-file` path is either absolute, or relative to the restheart configuration file (if specified) or relative to the plugins directory (if using the default configuration).
+
+The permission's options are fully equivalent to the ones handled by the _mongoAclAuthorizer_, only the yml format is used in place of Json.
+
+An example follows (for more examples check link:https://github.com/SoftInstigate/restheart/blob/master/examples/example-conf-files/acl.yml[acl.yml]):
+
+[source,yml]
+----
+ roles: [ "user" ]
+ predicate: >
+ method(GET) and path-template('/{userid}') and equals(@user._id, ${userid}) and qparams-contain(page) and qparams-blacklist(filter, sort)
+ priority: 100
+ mongo:
+ readFilter: >
+ { "_$or": [{ "status": "public" }, { "author": "@user._id" }] }
+ projectResponse: >
+ { "log": 0 }
+----
+
+TIP: Watch link:https://www.youtube.com/watch?v=QVk0aboHayM&t=1553s[Authorization via file and MongoDB]
diff --git a/docs/v7/security/how-clients-authenticate.adoc b/docs/v7/security/how-clients-authenticate.adoc
new file mode 100644
index 00000000..6c2ba6a8
--- /dev/null
+++ b/docs/v7/security/how-clients-authenticate.adoc
@@ -0,0 +1,144 @@
+---
+title: How Clients Authenticate
+layout: docs-adoc
+menu: setup
+---
+
+== Introduction
+
+Clients can authenticate passing credentials via the different authentication schemes handled by restheart-security.
+This section shows how clients can authenticate using the simple link:https://en.wikipedia.org/wiki/Basic_access_authentication[basic authentication],
+a standard method for an HTTP user agent to provide a *username* and
+*password* when making a request.
+
+## Some examples
+
+With link:https://github.com/jkbrzt/httpie[httpie] use the `-a` option:
+
+
+[source,bash]
+$ http -a userid:password GET 127.0.0.1:8080/
+
+With **curl**, use the `–user` options
+
+
+[source,bash]
+$ curl -i --user userid:password -X GET 127.0.0.1:8080/
+
+== Basic Authentication for dummies
+
+Basic Authentication requires the client to send its credentials with
+the **Authorization** request header.
+
+The value of the *Authorization* request header must be:** Basic
+base64(<userid> + ':' + <password>)**
+
+In other words:
+
+1. userid and password are combined into a string "userid:password".
+ **Note** the colon between userid and password (userid cannot
+ contain the ":" character).
+2. The resulting string is base 64 encoded
+3. The string "Basic " (**note** the space) is then put before the
+ encoded string.
+
+== Authentication Token
+
+RESTHeart default configuration includes the **tokenBasicAuthMechanism** and the **rndTokenManager**.
+
+With those plugins enabled, when a request is successfully authenticated, an auth token is generated by the Token Manager and included in every subsequent responses.
+
+the **tokenBasicAuthMechanism** allows to authenticate the client using the auth token; the auth token is used as a temporary password in the basic
+authentication scheme. This means that the *Authorization* request
+header can either be calculated from the the Auth-Token itself:
+
+`Authorization: Basic base64( + ':' + ) or Authorization: Basic base64( + ':' + )`
+
+Auth token information are passed in the following response headers:
+
+
+[source,http]
+----
+Auth-Token: 6a81d622-5e24-4d9e-adc0-e3f7f2d93ac7
+Auth-Token-Location: /tokens/user@si.com
+Auth-Token-Valid-Until: 2015-04-16T13:28:10.749Z
+----
+
+NOTE: the URI in the Auth-Token-Location header: the client can issue
+a GET request to obtain information about token or a DELETE request to
+invalidate it. Of course clients can only request their own tokens
+(otherwise response code will be 403 Forbidden).
+
+TIP: The Authentication Token is a very important feature when you are
+developing a web application. Since every request needs to include the
+credentials, you need to store them either in a cookie or (better) in
+the session storage. The sign-in form can check the credentials using
+the actual password; if it succeeds, the auth token can be stored and
+used.
+
+WARNING: Pay attention to the authentication token in case of multi-node
+deployments (horizontal scalability). In this case, you need to either
+disable it or use a load balancer with the sticky session option or a different Token Manager implementation.
+
+The `rndTokenManager` can be configured as follows (note option `TTL` the auth token Time To Live in minutes):
+
+
+[source,yml]
+----
+rndTokenManager:
+ ttl: 15
+ srv-uri: /tokens
+----
+
+=== Suggested way to check credentials
+
+The default restheart configuration file sets up the useful service **roles**, bound to `/roles/`
+
+The possible response codes of the request GET `/roles/`
+are:
+
+- **401 Unauthorized** missing or wrong credentials
+- **403 Forbidden** the *userid* in the URL does not match the one in
+ the *Authorization* header
+- **200 OK** credentials match; the following response document is
+ sent back:
+
+
+[source,json]
+----
+ {
+ "authenticated": true,
+ "roles": [
+ "USER"
+ ]
+}
+----
+
+Of course, if the request succeeds, the client gets back the auth token
+as well.
+
+NOTE: It is easy to check the user credentials from a login form with this
+handler: in case the client gets back 200, they match and the auth token
+can be stored for further request; otherwise passed credentials are
+wrong.
+
+== How to avoid the basic authentication popup in browsers
+
+With basic authentication, browsers can show a awful login popup window
+and this is not what you usually want.
+
+What happens behind the scene, is that the server sends
+the `WWW-Authenticate` response header that actually leads to it.
+
+You can avoid RESTHeart to actually send this header avoiding the popup
+login window altogether, either specifying
+the `No-Auth-Challenge` request header or using
+the `noauthchallenge` query parameter. In this case, RESTHeart will just
+respond with **401 Unauthorized** in case of missing or wrong
+credentials.
+
+TIP: This feature together with the authentication token, allows you to
+implement a form based authentication experience on top of the simple
+and effective basic authentication mechanism.
+
+TIP: Watch link:https://www.youtube.com/watch?v=QVk0aboHayM&t=2262s[An application example (blog)]
\ No newline at end of file
diff --git a/docs/v7/security/other-security-plugins.adoc b/docs/v7/security/other-security-plugins.adoc
new file mode 100644
index 00000000..62e76a84
--- /dev/null
+++ b/docs/v7/security/other-security-plugins.adoc
@@ -0,0 +1,96 @@
+---
+title: Other Security Plugins
+layout: docs-adoc
+menu: security
+---
+
+== Introduction
+
+RESTHeart provides some general purpose security plugins that help hardening the security.
+
+== OriginVetoer
+
+`OriginVetoer` protects from CSRF attacks by forbidding requests whose Origin header is not whitelisted.
+
+It can configured as follows:
+
+[source,yml]
+----
+originVetoer:
+ enabled: true # <---- default is false
+ whitelist:
+ - https://restheart.org
+ - http://localhost
+ # optional list of paths for whose the Origin header
+ # is not checked. values can be absolute paths
+ # or patterns like /{var}/path/to/resource/*
+ # ignore-paths:
+ # - /{tenant}/bucket.files/{id}/binary
+ # - /coll/docid
+----
+
+== filterOperatorsBlacklist
+
+A global blacklist for MongoDb query operators in the `filter` query parameter.
+
+[source,yml]
+----
+filterOperatorsBlacklist:
+ blacklist: [ "$where" ]
+ enabled: true
+----
+
+With this default configuration, the request `GET /coll?filter={"$where": "...."}` is forbidden.
+
+== Brute Force Attack Guard
+
+bruteForceAttackGuard defends from brute force password cracking attacks
+by returning `429 Too Many Requests` when more than
+`max-failed-attempts` requests with wrong credentials
+are received in last 10 seconds from the same ip
+
+[source,yml]
+----
+bruteForceAttackGuard:
+ enabled: false
+ # max number of failed attempts in 10 seconds sliding window
+ # before returning 429 Too Many Requests
+ max-failed-attempts: 5
+ # if true, the source ip is obtained from X-Forwarded-For header
+ # this requires that header being set by the proxy, dangerous otherwise
+ trust-x-forwarded-for: false
+ # when X-Forwarded-For has multiple values,
+ # take into account the n-th from last element
+ # e.g. with [x.x.x.x, y.y.y.y., z.z.z.z, k.k.k.k]
+ # 0 -> k.k.k.k
+ # 2 -> y.y.y.y
+ x-forwarded-for-value-from-last-element: 0
+----
+
+When RESTHeart is behind a reverse proxy, the header `X-Forwarded-For` should be used in place of the remote ip (which in this case is the reverse proxy's one).
+
+If several tiers of reverse proxies are in place, `x-forwarded-for-value-from-last-element` option allows to select the correct value.
+
+== Root Role Guard
+
+NOTE: available from v7.5
+
+`rootRoleGuard` forbids accounts handled by `mongoAclAuthorizer` to gain the `root-role` defined by the `mongoAclAuthorizer`.
+
+NOTE: `rootRoleGuard` is enabled by default.
+
+The default authorizer `mongoAclAuthorizer` enables the `root-role: admin` by default.
+
+WARNING: clients with `root-role` can execute any request.
+
+Although a the `root-role` is very useful at testing and developing time, it is a security risk to leave it enabled, this is why the link:/docs/security/security-hardening[security hardening doc page] suggests to disable it by setting the configuration option `mongoAclAuthorizer.root-role: null`.
+
+In any case, an account handled by the `mongoRealAuthenticator` (that handles accounts with roles in a MongoDb collection) should never gain the `root-role` via a MongoService write requests as `PATCH /users/foo {"roles": ["admin"]}`.
+
+The default configuration follows:
+
+[source,yml]
+----
+rootRoleGuard:
+ enabled: true
+----
diff --git a/docs/v7/security/overview.adoc b/docs/v7/security/overview.adoc
new file mode 100644
index 00000000..c823e96a
--- /dev/null
+++ b/docs/v7/security/overview.adoc
@@ -0,0 +1,44 @@
+---
+title: Security Overview
+layout: docs-adoc
+menu: framework
+---
+
+== Introduction
+
+RESTHeart provides **Authentication** and **Authorization** services. It can handle different authentication and authorization schemes, including handling users and permissions stored in MongoDB collections.
+
+The default configuration file enables `mongoRealmAuthenticator` and `mongoAclAuthorizer`. These use MongoDB collections (by default `/users` and `/acl` respectively) to handle users credentials and permissions respectively.
+
+RESTHeart can also handle users and permissions stored on configuration files via `fileRealmAuthenticator` and `fileAclAuthorizer`. Enabling these plugins requires updating the configuration.
+
+TIP: Watch link:https://www.youtube.com/watch?v=QVk0aboHayM&t=77s[Authentication and Authorization in RESTHeart]
+
+TIP: Watch link:https://www.youtube.com/watch?v=QVk0aboHayM&t=123s[Understanding RESTHeart security]
+
+== Understanding RESTHeart security
+
+RESTHeart is built around a **pluggable architecture**. It comes with a strong security implementation but you can extend it by implementing plugins.
+
+In RESTHeart everything is a plugin including Authentication Mechanisms, Authenticators, Authorizers, Token Managers and Services.
+
+[img-fluid]
+image::/images/restheart-security-explained.png[restheart-security explained]
+
+Different **Authentication Mechanisms** manage different authentication schemes.
+An example is _BasicAuthMechanism_ that handles the Basic Authentication scheme. It extracts the credentials from a request header and passes them to the an Authenticator for verification.
+
+A different example is the _IdentityAuthMechanism_ that binds the request to a single identity specified by configuration. This Authentication Mechanism does not require an Authenticator to build the account.
+
+RESTHeart allows defining several mechanism. As an in-bound request is received, the `authenticate()` method is called on each mechanism in turn until one of the following occurs:
+
+- no `VETOER` denies it and at least one `ALLOWER` allows it → the request proceeds to Authorization phase;
+- The list of mechanisms is exhausted → the request fails with code `401 Unauthorized`.
+
+The **Authenticator** verifies the credentials extracted from the request by Authentication Mechanism. For instance, the _BasicAuthMechanism_ extracts the credentials from the request in the form of id and password. The Authenticator can check these credentials against a database or a LDAP server. Note that some Authentication Mechanisms don't actually rely on a Authenticator to build the Account.
+
+The **Authorizer** is responsible of checking if the user can actually perform the request against an Access Control List. For instance the `mongoAclAuthorizer` checks if the request is allowed by looking at the permissions defined in a MongoDB collection.
+
+The **Token Manager** is responsible of generating and validating an auth-token. When a client successfully authenticates, the Token Manager generates an auth-token that is returned in the `Auth-Token` response header. It can be used to authenticate further requests. This requires an Authentication Manager to handle it using the Token Manager for token validation.
+
+A **Service** is a quick way of implementing Web Services to expose additional custom logic.
diff --git a/docs/v7/security/secure-connection-to-mongodb.md b/docs/v7/security/secure-connection-to-mongodb.md
new file mode 100644
index 00000000..fef42288
--- /dev/null
+++ b/docs/v7/security/secure-connection-to-mongodb.md
@@ -0,0 +1,152 @@
+---
+title: Secure connection to MongoDB
+layout: docs
+menu: security
+---
+
+`|`latest`, `7`, `7.5`, `7.5.0`|**The standard image.** This is usually the one you want to use. Keep in mind it doesn't support running JavaScript plugins. `docker pull softinstigate/restheart:latest`
+|`-distroless`|`latest-distroless`, `7-distroless`, `7.5-distroless`, `7.5.0-distroless` | Similar to the standard image, this image contains only RESTHeart and its runtime dependencies. It does not contain a package manager, shells or any other programs you would expect to find in a standard Linux distribution. `docker pull softinstigate/restheart:latest-distroless`
+|`-graalvm`|`latest-graalvm`, `7-graalvm`, `7.5-graalvm`, `7.5.0-graalvm` | RESTHeart running on the GraalVM that will let you JavaScript plugins. Check out the link:/docs/plugins/core-plugins-js[Plugins in JavaScript] for more info. This is the biggest image (about 600Mbytes). `docker pull softinstigate/restheart:latest-graalvm`
+|`-native`|`latest-native`, `7-native`, `7.5-native`, `7.5.0-native` | RESTHeart built as a native binary. It is the smallest image with lightning-fast startup time. This is the perfect choice for deploying in a Kubernetes cluster. It can only execute JavaScript plugins. Check out link:/docs/plugins/deploy#deploy-java-plugins-on-restheart-native[Deploy Java plugins on RESTHeart Native] for more info. `docker pull softinstigate/restheart:latest-native`
+|===
+
+== Dockerfile
+
+- link:https://github.com/SoftInstigate/restheart/blob/master/core/Dockerfile[Dockerfile]
+- link:https://github.com/SoftInstigate/restheart/blob/master/core/Dockerfile.distroless[Dockerfile.distroless]
+- link:https://github.com/SoftInstigate/restheart/blob/master/core/Dockerfile.graalvm[Dockerfile.graalvm]
+- link:https://github.com/SoftInstigate/restheart/blob/master/core/Dockerfile.native[Dockerfile.native]
+
+The "distroless" images are for special deployment requirements, where having the smallest possible image size and the very minimal security attack surface is required and their tag contains a `distroless` label. You usually don't need these images unless you exactly know what you are doing.
+
+Images tags ending with `-native` are created with the link:https://www.graalvm.org/reference-manual/native-image/[GraalVM Native Image technology] starting from stable builds of the product, especially suited for high demanding environments, like Kubernetes. These are experimental and not fully documented yet, please contact us for questions.
+
+== What's next
+
+- Check that RESTHeart is up and running, opening the URL link:http://localhost:8080/ping[http://localhost:8080/ping], you should see the message: `Greetings from RESTHeart!`
+- Check the link:/docs/configuration[Configuration] page
+- Play with the link:/docs/mongodb-rest/tutorial[REST API Tutorial]
+- Play with the link:/docs/mongodb-graphql/tutorial[GraphQL API Tutorial]
+- Deploy some plugins from the the link:https://github.com/SoftInstigate/restheart/tree/master/examples[plugin examples repo]
+- Load the link:/docs/mongodb-rest/sample-data[sample data] into MongoDB and play with the Data API.
diff --git a/docs/v7/setup.adoc b/docs/v7/setup.adoc
new file mode 100644
index 00000000..11bbeefc
--- /dev/null
+++ b/docs/v7/setup.adoc
@@ -0,0 +1,145 @@
+---
+title: Setup
+layout: docs-adoc
+menu: setup
+---
+
+TIP: The easiest way to run RESTHeart and MongoDB is with __Docker__, please go to link:/docs/setup-with-docker[Setup with Docker]
+
+== Download
+
+Download the ZIP or TAR archive.
+
+++++
+zip
+tgz
+
+++++
+
+Un-zip or un-tar
+
+[source,bash]
+----
+# if you downloaded the tar.gz
+$ tar -xzf restheart.tar.gz && cd restheart
+----
+
+[source,bash]
+----
+# if you downloaded the zip
+$ unzip restheart.zip && cd restheart
+----
+
+== Requirements
+
+RESTHeart only requires Java 17 or GraalVM >= 17.0.8 (v23.0.2 Java 17 based).
+
+== Run in standalone mode
+
+NOTE: standalone mode is available from RESTHeart 7.2
+
+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.
+
+[source,bash]
+----
+$ RHO="/fileRealmAuthenticator/users[userid='admin']/password->'secret'" java -jar restheart.jar -s
+----
+
+NOTE: the `RHO` environment variable sets the password for the user `admin`.
+
+[source,bash]
+----
+$ 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 4.2, 4.4, v5.0, v6.0 and v7.0
+
+To get RESTHeart and MongoDB up and running, use these commands:
+[source,bash]
+----
+# 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
+
+[source,text]
+----
+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:
+
+[source,bash]
+----
+$ 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:
+
+[source,bash]
+----
+$ 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`:
+
+[source,bash]
+----
+$ 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
+
+- Check that RESTHeart is up and running, opening the URL link:http://localhost:8080/ping[http://localhost:8080/ping], you should see the message: `Greetings from RESTHeart!`
+- Check the link:/docs/configuration[Configuration] page
+- Play with the link:/docs/mongodb-rest/tutorial[REST API Tutorial]
+- Play with the link:/docs/mongodb-graphql/tutorial[GraphQL API Tutorial]
+- Deploy some plugins from the the link:https://github.com/SoftInstigate/restheart/tree/master/examples[plugin examples repo]
+- Load the link:/docs/mongodb-rest/sample-data[sample data] into MongoDB and play with the Data API.
diff --git a/docs/v7/static-resources.adoc b/docs/v7/static-resources.adoc
new file mode 100644
index 00000000..9b6e592f
--- /dev/null
+++ b/docs/v7/static-resources.adoc
@@ -0,0 +1,27 @@
+---
+title: Serving static resources
+layout: docs-adoc
+menu: setup
+---
+
+== Introduction
+
+RESTHeart allows serving static resources acting as a Web Server.
+
+An example configuration follows:
+
+[source,yml]
+----
+#### Static Web Resources
+
+# Static web resources to bind to the URL specified by the 'where' property.
+# The 'what' property is the path of the directory containing the resources.
+# The path is either absolute (starts with /) or relative to the restheart.jar file
+# Set embedded: true, if resources are embedded in the file restheart.jar
+
+static-resources-mounts:
+ - what: /data/www
+ where: /static
+ welcome-file: index.html
+ embedded: false
+----
\ No newline at end of file
diff --git a/docs/v7/test-adoc.adoc b/docs/v7/test-adoc.adoc
new file mode 100644
index 00000000..c31f9a09
--- /dev/null
+++ b/docs/v7/test-adoc.adoc
@@ -0,0 +1,63 @@
+---
+layout: docs-adoc
+title: Test asciidoc
+---
+
+This is a sample page composed in AsciiDoc.
+Jekyll converts it to HTML using http://asciidoctor.org[Asciidoctor].
+
+== Intro
+
+This jekyll template with asciidoc
+
+== Github pages
+
+As long as I understood, github pages don't support adoc natively.
+
+However there is a github action that allow rendering asciidoc to html.
+
+== The cool code
+
+The problem is that the code is not very readable.
+
+[source,java]
+----
+public class Cool {
+ private boolean cool;
+
+ public Cool(){
+ this.cool = true;
+ }
+}
+----
+
+Here are the other built-in admonition types:
+
+NOTE: Some additional info...
+
+TIP: Pro tip...
+
+IMPORTANT: Don't forget...
+
+WARNING: Watch out for...
+
+CAUTION: Ensure that...
+
+[TIP]
+====
+Think of c1..c2 as _all commits as of c1 (not including c1) until commit
+c2._
+====
+
+
+[cols="1,2"]
+|===
+|Cell in column 1, row
+|Cell in column 2, row 1
+
+|Cell in column 1, row 2
+|Cell in column 2, row 2
+
+|Cell in column 1, row 3
+|Cell in column 2, row 3
+|===
\ No newline at end of file
diff --git a/docs/v7/tutorials.md b/docs/v7/tutorials.md
new file mode 100644
index 00000000..cd4e7b75
--- /dev/null
+++ b/docs/v7/tutorials.md
@@ -0,0 +1,43 @@
+---
+title: Other tutorials
+layout: docs
+menu: overview
+---
+
+
+
+- [Introduction](#introduction)
+- [Enable MongoDB authentication](#enable-mongodb-authentication)
+- [Restrict permissions of MongoDB user](#restrict-permissions-of-mongodb-user)
+- [Connect to MongoDB over TLS/SSL](#connect-to-mongodb-over-tlsssl)
+
+
+
+
+{% include docs-head.html %}
+
+## Introduction
+
+This section provides instructions on how to secure the connection between RESTHeart and MongoDB by enabling the MongoDB authentication, connect the two processes over TLS and restrict the permissions of the MongoDB user used by RESTHeart.
+
+## Enable MongoDB authentication
+
+This section assumes using MongoDB 3.2 or later. For other versions, the security
+configuration is similar but different. Refer to the [MongoDB
+documentation](https://docs.mongodb.org/manual/tutorial/enable-authentication/)
+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 `--fork` parameter.
+
+``` bash
+$ mongod --fork --syslog --auth
+$ mongo
+```
+
+In this section we will use the MongoDB superuser
+role [root](https://docs.mongodb.org/manual/reference/built-in-roles/#superuser-roles)
+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.
+
+Create the *admin* user. The procedure is different depending on MongoDB
+version.
+
+
+```javascript
+> use admin
+> db.createUser({
+ user: "admin",
+ pwd: "changeit",
+ roles:[ "root" ]
+})
+```
+
+We need to provide the MongoDB user authentication credentials in the RESTHeart Core configuration file: see docs.
+
+We’ll use the `restheart.yml` configuration file that comes with RESTHeart download package (you find it in the etc directory)
+
+
+``` bash
+$ vi etc/restheart.yml
+```
+
+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’).
+
+
+``` yml
+mongo-uri: mongodb://admin:changeit@127.0.0.1/?authSource=admin
+```
+
+Now start RESTHeart Core specifying the configuration file:
+
+``` bash
+$ java -jar restheart.jar etc/restheart.yml -e etc/default.properties
+```
+
+Test the connection open `http://localhost:8080/roles/admin`
+
+## Restrict permissions of MongoDB user
+
+In the previous examples we used a MongoDB user with *root* role for the sake of simplicity. This allows RESTHeart Core 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:
+
+1. use the mongo-mounts configuration option to restrict the resources exposed by RESTHeart Core;
+2. use a MongoDB user with just enough permission: *read* or *readWrite* on mounted databases
+
+The following example, creates a MongoDB user with appropriate roles to expose the databases *restheart.
+
+
+```javascript
+> use admin
+> db.createUser({user: "restheart",
+ pwd: ,
+ roles: [{role: "readWrite", db: "restheart"},
+ {role: "clusterMonitor", db: "admin"}
+]})
+```
+
+The built-in role `clusterMonitor` is needed to check the replica set status of MongoDB.
+
+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.
+
+## Connect to MongoDB over TLS/SSL
+
+In case MongoDB uses a __public TLS/SSL certificate__ there is nothing to configure on RESTHeart, except for the proper [Connection String URI Format](https://docs.mongodb.com/manual/reference/connection-string/).
+
+To configure RESTHeart for using instead a __private TLS/SSL certificate__ (read [What’s the Difference Between a Public and Private Trust Certificate?](https://www.entrust.com/it/blog/2019/03/difference-between-a-public-and-private-trust-certificate/)) do as follows:
+
+* create the keystore importing the certificate used by `mongod` using `keytool` (with `keytool`, the java tool to manage `keystores` of cryptographic keys)
+
+
+``` bash
+$ keytool -importcert -file mongo.cer -alias mongoCert -keystore rhTrustStore
+
+# asks for password, use "changeit"
+```
+
+* specify the ssl option in the `mongo-uri` in the restheart yml configuration file:
+
+
+``` yml
+mongo-uri: mongodb://your.mongo-domain.com?ssl=true
+```
+* start restheart with following options:
+
+
+``` bash
+$ java -Dfile.encoding=UTF-8 -server -Djavax.net.ssl.trustStore=rhTrustStore -Djavax.net.ssl.trustStorePassword=changeit -Djavax.security.auth.useSubjectCredsOnly=false -jar restheart.jar etc/restheart.yml -e etc/default.properties
+```
+
+References from MongoDB docs:
+ - [TLS/SSL Configuration for Clients](https://docs.mongodb.com/manual/tutorial/configure-ssl-clients/#tls-ssl-configuration-for-clients)
+ - [Standard Connection String Format](https://docs.mongodb.com/manual/reference/connection-string/#standard-connection-string-format)
+ - [DNS Seed List Connection Format](https://docs.mongodb.com/manual/reference/connection-string/#dns-seed-list-connection-format)
+
+
diff --git a/docs/v7/security/security-hardening.adoc b/docs/v7/security/security-hardening.adoc
new file mode 100644
index 00000000..51a2a0a3
--- /dev/null
+++ b/docs/v7/security/security-hardening.adoc
@@ -0,0 +1,239 @@
+---
+title: Security Hardening
+layout: docs-adoc
+menu: setup
+---
+
+== Introduction
+
+This section describes the security hardening features available with RESTHeart
+and some best practices to protect against common attacks.
+
+IMPORTANT: No system can guarantee 100% security. Security must be achieved through
+a set of security hardening measures implemented on the whole system stack
+and enforced by strong and efficient security policies.
+
+*Checklist*
+
+[.table]
+[cols="2,1,1"]
+|===
+|*Best practice* |*Priority* |*Impact*
+|Update the `admin` user password|Mandatory|Action required
+|Disable the root role|Suggested|Configuration required
+|Disable the auto-creation of the `admin` user|Suggested|Configuration required
+|Use HTTPS|Mandatory|Action required
+|Secure connection to MongoDB|Mandatory|Action required
+|Make sure password are stored in an encrypted form|Mandatory|No action required if the default authenticator is used
+|Enforce strong passwords|Mandatory|Configuration required
+|Enable bruteForceAttackGuard|Suggested|Configuration required
+|Enable originVetoer|Suggested|Configuration required
+|Define and test the ACL|Mandatory|Action required
+|Use only aggregations and forbid the filter query parameter|Suggested|Action required
+|Blacklist the $where MongoDB operator|Mandatory|No action required
+|Define role-specific GraphQL applications|Mandatory|Action required
+|===
+
+== Update the `admin` user password
+
+At first startup, RESTHeart initializes the user `admin`, with the default password `secret`. *This user can execute any request*.
+
+WARNING: *YOU MUST UPDATE THE DEFAULT PASSWORD!* The role `admin` can execute any request as it is set as the `root` role in the `mongoAclAuthorizer` configuration.
+
+To update it, run the following command:
+
+[source,bash]
+$ curl -u admin:secret -X PATCH localhost:8080/users/admin -H "Content-Type: application/json" -d '{ "password": "my-strong-password" }'
+
+Refer to link:/docs/security/user-management/[User Management] for more information on how to create new users, roles and permissions.
+
+== Disable the auto-creation of the admin user
+
+At startup time, the `mongoRealmAuthenticator` checks if the user `admin` exists. If it does not exist, it automatically creates it. This means that whenever the user `admin` is deleted, it will be eventually recreated with the default password `secret`.
+
+To avoid this dangerous behavior, you should disable the auto-creation of the `admin` user:
+
+[source,yml]
+----
+mongoRealmAuthenticator:
+# other options omitted
+# clients with root-role can execute any request
+create-user: false # <---- disable auto-creation of the admin user
+create-user-document: '{"_id": "admin", "password": "secret", "roles": ["admin"]}'
+----
+
+== Disable the root role
+
+The `mongoAclAuthorizer` by default defines the _root_ role.
+
+[source,yml]
+----
+mongoAclAuthorizer:
+ # other options omitted
+ # clients with root-role can execute any request
+ root-role: admin
+----
+
+WARNING: this role is granted all permission, including reading and deleting any MongoDb resource.
+
+When you have setup your ACL, the `root` role can be disabled as follow:
+
+[source,yml]
+----
+mongoAclAuthorizer:
+ # other options omitted
+ # root role disabled!
+ root-role: null
+----
+
+== Use HTTPS
+
+WARNING: *IT IS PARAMOUNT TO SECURE RESTHEART WITH TLS.*
+
+This can be achieved either by a reverse proxy (such as Nginx, AWS API gateway, etc)
+or by configuring RESTHeart to only use the https-listener.
+
+To configure RESTHeart to use TLS, follow the instructions at link:/docs/security/tls/[Configure TLS].
+
+== Secure connection to MongoDB
+
+To configure RESTHeart to connect to MongoDB over TLS, follow the instructions at link:/docs/mongodb-rest/secure-connection-to-mongodb/[Secure connection to MongoDB].
+
+It is also very important to restrict the access to the MongoDB database to only the resources that are required by RESTHeart; for this refer to link:/docs/mongodb-rest/secure-connection-to-mongodb/#restrict-permissions-of-mongodb-user[Restrict permissions of MongoDb User].
+
+== Make sure password are stored in an encrypted form
+
+Passwords must be stored in an encrypted form.
+
+The default `mongoRealmAuthenticator` is recommended for production use and it does store the password in an encrypted form with the default configuration.
+
+[source,yml]
+----
+mongoRealmAuthenticator:
+ # omitting other options
+ bcrypt-hashed-password: true
+ bcrypt-complexity: 12
+----
+
+The `fileRealmAuthenticator` is for testing and development purposes only and not suggested for production use, since it does not support password hashing.
+
+IMPORTANT: If you use a custom _Authenticator_ you must make sure that the passwords are stored in an encrypted form.
+
+== Enforce strong passwords
+
+If users can update their password, it is important enforcing that user-defined passwords are strong enough and avoid a user to chose a weak password like `123456`.
+
+The default `mongoRealmAuthenticator` is recommended for production use and it allows to refuse to update user documents with weak passwords.
+
+[source,yml]
+----
+mongoRealmAuthenticator:
+ # omitting other options
+ enforce-minimum-password-strenght: false
+ # Integer from 0 to 4
+ # 0 Weak （guesses < 3^10）
+ # 1 Fair （guesses < 6^10）
+ # 2 Good （guesses < 8^10）
+ # 3 Strong （guesses < 10^10）
+ # 4 Very strong （guesses >= 10^10）
+ minimum-password-strength: 3
+----
+
+== bruteForceAttackGuard
+
+`bruteForceAttackGuard` defends from brute force password cracking attacks
+by returning `429 Too Many Requests` when more than `max-failed-attempts` wrong requests are received in last 10 seconds from the same ip.
+
+IMPORTANT: if RESTHeart is behind a revers proxy, this must set the header `X-Forwarded-For` with the client IP. In this case set the option `trust-x-forwarded-for: true`
+
+[source,yml]
+----
+# defends from brute force password cracking attacks
+# by returning `429 Too Many Requests` when more than
+# `max-failed-attempts` wrong requests
+# are received in last 10 seconds from the same ip
+bruteForceAttackGuard:
+ enabled: false
+ # if true, the source ip is obtained from X-Forwarded-For header
+ # this requires that header being set by the proxy, dangerous otherwise
+ trust-x-forwarded-for: false
+ # max number of failed attempts in 10 seconds sliding window
+ # before returning 429 Too Many Requests
+ max-failed-attempts: 5
+----
+
+== originVetoer
+
+`originVetoer` protects from CSRF attacks by forbidding requests whose Origin header is not whitelisted
+
+NOTE: this is disable by default and musts be activated by adding the following configuration with the correct whitelist to your `restheart.yml` file:
+
+[source,yml]
+----
+# originVetoer protects from CSRF attacks by forbidding requests whose Origin header is not whitelisted
+originVetoer:
+ enabled: true
+ whitelist:
+ - https://restheart.org
+ - https://restheart.com
+----
+
+== Define and test the ACL
+
+The `mongoAclAuthorizer` allows to define a very fine grained, role based ACL.
+
+The permissions set must allow to execute just the required requests, blacklisting unused query parameters, projecting the response to hide sensitive data, merging the request body with sensitive properties at the server-side, filtering writes and reads.
+
+The following permission document is an example of a very fine grained ACL:
+
+[source,json]
+----
+{
+ "_id": "userCanCreateDocumentsInOwnCollection",
+ "description": [
+ "**** DESCRIPTION PROPERTY IS NOT REQUIRED, HERE ONLY FOR DOCUMENTATION PURPOSES",
+ "allow role 'user' to create documents under /{userid}",
+ "the request content must contain 'title' and 'content' <- bson-request-contains(title, content)",
+ "the request content cannot contain any property other than 'title' and 'content' <- bson-request-whitelist(title, content)",
+ "no qparams can be specified <- qparams-whitelist()",
+ "the property 'author' and 'status' are added to the request at server-side <- mergeRequest",
+ "the property 'log' with some request values is added to the request at server-side <- mergeRequest"
+ ],
+ "roles": ["user"],
+ "priority": 100,
+ "predicate": "method(POST) and path-template('/{userid}') and equals(@user._id, ${userid}) and bson-request-whitelist(title, content) and bson-request-contains(title, content) and qparams-whitelist()",
+ "mongo": {
+ "mergeRequest": {
+ "author": "@user._id",
+ "status": "draft",
+ "log": "@request"
+ }
+ }
+ }
+----
+
+Refer to link:/docs/security/authorization/#format-of-permissions[Format of permission] for more information.
+
+NOTE: When the permission language cannot be used and you need more control, you can define a custom `Vetoer` or an `Request Interceptor` that can enforce additional checking logic.
+
+== Use only aggregations and forbid the `filter` query parameter
+
+The `filter` query parameter for the Mongo REST API allows clients to execute any MongoDB query.
+
+This is very convenient at development time, however when you are ready to deploy your application, you should blacklist the `filter` query parameter in your ACL and rely on link:/docs/mongodb-rest/aggregations/[Aggregations] to expose, well defined and secured queries.
+
+== Blacklist the `$where` MongoDB operator
+
+If you cannot disable the `filter` query parameter, you can blacklist unused operators, using the `filterOperatorsBlacklist` plugin.
+
+The `$where` MongoDB query operator is dangerous and should not be used in any case.
+
+NOTE: `filterOperatorsBlacklist` is enabled by default and blacklists `$where`.
+
+== Define role-specific GraphQL applications
+
+NOTE: The GraphQL API is read-only, so you should only pay attention to avoid exposing sensitive information to users. This very important due to the nature of GraphQL that allows the client to request data in any format allowed by the GraphQL schema.
+
+In order secure the GraphQL API, several GraphQL applications should be defined with different read logic and bound to different URIs. In this way, different roles can be granted access to different subsets of the GraphQL apps thus protecting the information.
+
+WARNING: Protecting the GraphQL API requires the application definitions to be defined with the correct filtering options. Always test your APIs!
\ No newline at end of file
diff --git a/docs/v7/security/tls.adoc b/docs/v7/security/tls.adoc
new file mode 100644
index 00000000..4ee3e65e
--- /dev/null
+++ b/docs/v7/security/tls.adoc
@@ -0,0 +1,70 @@
+---
+title: Configure TLS
+layout: docs-adoc
+menu: security
+---
+
+== Introduction
+
+This section provides instructions on how to enable Transport Layer Security so that requests can be served over the HTTPS protocol.
+
+WARNING: HTTP is not secure: credentials can be sniffed by a man-in-the-middle attack. **It is paramount to use HTTPS**
+
+NOTE: This section is about securing HTTP requests between Clients and RESTHeart. Read link:/docs/mongodb-rest/secure-connection-to-mongodb/[Secure connection to MongoDB] for more information on how to secure the connection between RESTHeart and MongoDB.
+
+== The HTTPS listener
+
+There are many ways of enabling HTTS; for instance you can setup a web server such as nginx as a reverse proxy in front of RESTHeart or you may rely on cloud services that provides load balancers that manages SSL for you (such are Amazon WS or Google Cloud).
+
+In any case, restheart is able to expose directly the HTTS protocol and this is done configuring the https listener. This is the suggested configuration for small systems.
+
+The following configuration file except shows the involved options:
+
+[source,bash]
+----
+https-listener:
+ enabled: true
+ host: 0.0.0.0
+ port: 4443
+ keystore-file: /path/to/keystore/file
+ keystore-password: secret
+ certpassword: secret
+----
+
+To enable https configure the https listener using the following options:
+
+1. `/https-listener/enabled` _true_ to enable it
+2. `/https-listener/host` the ip where to bind the listener
+3. `/https-listener/port` the port where to bind the listener:
+
+A SSL certificate must configured in order to enable the https listener.
+
+== Configure the SSL certificate
+
+The SSL certificate must be added to the java keystore set by the `keystore-file` configuration property.
+
+Two scripts are available to help configuring the keystore.
+
+=== generate-certauthority-and-keystore.sh
+
+This is useful for testing purposes. It generates a CA and uses it to issue a SSL certificate, finally generating the keystore file.
+
+Download the script from link:https://raw.githubusercontent.com/SoftInstigate/restheart/master/core/bin/generate-certauthority-and-keystore.sh[generate-certauthority-and-keystore.sh]
+
+After having generated the keystore file and configured RESTHeart to use it, you need to install the CA root certificate into your OS.
+
+For example, in OSX:
+
+1. Open up `Keychain Access` application by searching it on `Spotlight`
+2. Select `File > Import Items`. Navigate to CA root certificate file generated by the script. Select `System` as "Destination Keychain".
+3. Right click on the certificate in Keychain Access and select `Get Info`
+ - Expand the Trust section
+ - Under When using this certificate select `Always Trust`.
+
+=== convert-letsencrypt-java-keystore.sh
+
+link:https://letsencrypt.org[Let's Encrypt] is a popular and nonprofit Certificate Authority providing free TLS certificates.
+
+This script generates the java keystore from Let's Encrypt certificate archive.
+
+Download the script from link:https://raw.githubusercontent.com/SoftInstigate/restheart/master/core/bin/convert-letsencrypt-java-keystore.sh[convert-letsencrypt-java-keystore.sh]
\ No newline at end of file
diff --git a/docs/v7/security/tutorial.adoc b/docs/v7/security/tutorial.adoc
new file mode 100644
index 00000000..59258709
--- /dev/null
+++ b/docs/v7/security/tutorial.adoc
@@ -0,0 +1,183 @@
+---
+title: Authentication and Authorization tutorial
+layout: docs-adoc
+menu: security
+---
+
+This tutorial aims to provide a thorough understanding of securing RESTHeart applications. RESTHeart offers robust security features, with **Authentication** and **Authorization** being central to these. This guide will explore the basic authentication. We'll also delve into authorization, focusing on Access Control Lists (ACLs) and their role in defining permissions.
+
+By the end of this tutorial, you'll have a solid foundation in securing RESTHeart applications, ensuring data security and controlled access.
+
+== What you need
+
+1. **Docker**: For running RESTHeart.
+2. **HTTPie**: A user-friendly command-line HTTP client. Download at link:https://httpie.io/cli[httpie.io/cli^].
+
+== Starting RESTHeart and MongoDB
+
+To begin, create a directory for RESTHeart and use Docker Compose to start both RESTHeart and MongoDB:
+
+[source,bash]
+----
+$ mkdir restheart && cd restheart
+$ curl https://raw.githubusercontent.com/SoftInstigate/restheart/master/docker-compose.yml --output docker-compose.yml
+$ docker compose up --attach restheart
+----
+
+== The Admin User
+
+Upon first launch, `mongoRealmAuthenticator` creates an `admin` user with default password `secret` and the `admin` role. This role is configured as the root role in `mongoAclAuthorizer`, granting full permissions.
+
+WARNING: **Always change the `admin` user's password** to maintain security.
+
+To change the `admin` password:
+
+[source,bash]
+$ http -a admin:secret PATCH :8080/users/admin password="my-strong-password"
+
+== Creating Collection /secrets
+
+Using `admin`, create the `/secrets` collection:
+
+[source,bash]
+$ http -a admin:secret PUT :8080/secrets
+
+== Creating Users alice and bob
+
+Next, create two users, `alice` and `bob`, each with the `user` role:
+
+[source,bash]
+----
+$ http -a admin:secret POST :8080/users _id=alice password=secret roles:='["user"]'
+$ http -a admin:secret POST :8080/users _id=bob password=secret roles:='["user"]'
+----
+
+== Understanding Status Codes
+
+The `/users/{id}` endpoint can verify credentials. For example, using incorrect credentials for `alice`:
+
+[source,bash]
+----
+$ http -a alice:wrong GET :8080/secrets
+HTTP/1.1 401 Unauthorized
+----
+
+IMPORTANT: A `401 Unauthorized` response indicates failed authentication due to incorrect credentials. RESTHeart blocks requests to secure services without proper authentication.
+
+Attempting access with correct credentials:
+
+[source,bash]
+----
+$ http -a alice:secret GET :8080/secrets
+HTTP/1.1 403 Forbidden
+----
+
+IMPORTANT: A `403 Forbidden` response means authentication succeeded, but the client lacks permission to access the resource.
+
+RESTHeart's default authorizer, `mongoAclAuthorizer`, enforces permissions based on user roles and ACL configurations.
+
+== Configuring Access for user Role on /secrets
+
+We aim to allow `user` role to create and access their own documents in `/secrets`, and to modify only their documents.
+
+1) **Allow `GET` on `/secrets`**:
+
+Users can only access documents they created.
+
+[source,bash]
+----
+{
+ "_id": "userCanAccessOwnSecret",
+ "roles": [ "user" ],
+ "predicate": "method(GET) and path('/secrets')",
+ "priority": 100,
+ "mongo": { "readFilter": "{ author: @user._id }" }
+}
+----
+
+2) **Allow `POST` on `/secrets`**:
+
+Users can create new documents, setting the `author` to their `_id`.
+
+[source,bash]
+----
+{
+ "_id": "userCanCreateOwnSecret",
+ "roles": [ "user" ],
+ "predicate": "method(POST) and path('/secrets')",
+ "priority": 100,
+ "mongo": { "mergeRequest": { "author": "@user._id" } }
+}
+----
+
+3) **Allow `PATCH` on `/secrets/{id}`**:
+
+Users can modify only their documents.
+
+[source,bash]
+----
+{
+ "_id": "userCanModifyOwnSecret",
+ "roles": [ "user" ],
+ "predicate": "method(PATCH) and path-template('/secrets/{id}')",
+ "priority": 100,
+ "mongo": { "writeFilter": { "author": "@user._id" } }
+}
+----
+
+To create these permissions, use the following commands:
+
+[source,bash]
+----
+$ http -a admin:secret POST :8080/acl _id=userCanAccessOwnSecret roles:='["user"]' priority:=100 predicate="method(GET) and path('/secrets')" mongo.readFilter:='{ "author": "@user._id" }'
+----
+
+[source,bash]
+----
+$ http -a admin:secret POST :8080/acl _id=userCanCreateOwnSecret roles:='["user"]' priority:=100 predicate="method(POST) and path('/secrets')" mongo.mergeRequest:='{ "author": "@user._id" }'
+----
+
+[source,bash]
+----
+$ http -a admin:secret POST :8080/acl _id=userCanModifyOwnSecret roles:='["user"]' priority:=100 predicate="method(PATCH) and path-template('/secrets/{id}')" mongo.writeFilter:='{ "author": "@user._id" }'
+----
+
+== Creating Secret Documents
+
+Let's have `alice` and `bob` create their secrets:
+
+[source,bash]
+----
+$ http -a bob:secret POST :8080/secrets message="Bob loves Alice"
+$ http -a alice:secret POST :8080/secrets message="Alice loves Bob"
+----
+
+== Reading Secret Documents
+
+Viewing with `admin`:
+
+[source,bash]
+----
+$ http -a admin:secret -b GET :8080/secrets
+# Output includes both Alice's and Bob's messages
+----
+
+NOTE: The `author` property is correctly set for each document.
+
+Accessing `/secrets` as `alice`:
+
+[source,bash]
+----
+$ http -a alice:secret -b GET :8080/secrets
+# Output includes only Alice's message
+----
+
+Similarly, accessing as `bob`:
+
+[source,bash]
+----
+$ http -a bob:secret -b GET :8080/secrets
+# Output includes only Bob's message
+----
+
+Let's take a moment to acknowledge the story of Alice and Bob. These two characters are entwined in an 'impossible love' story that symbolizes the challenges of secure communication in the digital age. And RESTHeart is no exception keeping their love hidden in the /secrets collection.
\ No newline at end of file
diff --git a/docs/v7/security/user-management.adoc b/docs/v7/security/user-management.adoc
new file mode 100644
index 00000000..2ca04837
--- /dev/null
+++ b/docs/v7/security/user-management.adoc
@@ -0,0 +1,140 @@
+---
+title: User Management
+layout: docs-adoc
+menu: setup
+---
+
+:page-liquid:
+
+== Introduction
+
+This section provides instructions on how to create, update and delete users with the default authenticator link:/docs/security/authentication/#mongo-realm-authenticator[mongoRealAuthenticator].
+
+It also shows how to manage permissions with the default authorizer link:/docs/security/authorization/#mongo-acl-authorizer[mongoAclAuthorizer].
+
+NOTE: The `mongoRealAuthenticator` is configured to utilize the "/users" collection as its default storage location for user documents. Similarly, the `mongoAclAuthorizer` employs the "/acl" collection as its default repository for storing permissions.
+
+=== Before running the example requests
+
+The following examples assume RESTHeart running on the localhost with the default configuration: the database _restheart_ is bound to `/` and the user _admin_ exists with default password _secret_.
+
+== User document
+
+With the default configuration, a user is represented as follows:
+
+[source,json]
+----
+{
+ "_id": "username",
+ "roles": [ "list", "of", "roles" ],
+ "password": "secret"
+}
+----
+
+TIP: **mongoRealAuthenticator** can be configured to use different properties for the username, roles an password. Check link:/docs/security/authentication/#mongo-realm-authenticator[mongoRealAuthenticator] for more information.
+
+## Get existing users
+
+++++
+{% include code-header.html type="Request"
+ link="http://restninja.io/share/b6876216ee3fb0999f7c5178e42a7978f6cc3c4c/0"
+%}
+++++
+
+[source,http]
+GET /users HTTP/1.1
+
+++++
+{% include code-header.html type="Response" %}
+++++
+
+[source,json]
+----
+[
+ {
+ "_id": "admin",
+ "roles": [
+ "admin"
+ ],
+ "_etag": {
+ "$oid": "5d2edb155883c050065d6a8a"
+ }
+ }
+]
+----
+
+NOTE: The password is always hidden on GET requests.
+
+NOTE: For security reasons, it not possible to use the `filter` query parameter on the password field; the following request is forbidden and will cause an error: `GET /users?filter={"password":{"$regex":"^a.*"}}`
+
+## Create a user
+
+++++
+{% include code-header.html type="Request"
+ link="http://restninja.io/share/38c1eb85a21213dd39192ccd474789f4abdbd6bc/0"
+%}
+++++
+
+[source,http]
+----
+POST /users HTTP/1.1
+
+{
+ "_id": "foo",
+ "roles": [ "user" ],
+ "password": "secret"
+}
+----
+
+NOTE: The password is automatically encrypted by RESTHeart.
+
+## Update a user
+
+++++
+{% include code-header.html type="Request"
+ link="http://restninja.io/share/3e541e5b4f1ce82ae255b8f6746d49f5faed9778/0"
+%}
+++++
+
+[source,http]
+----
+PATCH /users/foo HTTP/1.1
+
+{
+ "password": "betterSecret"
+}
+----
+
+## Delete a user
+
+++++
+{% include code-header.html type="Request"
+ link="http://restninja.io/share/ae4858bc59f5ac755f03dc8858220e0a470a3779/0"
+%}
+++++
+
+[source,http]
+DELETE /users/foo HTTP/1.1
+
+## Create an ACL document
+
+++++
+{% include code-header.html type="Request"
+ link="http://restninja.io/share/5ee142fbb84071261e56fc7f1904af6430b0495f/0"
+%}
+++++
+
+[source,http]
+----
+POST /acl HTTP/1.1
+
+{
+ "predicate": "path-prefix[/inventory] and method[GET]",
+ "roles": [ "user" ],
+ "priority": 1
+}
+----
+
+TIP: Check link:/docs/security/authorization/#format-of-permissions[Format of permission] for more information on ACL permissions.
+
+TIP: Watch link:https://www.youtube.com/watch?v=QVk0aboHayM&t=1828s[Managing users with practical examples]
diff --git a/docs/v7/setup-with-docker.adoc b/docs/v7/setup-with-docker.adoc
new file mode 100644
index 00000000..3f94d469
--- /dev/null
+++ b/docs/v7/setup-with-docker.adoc
@@ -0,0 +1,258 @@
+---
+title: Setup with Docker
+layout: docs-adoc
+menu: setup
+---
+
+TIP: If Docker isn’t your thing, check out the link:/docs/setup[setup] section for alternative installation methods.
+
+== Run with docker compose
+
+NOTE: This is the quickest way to run RESTHeart.
+
+To run both RESTHeart and MongoDB services you can use `docker compose`. Just copy and paste the following shell command:
+
+[source,bash]
+----
+$ curl https://raw.githubusercontent.com/SoftInstigate/restheart/master/docker-compose.yml --output docker-compose.yml && docker compose up --attach restheart
+----
+
+TIP: Watch link:https://www.youtube.com/watch?v=dzggm7Wp2fU&t=206s[Docker / Docker Compose] video.
+
+== Run RESTHeart with Docker 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.
+
+[.text-muted]
+On OSX and Windows:
+
+[source,bash]
+$ docker run -p 8080:8080 -e RHO="/fileRealmAuthenticator/users[userid='admin']/password->'secret';/http-listener/host->'0.0.0.0'" softinstigate/restheart -s
+
+[.text-muted]
+On Linux
+
+[source,bash]
+$ docker run -p 8080:8080 -e RHO="/fileRealmAuthenticator/users[userid='admin']/password->'secret';/http-listener/host->'0.0.0.0'" softinstigate/restheart -s
+
+NOTE: the `RHO` environment variable sets the password for the user `admin`.
+
+== Run RESTHeart with Docker, MongoDB running on localhost
+
+This runs RESTHeart with Docker connecting to MongoDB running on the localhost.
+
+If MongoDB is not already running, the following command will start a replica set and initiate it (the replica set is not required but enables RESTHeart to support transactions and change streams). Note that the data path is `/tmp/db`.
+
+[source,bash]
+----
+$ mkdir -p /tmp/db && mongod --fork --syslog --replSet=foo -dbpath=/tmp/db && mongosh --quiet --eval 'if (!rs.isMaster().ismaster) rs.initiate();'
+----
+
+Run RESTHeart with:
+
+[.text-muted]
+On OSX and Windows:
+
+[source,bash]
+$ docker run --rm -p "8080:8080" softinstigate/restheart
+
+[.text-muted]
+On Linux
+
+[source,bash]
+$ docker run --rm -p "8080:8080" --add-host host.docker.internal:host-gateway softinstigate/restheart
+
+NOTE: This command relies on the docker support of `host.docker.internal`. If you are using an old docker version or a docker runtime that does not support it, than you need to configure the docker network accordingly (you can refer to the brilliant link:https://stackoverflow.com/questions/24319662/from-inside-of-a-docker-container-how-do-i-connect-to-the-localhost-of-the-mach["From inside of a Docker container, how do I connect to the localhost of the machine?" on StackOverflow]) or use one of the an alternative methods described in the further sections.
+
+## Run RESTHeart and network isolated MongoDB with Docker
+
+This setup involves a RESTHeart container interfacing with a MongoDB container via a private Docker network. This arrangement ensures network isolation, with the RESTHeart API serving as the sole entry point. This configuration allows the two containers to communicate securely and efficiently within their dedicated network environment, while external access is streamlined and controlled through the RESTHeart API
+
+### Setup Procedure
+
+This setup only needs to be completed once. Follow these steps:
+
+1) **Create a Docker Network**
+
+Create a dedicated network for RESTHeart and MongoDB communication:
+
+[source,bash]
+$ docker network create restheart-network
+
+2) **Start MongoDB Container**
+
+Launch a MongoDB container within the created network:
+
+[source,bash]
+$ docker run -d --name mongodb --network restheart-network mongo --replSet=rs0
+
+3) **Initialize MongoDB as a Single Node Replica Set**
+
+Initialize the MongoDB instance to work as a single node replica set:
+
+[source,bash]
+$ docker run -it --network restheart-network --rm mongo mongosh --host mongodb --quiet --eval "rs.initiate()"
+
+4) **Launch RESTHeart Container**
+
+Run the RESTHeart container, linking it to the MongoDB container:
+
+[source,bash]
+$ docker run --name restheart --rm --network restheart-network -p "8080:8080" -e RHO='/http-listener/host->"0.0.0.0";/mclient/connection-string->"mongodb://mongodb"' softinstigate/restheart
+
+5) **Test the Setup**
+
+Execute a test request to verify that RESTHeart is running:
+
+[source,bash]
+----
+$ http -b http://localhost:8080/ping
+# Expected Output: Greetings from RESTHeart!
+----
+
+### Stopping the Containers
+
+To stop both RESTHeart and MongoDB containers, use the following command:
+
+[source,bash]
+$ docker stop restheart mongodb
+
+### Restarting the Containers
+
+The RESTHeart container is stateless and is removed upon stopping (due to the `--rm` option). However, the MongoDB container retains its state and is not removed on stop. To restart, use the following commands:
+
+1) **Start MongoDB Container**
+
+[source,bash]
+$ docker start mongodb
+
+2) **Run RESTHeart Container**
+
+[source,bash]
+$ docker run --name restheart --rm --network restheart-network -p 8080:8080 -e RHO='/http-listener/host->"0.0.0.0";/mclient/connection-string->"mongodb://mongodb"' softinstigate/restheart
+
+### How to connect to MongoDB with mongosh
+
+[source,bash]
+$ docker run -it --network restheart-network --rm mongo mongosh --host mongodb
+
+## For development: run RESTHeart and open MongoDB with Docker
+
+WARNING: This setup is insecure and should be only used for developing or testing purposes.
+
+### Setup Procedure
+
+This setup only needs to be completed once. Follow these steps:
+
+1) **Start MongoDB Container**
+
+Launch a MongoDB container:
+
+[source,bash]
+$ docker run -d --name mongodb -p 27017:27017 mongo --replSet=rs0
+
+2) **Initialize MongoDB as a Single Node Replica Set**
+
+Initialize the MongoDB instance to work as a single node replica set:
+
+[source,bash]
+$ docker exec mongodb mongosh --quiet --eval "rs.initiate()"
+
+3) **Launch RESTHeart Container**
+
+Run the RESTHeart container, linking it to the MongoDB container:
+
+[source,bash]
+$ docker run --name restheart --rm -p "8080:8080" softinstigate/restheart
+
+4) **Test the Setup**
+
+Execute a test request to verify that RESTHeart is running:
+
+[source,bash]
+----
+$ http -b http://localhost:8080/ping
+# Expected Output: Greetings from RESTHeart!
+----
+
+### Stopping the Containers
+
+To stop both RESTHeart and MongoDB containers, use the following command:
+
+[source,bash]
+$ docker stop restheart mongodb
+
+### Restarting the Containers
+
+The RESTHeart container is stateless and is removed upon stopping (due to the `--rm` option). However, the MongoDB container retains its state and is not removed on stop. To restart, use the following commands:
+
+1) **Start MongoDB Container**
+
+[source,bash]
+$ docker start mongodb
+
+2) **Run RESTHeart Container**
+
+[source,bash]
+$ docker run --name restheart --rm -p "8080:8080" softinstigate/restheart
+
+### Run RESTHeart with custom plugin
+
+If the plugin jar file is in the directory `./target`, this command starts RESTHeart with the plugin integrated:
+
+[source,bash]
+$ docker run --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart
+
+NOTE: This command requires RESTHeart version equal or greater than 7.7.
+
+### Run RESTHeart with remote debugging
+
+This runs RESTHeart enabling remote debugging (port 4000).
+
+[source,bash]
+$ docker run --rm -p 8080:8080 -p 4000:4000 --entrypoint "java" softinstigate/restheart -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:4000 -jar restheart.jar
+
+### How to connect to MongoDB with mongosh
+
+[source,bash]
+$ docker exec -it mongodb mongosh
+
+== The RESTHeart Docker tags
+
+RESTHeart Docker images come in four different versions:
+
+- Standard multi-arch (FROM eclipse-temurin:17-jre)
+- Graalvm (FROM softinstigate/graalvm:latest)
+- distroless (FROM gcr.io/distroless/java17-debian11:latest)
+- native (FROM debian:bookworm-slim)
+
+These are example tags:
+
+[cols="1,1,3"]
+|===
+|**Tag**|**Example**|**Description**
+|`
+
+* [From the Team](#from-the-team)
+* [From the Community](#from-the-community)
+
+
+
+
+{% include docs-head.html %}
+
+## From the Team
+
+* [**Easily Create a Star Wars GraphQL API with RESTHeart**](https://medium.com/softinstigate-team/easily-create-a-star-wars-graphql-api-with-restheart-5746e337da7c): How to create a GraphQL API using RESTHeart, inspired by the classic Star Wars characters and episodes
+
+* [**RESTHeart with FerretDB: a tutorial**](https://medium.com/p/1b43432ed2e0): This tutorial introduces FerretDB, an open-source alternative to MongoDB built on PostgreSQL. Utilizing FerretDB in conjunction with RESTHeart, a powerful API server for MongoDB, this guide demonstrates how to set up the FerretDB stack using Docker and interact with it using RESTHeart’s REST API.
+
+* [**Json Web Token Authentication for Angular App with Auth0 and RESTHeart**](https://medium.com/softinstigate-team/json-web-token-authentication-for-angular-app-with-auht0-and-restheart-214e3ce8a1cb?source=your_stories_page--------------------------- ) : How to create an Angular application that uses the **Auth0** service to manage user authentication with RESTHeart.
+
+* [**How to create a Web API for AWS DocumentDB**](https://medium.com/softinstigate-team/how-to-create-a-web-api-for-aws-documentdb-using-restheart-987921df3ced) : The compatibility of **DocumentDB** with MongoDB makes RESTHeart an extremely effective tool for creating a RESTful API on top of the **Amazon** database. So as we would configure RESTHeart to point to a MongoDB database, we can configure it to access a DocumentDB database.
+
+* [**JSON Schema — Form Validation, with Angular & RESTHeart**](https://medium.com/softinstigate-team/json-schema-validazione-e-salvataggio-di-un-form-con-angular-restheart-ec13cbdb5872): The **JSON Schema** makes the creation and the validation of a Form activities relatively simple and fast. The functionality of RESTHeart allows us to have an efficient server-side validation system controlled by the JSON Schema, while the **Angular** Angular6-json-schema-form library transform the JSON Schema in a Form very easily.
+
+* [**RESTful API memo: PUT and POST verbs**](https://medium.com/softinstigate-team/restful-api-memo-put-and-post-verbs-1351ffabc359): **PUT** and **POST** verbs sometimes can be a source of confusion. Let’s briefly recap how they are supposed to work, by revisiting the Hypertext Transfer Protocol.
+
+* [**RESTHeart, the REST API Server for MongoDB**](https://medium.com/softinstigate-team/restheart-the-rest-api-server-for-mongodb-4d84ca3376bc): **RESTHeart** leverages **MongoDB**’s document-oriented nature, creating an automatic mapping between MongoDB’s internal storage of data and a graph of externally accessible HTTP resources, implementing a model of interaction compliant with an HATEOAS (Hypermedia as the Engine of Application State) representation, where the state of a client process is entirely driven by HTTP verbs like GET, POST, PUT, PATCH, DELETE, etc.
+
+* [**RESTHeart Performances**](/docs/performances): **RESTHeart** has been designed and developed with lightness and performances as fundamental parameters. On this regards, also thanks to its caching capabilities, RESTHeart often overcomes the results that can be achieved accessing MongoDB directly via its Java driver. This article includes the performance test results gathered by the SoftInstigate’s development team.
+
+* [**RESTHeart and NGINX with SSL**](https://github.com/SoftInstigate/nginx-restheart): This repository shows an example of NGINX as a SSL frontend for RESTHeart 4.0. It uses Docker images to setup a complete stack made with NGINX, RESTHeart and MongoDB. NGINX acts as a HTTPS reverse proxy for RESTHeart and it uses a self-signed certificate for the SSL connection.
+
+## From the Community
+
+* [**Building Instant RESTFul API's with MongoDB and RESTHeart**](https://www.compose.com/articles/building-instant-restful-apis-with-mongodb-and-restheart/):When you need to turn your Mongo database into a RESTFul API, RESTHeart can get you up-and-running quickly. In this article, we'll explore using RESTHeart to expose a RESTFUL API directly from a Mongo database on Compose.
+
+* [**Building Secure Instant API's with RESTHeart and Compose**](https://www.compose.com/articles/building-secure-instant-apis-with-restheart-and-compose/):Following up on our previous article on using RESTHeart to expose a RESTFUL API directly from a Mongo database on Compose, in this article, we'll show you how to secure your RESTHeart API by adding authentication and role-base access control, as well as enabling SSL encryption.
+
+* [**Launching RESTHeart into Production**](https://www.compose.com/articles/launching-restheart-into-production/):Now that we've shown you how to build instant RESTFul API's with RESTHeart and secure your RESTHeart installation, there's just one more step to building instant, secure API's from Compose MongoDB: taking RESTHeart into production.
diff --git a/docs/upgrade-to-v7.adoc b/docs/v7/upgrade-to-v7.adoc
similarity index 100%
rename from docs/upgrade-to-v7.adoc
rename to docs/v7/upgrade-to-v7.adoc
diff --git a/docs/v7/video-tutorials.md b/docs/v7/video-tutorials.md
new file mode 100644
index 00000000..e2cef182
--- /dev/null
+++ b/docs/v7/video-tutorials.md
@@ -0,0 +1,97 @@
+---
+title: Video tutorials
+layout: docs
+menu: overview
+---
+
+
+
+- [RESTHeart Overview](#restheart-overview)
+- [Setup and Configuration](#setup-and-configuration)
+- [Security](#security)
+- [Plugin development](#plugin-development)
+
+
+
+
+{% include docs-head.html %}
+
+## Andrea's talk at Docker Community All-Hands 2022
+
+The talk provides an introduction on RESTHeart and shows the
+different options to run it with Docker, including running it and
+connecting to MongoDB running on the host, running a complete containerized
+stack with docker compose, and using the RESTHeart native image
+for instant startup with minimal memory footprint.
+
+
+
+## Andrea and Maurizio at MongoDB Live 2020
+
+In this talk we discuss how we designed and implemented MongoDB sessions and multi-document transactions within RESTHeart, exposing them via a REST API. After a quick introduction to the main concepts, we show a demo of a simple Angular application applying transactions in a real case.
+
+
+
+
+
+## RESTHeart Overview
+
+
+
+### Table of Contents
+
+- [Introduction](https://www.youtube.com/watch?v=9KroH-RvjS0&t=0s)
+- [Download and run](https://www.youtube.com/watch?v=9KroH-RvjS0&t=67s)
+- [How to run MongoDB with Docker](https://www.youtube.com/watch?v=9KroH-RvjS0&t=187s)
+- [How to run RESTHeart from command line](https://www.youtube.com/watch?v=9KroH-RvjS0&t=212s)
+- [Practical testing with Rest Ninja](https://www.youtube.com/watch?v=9KroH-RvjS0&t=291s)
+- [How to create RESTHeart database](https://www.youtube.com/watch?v=9KroH-RvjS0&t=321s)
+- [How to create a test collection on MongoDB](https://www.youtube.com/watch?v=9KroH-RvjS0&t=410s)
+- [How to populate a collection](https://www.youtube.com/watch?v=9KroH-RvjS0&t=495s)
+- [How to filter data](https://www.youtube.com/watch?v=9KroH-RvjS0&t=610s)
+
+## Setup and Configuration
+
+
+
+### Table of Contents
+
+- [Introduction](https://www.youtube.com/watch?v=dzggm7Wp2fU&t=0s)
+- [Java binaries](https://www.youtube.com/watch?v=dzggm7Wp2fU&t=57s)
+- [Docker / Docker Compose](https://www.youtube.com/watch?v=dzggm7Wp2fU&t=206s)
+- [Compile source code from scratch](https://www.youtube.com/watch?v=dzggm7Wp2fU&t=605s)
+- [Configuration](https://www.youtube.com/watch?v=dzggm7Wp2fU&t=820s)
+- [Logging](https://www.youtube.com/watch?v=dzggm7Wp2fU&t=1152s)
+
+## Security
+
+
+
+### Table of Contents
+
+- [Introduction](https://www.youtube.com/watch?v=QVk0aboHayM&t=0s)
+- [About authorization and authentication concepts](https://www.youtube.com/watch?v=QVk0aboHayM&t=36s)
+- [Authentication and Authorization in RESTHeart](https://www.youtube.com/watch?v=QVk0aboHayM&t=77s)
+- [Understanding RESTHeart security](https://www.youtube.com/watch?v=QVk0aboHayM&t=123s)
+- [Authentication mechanisms](https://www.youtube.com/watch?v=QVk0aboHayM&t=342s)
+- [Authentication practical examples](https://www.youtube.com/watch?v=QVk0aboHayM&t=658s)
+- [Authenticators in RESTHeart](https://www.youtube.com/watch?v=QVk0aboHayM&t=1211s)
+- [Authorization via file and MongoDB](https://www.youtube.com/watch?v=QVk0aboHayM&t=1553s)
+- [Managing users with paractical examples](https://www.youtube.com/watch?v=QVk0aboHayM&t=1828s)
+- [An application example (blog](https://www.youtube.com/watch?v=QVk0aboHayM&t=2262s)
+
+## Plugin development
+
+
diff --git a/index.md b/index.md
index 12fd6a15..1ae210cf 100644
--- a/index.md
+++ b/index.md
@@ -8,9 +8,8 @@ stars-bounce: true
- Open source low-code API development framework
-