[[_mongo]]

== Mongo DB Setup

You are not stuck with using a RDBMS for persisting data.  {{book.project.name}}
provides a http://www.mongodb.com[MongoDB] based model implementation.
To configure {{book.project.name}} to use Mongo, you need to edit the `standalone.xml`, 
`standalone-ha.xml`, or `domain.xml` file in your distribution.  The location of this file 
depends on your <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>. 

Open the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file.  Look for the following XML snippets and replace all the _jpa_ providers with _mongo_ .   This is the area you will be modifying
to use Mongo.

[source,xml]
----
<spi name="eventsStore">
    <default-provider>jpa</default-provider>
    <provider name="jpa" enabled="true">
        <properties>
            <property name="exclude-events" value="[&quot;REFRESH_TOKEN&quot;]"/>
        </properties>
    </provider>
</spi>
<spi name="realm">
    <default-provider>jpa</default-provider>
</spi>
<spi name="user">
    <default-provider>jpa</default-provider>
</spi>
<spi name="userFederatedStorage">
    <default-provider>jpa</default-provider>
    <provider name="jpa" enabled="true"/>
</spi>
<spi name="userSessionPersister">
    <default-provider>jpa</default-provider>
</spi>
<spi name="authorizationPersister">
    <default-provider>jpa</default-provider>
</spi>

----

Change that XML snippet to use Mongo:

[source,xml]
----
<spi name="eventsStore">
    <default-provider>mongo</default-provider>
    <provider name="mongo" enabled="true">
        <properties>
            <property name="exclude-events" value="[&quot;REFRESH_TOKEN&quot;]"/>
        </properties>
    </provider>
</spi>
<spi name="realm">
    <default-provider>mongo</default-provider>
</spi>
<spi name="user">
    <default-provider>mongo</default-provider>
</spi>
<spi name="userFederatedStorage">
    <default-provider>mongo</default-provider>-->
    <provider name="mongo" enabled="true"/>
</spi>
<spi name="userSessionPersister">
    <default-provider>mongo</default-provider>
</spi>
<spi name="authorizationPersister">
    <default-provider>mongo</default-provider>
</spi>
----
After that, add the snippet like this where you can configure details about your Mongo database:

[source,xml]
----
<spi name="connectionsMongo">
    <provider name="default" enabled="true">
        <properties>
            <property name="host" value="127.0.0.1"/>
            <property name="port" value="27017"/>
            <property name="db" value="keycloak"/>
            <property name="connectionsPerHost" value="100"/>
            <property name="migrationStrategy" value="update"/>
        </properties>
    </provider>
</spi>
----
All configuration options are optional.
Default values for host and port are localhost and 27017.
Default name of database is `keycloak` . You can also specify properties `user` and `password` if you want authenticate against your MongoDB.
If user and password are not specified, {{book.project.name}} will connect unauthenticated to your MongoDB.

Finally there is set of optional configuration options, which can be used to specify connection-pooling capabilities of Mongo client.
Supported int options are: `connectionsPerHost`, `threadsAllowedToBlockForConnectionMultiplier`, `maxWaitTime`, `connectTimeout` `socketTimeout`.
Supported boolean options are: `socketKeepAlive`, `autoConnectRetry`.
Supported long option is `maxAutoConnectRetryTime`.
See http://api.mongodb.org/java/2.11.4/com/mongodb/MongoClientOptions.html[Mongo documentation]                for details about those options and their default values.

Alternatively, you can configure MongoDB using a MongoDB http://docs.mongodb.org/manual/reference/connection-string/[connection URI].
In this case, you define all information concerning the connection and authentication within the URI, as described in the MongoDB documentation.
Please note that the database specified within the URI is only used for authentication.
To change the database used by {{book.project.name}} you have to set `db` property as before.
Therefore, a configuration like the following

[source,xml]
----
<spi name="connectionsMongo">
    <provider name="default" enabled="true">
        <properties>
            <property name="uri" value="mongodb://user:password@127.0.0.1/authentication"/>
            <property name="db" value="keycloak"/>
        </properties>
    </provider>
</spi>
----
will authenticate the user against the authentication database, but store all {{book.project.name}} related data in the keycloak database.

Finally, there's some ongoing incomplete refactoring work that needs to be disabled as there isn't a Mongo implementation for it.  Replace the following XML

[source,xml]
----
<spi name="userFederatedStorage">
    <default-provider>jpa</default-provider>
</spi>
----

with

[source,xml]
----
<spi name="userFederatedStorage">
    <provider name="jpa" enabled="false"/>
</spi>
----



=== MongoDB Replica Sets

In order to use a mongo replica set for {{book.project.name}}, one has to use URI based configuration, which supports the definition of replica sets out of the box: `mongodb://host1:27017,host2:27017,host3:27017/`.