Merge pull request #1522 from mposolda/master

Clustering docs and distribution fixes

distribution/demo-dist/src/main/xslt/standalone.xsl

@@ -8,6 +8,7 @@
                 exclude-result-prefixes="xalan j ds k sec">
 
     <xsl:param name="config"/>
+    <xsl:variable name="inf" select="'urn:jboss:domain:infinispan:'"/>
 
     <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes" xalan:indent-amount="4" standalone="no"/>
     <xsl:strip-space elements="*"/>
@@ -61,6 +62,18 @@
         </xsl:copy>
     </xsl:template>
 
+    <xsl:template match="//*[local-name()='subsystem' and starts-with(namespace-uri(), $inf)]">
+        <xsl:copy>
+            <cache-container name="keycloak" jndi-name="infinispan/Keycloak">
+                <local-cache name="realms"/>
+                <local-cache name="users"/>
+                <local-cache name="sessions"/>
+                <local-cache name="loginFailures"/>
+            </cache-container>
+            <xsl:apply-templates select="node()|@*"/>
+        </xsl:copy>
+    </xsl:template>
+
     <xsl:template match="@*|node()">
         <xsl:copy>
             <xsl:apply-templates select="@*|node()" />

docbook/reference/en/en-US/modules/clustering.xml

@@ -49,15 +49,20 @@
         </para>
         <para>
             For realm and users Keycloak uses a invalidation cache. An invalidation cache doesn't share any data, but simply
-            removes stale data from remote caches. This reduces network traffic, as well as preventing sensitive data (such as
+            removes stale data from remote caches and makes sure all nodes re-load data from the database when it is changed. This reduces network traffic, as well as preventing sensitive data (such as
             realm keys and password hashes) from being sent between the nodes.
         </para>
         <para>
             User sessions and login failures supports either distributed caches or fully replicated caches. We recommend using a distributed
-            cache.
+            cache. A distributed
+            cache splits user sessions into segments where each node holds one or more segment. It is possible
+            to replicate each segment to multiple nodes, but this is not strictly necessary since the failure of a node
+            will only result in users having to log in again. If you need to prevent node failures from requiring users to
+            log in again, set the <literal>owners</literal> attribute to 2 or more for the <literal>sessions</literal> cache
+            of <literal>infinispan/Keycloak</literal> container as described below.
         </para>
         <para>
-            To enable clustering in Keycloak open <literal>standalone/configuration/keycloak-server.json</literal> and add:
+            The infinispan container is set by default in <literal>standalone/configuration/keycloak-server.json</literal>:
 <programlisting>
 "connectionsInfinispan": {
     "default" : {
@@ -66,49 +71,13 @@
 }
 </programlisting>
         </para>
-    </section>
+        <para>As you can see in this file, the realmCache, userCache and userSession providers are configured to use infinispan by default, which applies for both cluster and non-cluster environment.</para>
-
-    <section>
-        <title>Enable realm and user cache invalidation</title>
         <para>
-            To reduce number of requests to the database Keycloak caches realm and user data. In cluster mode
+            For non-cluster configuration (server executed with <literal>standalone.xml</literal> ) is the infinispan container <literal>infinispan/Keycloak</literal> just uses local infinispan caches for realms, users and userSessions.
-            Keycloak uses an Infinispan invalidation cache to make sure all nodes re-load data from the database
-            when it is changed. Using an invalidation cache instead of a replicated cache reduces the network traffic
-            generated by the cluster, but more importantly prevents sensitive data from being sent.
         </para>
         <para>
-            To enable realm and user cache invalidation open <literal>keycloak-server.json</literal> and change
+            For cluster configuration, you can edit the configuration of <literal>infinispan/Keycloak</literal> container in <literal>standalone/configuration/standalone-ha.xml</literal> (or <literal>standalone-keycloak-ha.xml</literal>
-            the <literal>realmCache</literal> and <literal>userCache</literal> providers to <literal>infinispan</literal>:
+            if you are using overlay or demo distribution) .
-<programlisting>
-"realmCache": {
-    "provider": "infinispan"
-},
-
-"userCache": {
-    "provider": "infinispan"
-}
-</programlisting>
-        </para>
-    </section>
-
-    <section>
-        <title>Enable distributed user sessions</title>
-        <para>
-            To help distribute the load of user sessions Keycloak uses an Infinispan distributed cache. A distributed
-            cache splits user sessions into segments where each node holds one or more segment. It is possible
-            to replicate each segment to multiple nodes, but this is not strictly necessary since the failure of a node
-            will only result in users having to log in again. If you need to prevent node failures from requiring users to
-            log in again, set the <literal>owners</literal> attribute to 2 or more for the <literal>sessions</literal> cache
-             (see <link linkend='cluster-configure-infinispan'>Configure Infinispan</link>).
-        </para>
-        <para>
-            To enable the Infinispan user sessions provider open <literal>keycloak-server.json</literal> and change the
-            userSessions provider to <literal>infinispan</literal>:
-<programlisting>
-"userSessions": {
-    "provider": "infinispan"
-}
-</programlisting>
         </para>
     </section>
 
@@ -117,6 +86,8 @@
         <para>
             To start the server in HA mode, start it with:
             <programlisting># bin/standalone --server-config=standalone-ha.xml</programlisting>
+            or if you are using overlay or demo distribution with:
+            <programlisting># bin/standalone --server-config=standalone-keycloak-ha.xml</programlisting>
         </para>
         <para>
             Alternatively you can copy <literal>standalone/config/standalone-ha.xml</literal> to <literal>standalone/config/standalone.xml</literal>