<?xml version="1.0" encoding="UTF-8"?>
<!-- This document was created with Syntext Serna Free. -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="JCR.ClusterConfig">
  <title>Configuring JBoss AS with eXo JCR in cluster</title>

  <section id="JCR.ClusterConfig.Launching_Cluster">
    <title>Launching Cluster</title>

    <section id="JCR.ClusterConfig.Launching_Cluster.Deploying_eXo_JCR_To_JBoss_As">
      <title>Deploying eXo JCR to JBoss As</title>

      <para>To deploy eXo JCR to JBoss, do the following steps:</para>

      <orderedlist>
        <listitem>
          <para>Download the latest version of eXo JCR .ear file
          distribution.</para>
        </listitem>

        <listitem>
          <para>Copy &lt;jcr.ear&gt; into
          &lt;%jboss_home%/server/default/deploy&gt;</para>
        </listitem>

        <listitem>
          <para>Put exo-configuration.xml to the root
          &lt;%jboss_home%/exo-configuration.xml&gt;</para>
        </listitem>

        <listitem>
          <para>Configure JAAS by inserting XML fragment shown below into
          &lt;%jboss_home%/server/default/conf/login-config.xml&gt;</para>

          <programlisting language="xml">&lt;application-policy name="exo-domain"&gt;
   &lt;authentication&gt;
      &lt;login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required"&gt;&lt;/login-module&gt;
   &lt;/authentication&gt;
&lt;/application-policy&gt;</programlisting>
        </listitem>

        <listitem>
          <para>Ensure that you use JBossTS <link
          linkend="Kernel.TransactionService">Transaction Service</link> and
          JBossCache <link linkend="JCR.JBossTransactionsService">Transaction
          Manager</link>. Your exo-configuration.xml must contain such
          parts:</para>

          <programlisting language="xml">&lt;component&gt;
   &lt;key&gt;org.jboss.cache.transaction.TransactionManagerLookup&lt;/key&gt;
   &lt;type&gt;org.jboss.cache.GenericTransactionManagerLookup&lt;/type&gt;^
&lt;/component&gt;

&lt;component&gt;
   &lt;key&gt;org.exoplatform.services.transaction.TransactionService&lt;/key&gt;
   &lt;type&gt;org.exoplatform.services.transaction.jbosscache.JBossTransactionsService&lt;/type&gt;
   &lt;init-params&gt;
      &lt;value-param&gt;
         &lt;name&gt;timeout&lt;/name&gt;
         &lt;value&gt;300&lt;/value&gt;
      &lt;/value-param&gt;
   &lt;/init-params&gt;
&lt;/component&gt;</programlisting>
        </listitem>

        <listitem>
          <para>Start server:</para>

          <itemizedlist>
            <listitem>
              <para>bin/run.sh for Unix</para>
            </listitem>

            <listitem>
              <para>bin/run.bat for Windows</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>Try accessing <uri>http://localhostu:8080/browser</uri> with
          root/exo as login/password if you have done everything right, you'll
          get access to repository browser.</para>
        </listitem>
      </orderedlist>
    </section>

    <section id="JCR.ClusterConfig.JCRExternalConfig">
      <title>Configuring JCR to use external configuration</title>

      <itemizedlist>
        <listitem>
          <para>To manually configure repository, create a new configuration
          file (e.g., exo-jcr-configuration.xml). For details, see <link
          linkend="JCR.eXoJCRconfiguration">JCR Configuration</link>. Your
          configuration must look like:</para>

          <programlisting language="xml">&lt;repository-service default-repository="repository1"&gt;
   &lt;repositories&gt;
      &lt;repository name="repository1" system-workspace="ws1" default-workspace="ws1"&gt;
         &lt;security-domain&gt;exo-domain&lt;/security-domain&gt;
         &lt;access-control&gt;optional&lt;/access-control&gt;
         &lt;authentication-policy&gt;org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator&lt;/authentication-policy&gt;
         &lt;workspaces&gt;
            &lt;workspace name="ws1"&gt;
               &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"&gt;
                  &lt;properties&gt;
                     &lt;property name="source-name" value="jdbcjcr" /&gt;
                     &lt;property name="dialect" value="oracle" /&gt;
                     &lt;property name="multi-db" value="false" /&gt;
                     &lt;property name="update-storage" value="false" /&gt;
                     &lt;property name="max-buffer-size" value="200k" /&gt;
                     &lt;property name="swap-directory" value="../temp/swap/production" /&gt;
                  &lt;/properties&gt;
                  &lt;value-storages&gt;
                     see "<link linkend="conf_value_storage">Value storage configuration</link>" part.
                  &lt;/value-storages&gt;
               &lt;/container&gt;
               &lt;initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"&gt;
                  &lt;properties&gt;
                     &lt;property name="root-nodetype" value="nt:unstructured" /&gt;
                  &lt;/properties&gt;
               &lt;/initializer&gt;
               &lt;cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"&gt;
                     see  "<link linkend="conf_cache">Cache configuration</link>" part.
               &lt;/cache&gt;
               &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt;
                  see  "<link linkend="conf_indexer">Indexer configuration</link>" part.
               &lt;/query-handler&gt;
               &lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt;
                  see  "<link linkend="conf_lock_manager">Lock Manager configuration</link>" part.
               &lt;/lock-manager&gt;
            &lt;/workspace&gt;
            &lt;workspace name="ws2"&gt;
                        ...
            &lt;/workspace&gt;
            &lt;workspace name="wsN"&gt;
                        ...
            &lt;/workspace&gt;
         &lt;/workspaces&gt;
      &lt;/repository&gt;
   &lt;/repositories&gt;
&lt;/repository-service&gt; </programlisting>
        </listitem>

        <listitem>
          <para>Then, update RepositoryServiceConfiguration configuration in
          exo-configuration.xml to use this file:</para>

          <programlisting language="xml">&lt;component&gt;
   &lt;key&gt;org.exoplatform.services.jcr.config.RepositoryServiceConfiguration&lt;/key&gt;
   &lt;type&gt;org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl&lt;/type&gt;
   &lt;init-params&gt;
      &lt;value-param&gt;
         &lt;name&gt;conf-path&lt;/name&gt;
         &lt;description&gt;JCR configuration file&lt;/description&gt;
         &lt;value&gt;exo-jcr-configuration.xml&lt;/value&gt;
      &lt;/value-param&gt;
   &lt;/init-params&gt;
&lt;/component&gt;</programlisting>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section id="JCR.ClusterConfig.Requirements">
    <title>Requirements</title>

    <section id="JCR.ClusterConfig.Requirements.Environment_Requirements">
      <title>Environment requirements</title>

      <itemizedlist>
        <listitem>
          <para>Every node of cluster MUST have the same mounted Network File
          System with the read and write permissions on it.</para>

          <para>"/mnt/tornado" - path to the mounted Network File System (all
          cluster nodes must use the same NFS).</para>
        </listitem>

        <listitem>
          <para>Every node of cluster MUST use the same database.</para>
        </listitem>

        <listitem>
          <para>The same Clusters on different nodes MUST have the same names
          (e.g., if Indexer cluster in workspace production on the first node
          has the name "production_indexer_cluster", then indexer clusters in
          workspace production on all other nodes MUST have the same name
          "production_indexer_cluster" ).</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="JCR.ClusterConfig.Requirements.Configuration_Requirements">
      <title>Configuration requirements</title>

      <para>Configuration of every workspace in repository must contains of
      such parts:</para>

      <itemizedlist>
        <listitem id="conf_value_storage">
          <para>Value Storage configuration:</para>

          <programlisting language="xml">&lt;value-storages&gt;
   &lt;value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt;
      &lt;properties&gt;
         &lt;property name="path" value="/mnt/tornado/temp/values/production" /&gt;    &lt;!--path within NFS where ValueStorage will hold it's data--&gt;
      &lt;/properties&gt;
      &lt;filters&gt;
         &lt;filter property-type="Binary" /&gt;
      &lt;/filters&gt;
   &lt;/value-storage&gt;
&lt;/value-storages&gt;</programlisting>
        </listitem>

        <listitem id="conf_cache">
          <para>Cache configuration:</para>

          <programlisting language="xml">&lt;cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"&gt;
   &lt;properties&gt;
      &lt;property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-data.xml" /&gt;     &lt;!--    path to JBoss Cache configuration for data storage --&gt;
      &lt;property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /&gt;                     &lt;!--    path to JGroups configuration --&gt;
      &lt;property name="jbosscache-cluster-name" value="JCR_Cluster_cache" /&gt;                              &lt;!--    JBoss Cache data storage cluster name --&gt;
      &lt;property name="jgroups-multiplexer-stack" value="false" /&gt;
      &lt;property name="jbosscache-shareable" value="true" /&gt;
   &lt;/properties&gt;
&lt;/cache&gt; </programlisting>
        </listitem>

        <listitem id="conf_indexer">
          <para>Indexer configuration:</para>

          <programlisting language="xml">&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt;
   &lt;properties&gt;
      &lt;property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /&gt;
      &lt;property name="index-dir" value="/mnt/tornado/temp/jcrlucenedb/production" /&gt;                       &lt;!--    path within NFS where ValueStorage will hold it's data --&gt;
      &lt;property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-indexer.xml" /&gt;    &lt;!--    path to JBoss Cache configuration for indexer --&gt;
      &lt;property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /&gt;                       &lt;!--    path to JGroups configuration --&gt;
      &lt;property name="jbosscache-cluster-name" value="JCR_Cluster_indexer" /&gt;                              &lt;!--    JBoss Cache indexer cluster name --&gt;
      &lt;property name="jgroups-multiplexer-stack" value="false" /&gt;
      &lt;property name="jbosscache-shareable" value="true" /&gt;
   &lt;/properties&gt;
&lt;/query-handler&gt; </programlisting>
        </listitem>

        <listitem id="conf_lock_manager">
          <para>Lock Manager configuration:</para>

          <programlisting language="xml">&lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt;
   &lt;properties&gt;
      &lt;property name="time-out" value="15m" /&gt;
      &lt;property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-lock.xml" /&gt;       &lt;!--    path to JBoss Cache configuration for lock manager --&gt;
      &lt;property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /&gt;                       &lt;!--    path to JGroups configuration --&gt;
      &lt;property name="jbosscache-cluster-name" value="JCR_Cluster_locks" /&gt;                                &lt;!--    JBoss Cache locks cluster name --&gt;                    
      &lt;property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks"/&gt;                              &lt;!--    the name of the DB table where lock's data will be stored --&gt;
      &lt;property name="jbosscache-cl-cache.jdbc.table.create" value="true"/&gt;
      &lt;property name="jbosscache-cl-cache.jdbc.table.drop" value="false"/&gt;
      &lt;property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_pk"/&gt;
      &lt;property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn"/&gt;
      &lt;property name="jbosscache-cl-cache.jdbc.node.column" value="node"/&gt;
      &lt;property name="jbosscache-cl-cache.jdbc.parent.column" value="parent"/&gt;
      &lt;property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr"/&gt;
      &lt;property name="jgroups-multiplexer-stack" value="false" /&gt;
      &lt;property name="jbosscache-shareable" value="true" /&gt;
   &lt;/properties&gt;
&lt;/lock-manager&gt;</programlisting>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section id="JCR.ClusterConfig.How_to_stop_the_node_properly">
    <title>How to stop the node properly</title>

    <para>To be sure that all transactions are over and JCR is in consistent
    state after stopping node, you need to follow next steps:</para>

    <itemizedlist>
      <listitem>
        <para>Connect using JMX to one of cluster's node which you won't need
        to stop.</para>
      </listitem>

      <listitem>
        <para>Use RepositorySuspendController suspend all repositories (see
        <link linkend="JCR.SearchIndexBackup">37.1 Repository
        suspending</link>)</para>
      </listitem>

      <listitem>
        <para>Stop the node</para>
      </listitem>

      <listitem>
        <para>Use RepositorySuspendController to resume all repositories (see
        <link linkend="JCR.SearchIndexBackup">37.3 Repository
        resuming</link>)</para>
      </listitem>
    </itemizedlist>
  </section>
</section>
