Installing Tomcat5.5 and integrating it with Apache 1.3

Recently I have upgraded my web server at home to the latest version of Tomcat (version 5.5.7 at the moment of this writing). Time to document my steps a bit. Please note this document focusses on installing Tomcat 5.5 on a Debian Woody Linux machine, but the steps shouldn’t differ much on other Linux systems or (perhaps) even a Windows system.

As can be seen on the Tomcat Setup document page, Tomcat 5.5 is intended to be used with the J2SE 5 JRE. One version of this JRE can be downloaded from the Sun Java 2 Platform Standard Edition 5.0 download page. I downloaded the JDK and installed it into the /usr/local directory of my webserver using the commands

# chmod 755 jdk-1_5_0_01-linux-i586.bin

and

# ./jdk-1_5_0_01-linux-i586.bin

Please note this needs to be done as root user, since “normal” users don’t have write permissions in the /usr/local directory. Next, I set the JAVA_HOME environmental variable in the root user’s .profile file like this:

export JAVA_HOME=/usr/local/jdk1.5.0_01

To make the variable effective, I logged out and back in again.
I then downloaded the Tomcat binary version and installed it into the /usr/local directory as follows:

# tar zxf jakarta-tomcat-5.5.7.tar.gz

This created the directory /usr/local/jakarta-tomcat-5.5.7 and this is where everything Tomcat related resides. Both Tomcat itself and this document will refer to this directory as $CATALINA_HOME. To start Tomcat, I issued

# cd jakarta-tomcat-5.5.7/bin
# ./startup.sh
# tail -f /usr/local/jakarta-tomcat-5.5.7/logs/catalina.out

The last command makes sure the contents of the catalina.out log file are displayed on the screen and any new content in the file is shown as well. Once the line INFO: Server startup in 22292 ms was displayed, I knew Tomcat 5.5 was started up. To verify, I browsed to http://www:8080 to see the Tomcat 5.5 welcome screen.:

To add a web application, I needed to do two things. First of all, the web application needs to be placed in the $CATALINA_HOME/webapps directory. Second, a <Context> element needs to be added to $CATALINA_HOME/conf/server.xml file. Since I wanted to add a web application called Test, I would place it in the $CATALINA_HOME/webapps/Test directory and add this line

<Context path="/Test" docBase="Test" debug="99" reloadable="true"/>

to the $CATALINA_HOME/conf/server.xml file, just above the </Host> statement nearly at the bottom of the file. In case I would have liked to deploy my web application in a war file, I simply had to put the war file in the $CATALINA_HOME/webapps directory and place the war file name in the docBase attribute of the Context element in the server.xml file. Then I restarted Tomcat afterwards as root user like this

# cd /usr/local/jakarta-tomcat-5.5.7/bin
# ./shutdown.sh
# ./startup.sh

To access the Test web application, I had to browse to http://www:8080/Test/ but I really wanted to be able to browse to http://www/Test/. One way of doing this is modifying the Tomcat server config file to make Tomcat listen on port 80 instead of 8080 but that would of course interfere with the Apache web server listening on that port. Fortunately it is possible to transparantly forward all incoming requests for the Test web application from Apache to Tomcat using the Tomcat Connector which can be found on The Apache Jakarta Tomcat Connector.
The Tomcat Connector website provides binary versions for some Linux distributions and other operating systems. Unfortunately, Debian isn’t one of them, so I had to compile the module myself. For this, I downloaded the source package of version 1.28 which was the latest version of the Tomcat Connector at the time of this writing. To be able to build the Tomcat Connector module, the Apache Extension Tool apxs is needed. On Debian, this is provided by the apache-dev package, so I made sure it was installed. To build the connector, ungzip and untar the source tar ball and I used the configure and make commands like this:

# tar zxf jakarta-tomcat-connectors-1.2.8-src.tar.gz
# cd jakarta-tomcat-connectors-1.2.8-src/jk/native
# ./configure --with-apxs=/usr/bin/apxs
# make

After all of this, the Tomcat Connector module could be found in the apache-1.3 subdir of the directory these commands were executed from. To install the connector module, I issued as root user

# cp apache-1.3/mod_jk.so.0.0.0 /usr/lib/apache/1.3/

ln -s mod_jk.so.0.0.0 mod_jk.so

Please note that the path to the apache lib directory (/usr/lib/apache/1.3 in this case) may be different on different Linuxes or other operating systems. Finally, to make sure the correct paths are mapped from Apache to Tomcat, I added these lines to the Apache config file httpd.conf:

LoadModule jk_module /usr/lib/apache/1.3/mod_jk.so
<ifmodule mod_jk.c>
JkWorkersFile /usr/local/jakarta-tomcat-5.5.7/jk/workers.properties
JkLogFile /etc/apache/logs/mod_jk.log
JkLogLevel info
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
JkMount /Test/*.jsp worker1
JkMount /Test/* worker1
</ifmodule mod_jk.c>

and created the Tomcat Connector config file /usr/local/jakarta-tomcat-5.5.7/jk/workers.properties like this:

# 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
worker.worker1.lbfactor=50
worker.worker1.cachesize=10
worker.worker1.cache_timeout=600
worker.worker1.socket_keepalive=1
worker.worker1.socket_timeout=300

Next, I restarted Apache and browsed to http://www/Test/ and got to see my web application. That’s it!