Documentation

Preinstallation

This page explains Smith preinstallation steps. It includes details on how to install and configure Java, Apache, Tomcat and apache tomcat connector. To make the presintallation process easier to understand, these steps are described using concrete versions of each tool and for a concrete platform - CentOS 4.4. It should be fairly easy to adapt these instructions to any other platform.

Here's the list of preinstallation steps:

Installing Apache web server
Installing Java
Installing Tomcat 5
Installing apache-tomcat connector
Configure Apache mod_jk (tomcat-connector)
Debugging

More details on configuring Tomcat with Apache or with IIS can be found in The Apache Tomcat Connector documentation.

Step 1 - Installing Apache web server

First of all, we will check whether apache package (httpd) is already installed. This is done as follows:

    # rpm -q httpd
    httpd-2.0.52-9.ent.centos4.1

If the package is not installed, we will install it via yum repo.

To see available httpd version, type:

    # yum list | grep httpd

To install apache, type the following:

    # yum install httpd httpd-devel

This command will install all necessary packages.

Step 2 - Installing Java

Go to sun website (java.sun.com) and download jdk package for your platform (in our case, jdk-1_5_0_09-linux-i586-rpm.bin). Place it in /tmp folder and then start the installation:

    # cd /tmp
    # sh jdk-1_5_0_09-linux-i586-rpm.bin

It will first show the license agreement and then install java right away.
When finished, we'll have java (jdk) installed in: /usr/java/jdk1.5.0_09

Step 3 - Installing Tomcat 5

Now go to tomcat.apache.org and download the latest stable version of tomcat. In our case, tomcat v5.5.20.

Choose the core distribution (in tar.gz format) and download it to /tmp folder:

    # wget http://mirrors.isc.org/pub/apache/tomcat/tomcat-5/v5.5.20/bin/apache-tomcat-5.5.20.tar.gz

make /opt directory if it doesn't already exist:

    # cd /
    # mk opt
    # cd /opt

move tomcat package to /opt

    # mv /tmp/apache-tomcat-5.5.20.tar.gz /opt

and then unzip the package:

    # gunzip apache-tomcat-5.5.20.tar.gz
    # tar -xvf apache-tomcat-5.5.20.tar
    apache-tomcat-5.5.20/bin/catalina.sh
    apache-tomcat-5.5.20/bin/digest.sh
    apache-tomcat-5.5.20/bin/setclasspath.sh
    apache-tomcat-5.5.20/bin/shutdown.sh
    apache-tomcat-5.5.20/bin/startup.sh
    ...

Now move apache-tomcat-5.5.20 to tomcat5 directory:

    # mv /opt/apache-tomcat-5.5.20 /opt/tomcat5

Edit catalina.sh in /opt/tomcat5/bin directory and add JAVA_HOME and JRE_HOME variables. Also, we will add JAVA_OPTS:

    JAVA_HOME=/usr/java/jdk1.5.0_09
    JRE_HOME=/usr/java/jdk1.5.0_09/jre
    JAVA_OPTS="-server -Xms1024M -Xmx1024M -XX:PermSize=256m -XX:MaxPermSize=256m \
        -Duser.language=de -Duser.country=CH -Dfile.encoding=UTF-8 \
        -Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl"

Note that Smith uses log4j for logging. When tomcat starts Smith servlet, it performs log4j initialization. But since tomcat first loads libraries located at approot/WEB-INF/lib and then loads the web application, it may warn that log4j was not properly initialized. If you want to suppress this warning, simply create approot/WEB-INF/classes/log4j.properties file with the following contents:

    log4j.rootLogger=info, R
    log4j.appender.R=org.apache.log4j.ConsoleAppender
    log4j.appender.R.layout=org.apache.log4j.PatternLayout
    log4j.appender.R.layout.ConversionPattern=%-5p %-30.30c{1} %x - %m%n

Step 4 - Installing apache-tomcat connector

Download the source distribution of apache-tomcat connector:

    # cd /tmp
    # wget http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.20/tomcat-connectors-1.2.20-src.tar.gz

Unpack the source package:

    # gunzip tomcat-connectors-1.2.20-src.tar.gz
    # tar -xvf tomcat-connectors-1.2.20-src.tar

then reach the "native" directory and compile tomcat-connector:

    # cd  /tmp/tomcat-connectors-1.2.20-src/native
    # ./cofigure –with-apxs=/usr/sbin/apxs
    # make
    # make install

If compile procedure is finished without errors, we can go to the next step.

Step 5 - Configure Apache mod_jk (tomcat-connector)

Add the following to apache httpd.conf

    # Load mod_jk module
    # Update this path to match your modules location
    LoadModule    jk_module  modules/mod_jk.so
    # Where to find workers.properties
    # Update this path to match your conf directory location (put workers.properties next to httpd.conf)    
    JkWorkersFile /etc/httpd/conf/workers.properties
    # Where to put jk shared memory
    # Update this path to match your local state directory or logs directory
    JkShmFile     /var/log/httpd/mod_jk.shm
    # Where to put jk logs
    # Update this path to match your logs directory location (put mod_jk.log next to access_log)
    JkLogFile     /var/log/httpd/mod_jk.log
    # Set the jk log level [debug/error/info]
    JkLogLevel    info
    # Select the timestamp log format
    JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "

Create file workers.properties in /etc/httpd/conf
And add following to the file:

    # Define 1 real worker using ajp13
    worker.list=worker1
    # Set properties for worker1 (ajp13)
    worker.worker1.type=ajp13
    worker.worker1.host=localhost
    worker.worker1.port=8009

In /opt/tomcat5/conf/server.xml, comment out the stand alone http port 8080 and uncomment the AJP/1.3 connector:

    <!--  <Connector port="8080" maxHttpHeaderSize="8192"
                  maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                  enableLookups="false" redirectPort="8443" acceptCount="100"
                  connectionTimeout="20000" disableUploadTimeout="true" />  -->    

    <Connector port="8009"
            enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

At this point, configuring tomcat connector is done. We only need to configure virtual host.

Uncomment line " NameVirtualHost *:80 " in /etc/httpd/conf/httpd.conf

Create file virtual.conf in /etc/httpd/conf.d with the following contents:

    <VirtualHost *:80>
        ServerAdmin webmaster@dummy-host.example.com
        ServerName dummy-host.example.com
        JKMount /* worker1
    </VirtualHost>

Note that in JKMount command, we are using the same worker defined in workers.properties, in our case that is worker1.

Also in tomcat /opt/tomcat5/conf/server.xml we need to define a host:

    <Host name="dummy-host.example.com" appBase="webapps"
            unpackWARs="true" autoDeploy="true"
            xmlValidation="false" xmlNamespaceAware="false">
        <Context path="" docBase="/data/dummy-host"
                reloadable="true" privileged="true" antiResourceLocking="false" antiJARLocking="false">    
        </Context>
    </Host>

At this point, your web host is configured and you can start apache and tomcat.

Starting apache with command "service httpd start".
And starting tomcat with command "/opt/tomcat5/bin/startup.sh".

Step 6 - Debugging

In case of failure, you can debug apache and tomcat via their log files.
Location of log files are respectively: /var/log/httpd and /opt/tomcat5/logs/

In case of apache failure:

    tail -f /var/log/httpd/error_log

In case of tomcat failure:

    tail -f /opt/tomcat5/logs/cataline.out

In case of connector failure:

    tail -f /var/log/httpd/mod_jk.log