more

SUMMARY.adoc

@@ -17,6 +17,11 @@
  .. link:topics/operating-mode/standalone.adoc[Standalone Mode]
  .. link:topics/operating-mode/standalone-ha.adoc[Standalone Clustered Mode]
  .. link:topics/operating-mode/domain.adoc[Domain Clustered Mode]
+ . link:topics/management.adoc[Managing Config at Runtime]
+ . link:topics/database.adoc[Relational Database Setup]
+ {% if book.community %}
+ . link:topics/mongo.adoc[Mongo DB Setup]
+ {% endif %}
  . link:topics/cache.adoc[Server Cache]
  . link:topics/clustering.adoc[Clustering]
  . link:topics/management.adoc[Runtime Management]

book.json

@@ -18,6 +18,10 @@
       "admindoc": {
         "name": "JBoss EAP Administration and Configuration Guide",
         "link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/"
+      },
+      "datasource": {
+        "name": "JBoss EAP Administration and Configuration Guide",
+        "link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/chap-Datasource_Management.html"
       }
     },
     "caching": {

topics/database.adoc

@@ -0,0 +1,62 @@
+[[_database]]
+
+== Relational Database Setup
+
+Out of the box, {{book.project.name}} persists its data using the Hibernate JPA set of APIs on top of an embedded Java based relational database.
+The built-in database is not viable in high load and high concurrency situations.  It cannot be used in a cluster either.  It is
+highly recommended that you replace the default embedded database with a more scalable and reliable solution like PostgreSQL or MySql.  This
+chapter will show you how to configure {{book.project.name}} to use an external relational database.  It will also discuss
+how you can configure the Hibernate JPA persistence abstraction that sits on top of your RDBMS.
+
+NOTE:  Datasource configuration is covered much more thoroughly within the link:{{book.appserver.database.link}}[the datasource configuration chapter]
+       of the {{book.appserver.admindoc.name}}.
+
+=== RDBMS Checklist
+
+These are the steps you will need to perform to get an RDBMS configured for {{book.project.name}}.
+
+. Locate and download a JDBC driver for your database
+. Package the driver JAR into a module and install this module into the server
+. Declare the JDBC driver in the configuration profile of the server
+. Modify the datasource configuration to use your database's JDBC driver
+. Modify the datasource configuration to define the connection parameters to your database
+
+This chapter will use PostgresSQL for all its examples.  Other databases follow the same steps for installation.
+
+=== Package the JDBC Driver
+
+Find and download the JDBC driver JAR for your RDBMS.  Before you can use this driver, you must package it up into a module.
+Modules define JARs that are loaded into the {{book.project.name}} classpath and the dependencies those JARs have on
+other modules.  They are pretty simple to set up.
+
+Within the _.../modules/system/layers/keycloak/_ directory of your
+{{book.project.name}} distribution, you need to create a directory structure to hold your module definition.  The convention is use the Java package name
+of the JDBC driver for the name of the directory structure.  For PostgreSQL, create the directory _org/postgresql/main_.  Copy your database
+driver JAR into this directory and also create an empty _module.xml_ file.
+
+.Module Directory
+image:../../{{book.images}}/db-module.png[]
+
+After you have done this, open up the _module.xml_ file and create the following XML
+
+.Module XML
+[source,xml]
+----
+<?xml version="1.0" ?>
+<module xmlns="urn:jboss:module:1.3" name="org.postgresql">
+
+    <resources>
+        <resource-root path="postgresql-9.4.1208.jar"/>
+    </resources>
+
+    <dependencies>
+        <module name="javax.api"/>
+        <module name="javax.transaction.api"/>
+    </dependencies>
+</module>
+----
+
+The module name should match the directory structure of your module.  _org/postgresql_ maps to +org.postgresql+.  The
++resource-root path+ attribute should specify the JAR filename.  The rest are just the normal dependencies that
+any JDBC driver JAR would have.
+

topics/manage.adoc

@@ -0,0 +1,53 @@
+[[_app_server_cli]]
+
+== Manage Configuration at Runtime
+
+In the upcoming chapters, you'll often be provided two options for applying application server configuration changes to your deployment.  You'll be
+shown how to edit the _standalone.xml_ or _domain.xml_ directly.  This must be done when the server (or servers) are offline.
+Additionally, you may be shown how to apply config changes on a running server using the app server's command line interface ({{books.appserver.name}} CLI).  This chapter discusses
+how you will do this.
+
+=== Start the {{books.appserver.name}} CLI
+
+To start the {{books.appserver.name}} CLI, you need to run the +jboss-cli+ script.
+
+.Linux/Unix
+[source]
+----
+$ .../bin/jboss-cli.sh
+----
+
+.Windows
+[source]
+----
+> ...\bin\jboss-cli.bat
+----
+
+This will bring you to a prompt like this:
+
+.Prompt
+[source]
+----
+[disconnected /]
+----
+
+There's a few commands you can execute without a running standalone server or domain controller, but usually you will
+have to have those services booted up before you can execute CLI commands.  To connect to a running server simply
+execute the +connect+ command.
+
+.connect
+[source]
+----
+[disconnected /] connect
+connect
+[domain@localhost:9990 /]
+----
+
+You may be thinking to yourself, "I didn't enter in any username or password!".  If you run +jboss-cli+ on the same machine
+as your running standalone server or domain controller and your account has appropriate file permissions, you do not have
+to setup or enter in a admin username and password.  See the link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}]
+for more details on how to make things more secure if you are uncomfortable with that setup.
+
+
+
+

topics/mongo.adoc

@@ -0,0 +1,95 @@
+[[_mongo]]
+
+== Mongo DB Setup
+
+You are not stuck with using a RDBMS for persisting data.  {{book.project.name}}
+provides http://www.mongodb.com[MongoDB] based model implementation.
+To configure {{book.project.name}} to use Mongo, you need to edit the _keycloak-server.json_ file.  If you are running
+in standalone mode, this file is in the _.../standalone/configuration_ directory.  If you are running in domain mode
+this file will live in the _.../domain/servers/{server name}/configuration_ directory.
+
+[source,json]
+----
+
+"eventsStore": {
+    "provider": "jpa",
+    "jpa": {
+        "exclude-events": [ "REFRESH_TOKEN" ]
+    }
+},
+
+"realm": {
+    "provider": "jpa"
+},
+
+"user": {
+    "provider": "${keycloak.user.provider:jpa}"
+},
+----
+to:
+
+[source,json]
+----
+
+"eventsStore": {
+    "provider": "mongo",
+    "mongo": {
+        "exclude-events": [ "REFRESH_TOKEN" ]
+    }
+},
+
+"realm": {
+    "provider": "mongo"
+},
+
+"user": {
+    "provider": "mongo"
+},
+----
+And at the end of the file add the snippet like this where you can configure details about your Mongo database:
+
+[source,json]
+----
+
+"connectionsMongo": {
+    "default": {
+        "host": "127.0.0.1",
+        "port": "27017",
+        "db": "keycloak",
+        "connectionsPerHost": 100,
+        "databaseSchema": "update"
+    }
+}
+----
+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, Keycloak 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 keycloak you have to set `db` property as before.
+Therefore, a configuration like the following
+
+[source]
+----
+
+"connectionsMongo": {
+    "default": {
+        "uri": "mongodb://user:password@127.0.0.1/authentication",
+        "db": "keycloak"
+    }
+}
+----
+will authenticate the user against the authentication database, but store all keycloak related data in the keycloak database.
+
+==== MongoDB Replica Sets
+
+In order to use a mongo replica set for Keycloak, 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/`.

topics/operating-mode/domain.adoc

@@ -225,7 +225,7 @@ $ add-user.sh
  To represent the user add the following to the server-identities definition <secret value="bWdtdDEyMyE=" />
 ----
 
-Now cut and paste the secret value into the .../domain/configuration/host-slave.xml_ file:
+Now cut and paste the secret value into the _.../domain/configuration/host-slave.xml_ file:
 
 [source,xml]
 ----