<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../User_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter id="Quick_Start_Guide">
  <title>Quick Start Guide</title>
  <para>
    The following are the steps to set up a minimal working installation of mod_cluster on a single httpd server and a single back end server, either JBoss AS, JBossWeb or Tomcat.
    The steps can be repeated to add as many httpd servers or back end servers to your cluster as is desired.
  </para>
  <para>
    The steps shown here are not intended to demonstrate how to set up a production install of mod_cluster;
    for example <link linkend="UsingSSL">using SSL to secure access</link> to the httpd-side mod_manager component is not covered.
    See the <link linkend="native.config">httpd-side</link> and <link linkend="java.config">java-side</link> configuration documentation for the full set of configuration options.
  </para>

  <section>
    <title>Download mod_cluster components</title>
    <para>
      Download the latest <ulink url="http://www.jboss.org/mod_cluster/downloads/latest.html">httpd and java release bundles</ulink>.
      If there is no pre-built httpd bundle appropriate for your OS or system architecture, you can <link linkend="native.building">build the binary from source</link>.
    </para>
  </section>

  <section>
    <title>Install the httpd binary</title>
    <section>
      <title>Install the whole httpd</title>
      <para>
        The httpd-side bundles are gzipped tars and include a full httpd install.
        As they contain already an Apache httpd install you don't need to download Apache httpd.
        Just extract them in root, e.g.
      </para>
      <programlisting>cd /
tar xvf mod-cluster-1.0.0-linux2-x86-ssl.tar.gz</programlisting>
      <para>
        That will give you a full httpd install in your <code>/opt/jboss</code> directory.
      </para>
    </section>

    <section>
      <title>Install only the modules</title>
      <para>
        If you already have a working httpd install that you would prefer
        to use, you'll need to download the bundle named mod_cluster httpd
        dynamic libraries corresponding to you plaform, extract the modules and
        copy them directory to your httpd install's module directory.
      </para>
      <programlisting>cd /tmp
tar xvf mod_cluster-1.2.0.Final-linux2-x86-so.tar.gz</programlisting>
      <para>
        And then you have to copy the files below to you module directory:
      </para>
      <itemizedlist>
        <listitem><para>mod_slotmem.so</para></listitem>
        <listitem><para>mod_manager.so</para></listitem>
        <listitem><para>mod_proxy_cluster.so</para></listitem>
        <listitem><para>mod_advertise.so</para></listitem>
      </itemizedlist>
    </section>

    <section>
      <title>Install in home directory</title>
      <para>
        Since 1.1.0.CR2 a script <code>opt/jboss/httpd/sbin/installhome.sh</code>
        allows reconfiguration of the bundle installation so that it can run in
        user's home directory.
        To do that just extract the bundle in your home directory and run the script.
        Once that done, httpd will run on port 8000 and will accept MCMP messages on
        localhost:6666 and offer <code>/mod_cluster_manager</code> on the same host and port.</para>
    </section>

    <section>
      <title>Install in Windows</title>
      <para>
        Unzip the bundle corresponding to your architecture.
      </para>
      <para>
        Change to the bin directory of the subfolder httpd-2.2 where you unzip the bundle
        and run the installconf.bat shell script.
      <programlisting>cd httpd-2.2\bin
       installconf.bat</programlisting>
      </para>
      <para>
        You may run httpd directly by using:
      </para>
      <programlisting>httpd.exe</programlisting>
      <para>
        or install Apache httpd as a service:
      </para>
      <programlisting>httpd.exe -k install</programlisting>
      <para>
        and start the service via net start or using httpd.exe:
      <programlisting>net start Apache2.2</programlisting>
      <programlisting>httpd.exe -k start</programlisting>
      </para>
      <para>
        Note that in the windows bundles have a flat directory structure, so you have <emphasis>httpd-2.2/modules/</emphasis> instead of
        <code>opt/jboss/httpd/lib/httpd/modules</code>.
      </para>
    </section>
  </section>

  <section>
    <title>Configure httpd</title>

    <para>
      Since 1.1.0.CR2 httpd.conf is preconfigured with the Quick Start values.
      You should adapt the default values to your configuration with older mod_cluster we will have to add the following to httpd.conf.
      If you extracted the download bundle to root as shown above and are using that extract as your httpd install,
      httpd.conf is located in <code>/opt/jboss/httpd/httpd/conf</code>.
    </para>
    <programlisting><![CDATA[LoadModule proxy_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy.so
LoadModule proxy_ajp_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy_ajp.so
LoadModule slotmem_module /opt/jboss/httpd/lib/httpd/modules/mod_slotmem.so
LoadModule manager_module /opt/jboss/httpd/lib/httpd/modules/mod_manager.so
LoadModule proxy_cluster_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy_cluster.so
LoadModule advertise_module /opt/jboss/httpd/lib/httpd/modules/mod_advertise.so
 
Listen 10.33.144.3:6666
<VirtualHost 10.33.144.3:6666>
 
  <Directory />
    Order deny,allow
    Deny from all
    Allow from 10.33.144.
  </Directory>
 
  KeepAliveTimeout 60
  MaxKeepAliveRequests 0
 
  ManagerBalancerName mycluster
  AdvertiseFrequency 5
 
</VirtualHost>]]></programlisting>
    <para>
      If you are using your own install of httpd, httpd.conf is found in your install's conf directory.
      The content to add to httpd.conf is slightly different from the above (different path to the various .so files):
    </para>
    <programlisting><![CDATA[LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
LoadModule slotmem_module modules/mod_slotmem.so
LoadModule manager_module modules/mod_manager.so
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
LoadModule advertise_module modules/mod_advertise.so
 
Listen 10.33.144.3:6666
<VirtualHost 10.33.144.3:6666>
 
  <Directory />
    Order deny,allow
    Deny from all
    Allow from 10.33.144.
  </Directory>
 
  KeepAliveTimeout 60
  MaxKeepAliveRequests 0
 
  ManagerBalancerName mycluster
  AdvertiseFrequency 5
 
</VirtualHost>]]></programlisting>
  </section>

  <section>
    <title>Install the server-side binaries</title>
    <para>
      First, extract the java-side binary to a temporary directory.
      The following assumes it was extracted to /tmp/mod-cluster
    </para>
    <para>
      Your next step depends on whether your target server is JBoss AS or JBoss Web/Tomcat.
    </para>

    <section>
      <title>Installing in JBoss AS 6.x</title>
      <para>
        You don't need to do anything to install the java-side binaries in AS 6.x;
        it's part of the AS distribution's default, standard and all configurations.
      </para>
    </section>

    <section>
      <title>Installing in JBoss AS 5.x</title>
      <para>
        Assuming $JBOSS_HOME indicates the root of your JBoss AS install and that you want to use mod_cluster in the AS's all config:
      </para>
      <programlisting>cp -r /tmp/mod-cluster/mod-cluster.sar $JBOSS_HOME/server/all/deploy</programlisting>
    </section>

    <section>
      <title>Installing in Tomcat</title>
      <para>
        Assuming $CATALINA_HOME indicates the root of your Tomcat install:
      </para>

      <programlisting>cp -r /tmp/mod-cluster/JBossWeb-Tomcat/lib/* $CATALINA_HOME/lib/ </programlisting>
      Note that you should remove in the $CATALINA_HOME/lib/ directory the mod_cluster-container-tomcat6* file in Tomcat7 and
      the mod_cluster-container-tomcat7* in Tomcat 6.
    </section>

    <section>
      <title>Installing in JBoss AS 4.2.x or 4.3.x</title>
      <para>Assuming $JBOSS_HOME indicates the root of your JBoss AS install and that you want to use mod_cluster in the AS's all config:
      </para>
      <programlisting>cp -r /tmp/mod-cluster/JBossWeb-Tomcat/lib/* $JBOSS_HOME/server/all/deploy/jboss-web.deployer/ </programlisting>
    </section>
  </section>

  <section>
    <title>Configuring the server-side</title>

    <section>
      <title>Configuring mod_cluster with JBoss AS 5.x+</title>
      <para>
        No post-installation configuration necessary!
      </para>
    </section>

    <section>
      <title>Configuring mod_cluster with standalone JBoss Web or Tomcat</title>
      <para>
        Edit the <code>$CATALINA_HOME/conf/server.xml</code> file, adding the following next to the other <![CDATA[<Listener/>]]> elements:
      </para>
      <programlisting><![CDATA[<Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true"/>]]></programlisting>
    </section>

    <section>
      <title>Integrate mod_cluster with JBoss AS 4.2.x and 4.3.x</title>
      <para>
        Edit the <code>$JBOSS_HOME/server/all/deploy/jboss-web.deployer/server.xml</code> file, adding the following next to the other <![CDATA[<Listener/>]]> elements:
      </para>
      <programlisting><![CDATA[<Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true"/>]]></programlisting>
    </section>
  </section>

  <section>
    <title>Start httpd</title>
    <para>To start httpd do the following:</para>
    <programlisting>/opt/jboss/httpd/sbin/apachectl start</programlisting>
  </section>

  <section>
    <title>Start the back-end server</title>
    <section>
      <title>Starting JBoss AS</title>
      <programlisting>cd $JBOSS_HOME/bin
./run.sh -c all</programlisting>
    </section>

    <section>
      <title>Starting JBossWeb or Tomcat</title>
      <programlisting>cd $CATALINA_HOME
./startup.sh</programlisting>
    </section>
  </section>

  <section>
    <title>Set up more back-end servers</title>
    <para>
      Repeat the back-end server install and configuration steps for each server in your cluster.
    </para>
  </section>

  <section>
    <title>Experiment with the Load Balancing Demo Application</title>
    <para>
      The <link linkend="demo">load balancing demo application</link> is a good way to learn about mod_cluster's capabilities.
    </para>
  </section>
</chapter>
