# Quick Start Guide

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.

The steps shown here are not intended to demonstrate how to set up a production install of mod_cluster; for example using SSL to secure access to the httpd-side mod_manager component is not covered. See the httpd-side and java-side configuration documentation for the full set of configuration options.

## Download mod_cluster components

Download the latest httpd and java release bundles. If there is no pre-built httpd bundle appropriate for your OS or system architecture, you can build the binary from source.

## Install the httpd binary

### Install the whole httpd

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.

    cd /
    tar xvf mod-cluster-1.0.0-linux2-x86-ssl.tar.gz

That will give you a full httpd install in your `/opt/jboss` directory.

### Install only the modules

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.

    cd /tmp
    tar xvf mod_cluster-1.x.y.Final-linux2-x86-so.tar.gz

And then you have to copy the files below to you module directory:

- mod_slotmem.so

- mod_manager.so

- mod_proxy_cluster.so

- mod_advertise.so

### Install in home directory

Since 1.1.0.CR2 a script `opt/jboss/httpd/sbin/installhome.sh` 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 `/mod_cluster_manager` on the same host and port.

### Install in Windows

Unzip the bundle corresponding to your architecture.

Change to the bin directory of the subfolder httpd-2.2 where you unzip the bundle and run the installconf.bat shell script.

    cd httpd-2.2\bin
           installconf.bat

You may run httpd directly by using:

    httpd.exe

or install Apache httpd as a service:

    httpd.exe -k install

and start the service via net start or using httpd.exe:

    net start Apache2.2

    httpd.exe -k start

Note that in the windows bundles have a flat directory structure, so you have httpd-2.2/modules/ instead of `opt/jboss/httpd/lib/httpd/modules`.

## Configure httpd

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 `/opt/jboss/httpd/httpd/conf`.

    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>

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):

    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>

## Install the server-side binaries

First, extract the java-side binary to a temporary directory. The following assumes it was extracted to /tmp/mod-cluster

Your next step depends on whether your target server is JBoss AS or JBoss Web/Tomcat.

### Installing in JBoss AS 6.x

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.

### Installing in JBoss AS 5.x

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:

    cp -r /tmp/mod-cluster/mod-cluster.sar $JBOSS_HOME/server/all/deploy

### Installing in Tomcat

Assuming $CATALINA_HOME indicates the root of your Tomcat install:

    cp -r /tmp/mod-cluster/JBossWeb-Tomcat/lib/* $CATALINA_HOME/lib/

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.

### Installing in JBoss AS 4.2.x or 4.3.x

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:

    cp -r /tmp/mod-cluster/JBossWeb-Tomcat/lib/* $JBOSS_HOME/server/all/deploy/jboss-web.deployer/

## Configuring the server-side

### Configuring mod_cluster with JBoss AS 5.x+

No post-installation configuration necessary!

### Configuring mod_cluster with standalone JBoss Web or Tomcat

Edit the `$CATALINA_HOME/conf/server.xml` file, adding the following next to the other <Listener/> elements:

    <Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true"/>

### Integrate mod_cluster with JBoss AS 4.2.x and 4.3.x

Edit the `$JBOSS_HOME/server/all/deploy/jboss-web.deployer/server.xml` file, adding the following next to the other <Listener/> elements:

    <Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true"/>

## Start httpd

To start httpd do the following:

    /opt/jboss/httpd/sbin/apachectl start

## Start the back-end server

### Starting JBoss AS

    cd $JBOSS_HOME/bin
    ./run.sh -c all

### Starting JBossWeb or Tomcat

    cd $CATALINA_HOME
    ./startup.sh

## Set up more back-end servers

Repeat the back-end server install and configuration steps for each server in your cluster.

## Experiment with the Load Balancing Demo Application

The load balancing demo application is a good way to learn about mod_cluster's capabilities.