Aerospace Software Ltd.

Tomcat Install Howto

Nov 2004, Redhat 7.2!!!

Please forgive me for the old Linux version, but this is an old server on the other side of the country and I did all of this remotely via SSH. This document should apply to any version of Linux and it can only be easier with a modern distribution!

The Tomcat Java Applet Server installation is a bit problematic. In order to figure out what you need to do, to install it, you have to download a long laundry list of source packages from jakarta.apache.org and start reading. Then when you actually start the installation, the build script will download everything all over again from CVS...

First of all, you need a Java development kit, then you need Apache Ant, which is used to build the whole thing and finally, you have to configure it.

Download a Java Development Kit (JDK) release (version 1.4.x or later) from:
http://java.sun.com/j2se/
Copy it to /usr/local/java and install it.

Set an environment variable JAVA_HOME to the pathname of the directory into which you installed the JDK release.

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

Install Apache Ant

Download a binary distribution of Ant 1.5.x from:
http://ant.apache.org/bindownload.cgi

Put Ant in a suitable spot and untar it:

cp apache-ant*gz /usr/local
cd /usr/local
tar -zxvf apache-ant*gz

Set some more environment variables

export PATH=$PATH:/usr/local/apache-ant-1.6.2/bin
export ANT_HOME=/usr/local/apache-ant-1.6.2

Build Tomcat 5.5 from Source

Note, it didn't quite work for me. It downloaded and compiled and installed everything, but there was no Tomcat binary anywhere to be found...

Since I am running a prehistoric Linux kernel on this machine, I have to build everything from source. Binary downloads usually won't run and invariably find some darn thing to complain about, but with Tomcat I was fortunately proved wrong...

Download the main build script from:
http://jakarta.apache.org/tomcat/tomcat-5.5-doc/build.xml

Get the tomcat source file with Ant and build the whole thing:

mkdir tomcat
mv build.xml tomcat
cd tomcat
ant

When you run this command, it will checkout the Tomcat 5 sources from CVS, as well as download binaries to the /usr/share/java directory. It ends with the following announcement:
BUILD SUCCESSFUL
Total time: 7 minutes 28 seconds

Hmmm, I then ended up with a bunch of crud in /usr/share/java and zero information on how to proceed from there...

Maybe someone else can enlighten me one day.

Install a Binary version of Tomcat

I gave up with the source version and got a binary tar ball here: http://jakarta.apache.org/site/binindex.cgi

Down at the bottom of that page, get Tomcat 5.5.4, file jakarta-tomcat-5.5.4.tar.gz Copy this file to /usr/local and untar it into directory jakarta-tomcat-5.5.4

In there, is a file called RUNNING.txt - read it.

You need to set some environment variables:

echo $JAVA_HOME /usr/local/java/jdk1.5.0
echo $CATALINA_HOME

Set them like this in /etc/rc.d/rc.local

export JAVA_HOME=/usr/local/java/jdk1.5.0
export CATALINA_HOME=/usr/local/jakarta-tomcat-5.5.4

Tomcat can be started by executing the following commands:

$CATALINA_HOME/bin/startup.sh

You can test Tomcat by going to this URL:
http://www.aeronetworks.ca:8080/
and you should get the default welcome page.

It actually worked on my old Linux and didn't complain about any C libraries. This is quite amazing and probably means that Tomcat is statically linked with everything it needs.

Hook Tomcat up with Apache

You need the mod_jk2 connector - most references in the documentation is wrong about the location of this connector and refers to the previous version. It is not in the Tomcat binary download file and is now distributed on its own.

The connector is used to forward Java applet page requests to Tomcat. Tomcat can also process static pages, but Apache is faster with that. So, through the connector, Apache is used as a preprocessor to Tomcat

The binary version didn't run on my old Linux and complained about a C library, so I had to build this infernal thing from source. By the way, you could also use mod_proxy or even Squid-cache to connect Apache to Tomcat. If I have to do this again, I'll probably use Squid - much easier and then you have an accellerator too.

For what they are worth, here are the official mod_jk2 howtos:

http://jakarta.apache.org/tomcat/tomcat-5.0-doc/config/ajp.html
http://jakarta.apache.org/tomcat/connectors-doc/jk2/
http://jakarta.apache.org/tomcat/connectors-doc/jk2/jk2/installhowto.html

These guides should be taken with a little salt, but that applies to any howto, including this one...

You can find the mod_jk2 source here:

http://jakarta.apache.org/site/sourceindex.cgi#Release%20Source%20Drops
http://apache.mirror.mcgill.ca/jakarta/tomcat-connectors/jk/jakarta-tomcat-connectors-jk-1.2-src-current.tar.gz

Untar it:

tar -zxvf jakarta-tomcat-connectors-jk2-src-current.tar.gz

There is no useful documentation anywhere and all the docs that Google can find are outdated (Nov 04)...

The subdirectories of this package are maximally confusing. It took one hell of a long time to figure out how to build this bloody module and once built, I had to search the disk for the output. The joker who did this should be clobbered with a clue-stick.

Here is one whole day's frustrating work in seven easy steps:

cd jakarta-tomcat-connectors-jk2-2.0.4-src/
cd jk/native2
./buildconf.sh
./configure --with-apxs2=/usr/local/apache2/bin/apxs
make
cd ../build/jk2/apache2
cp mod_jk2.so /usr/local/apache2/modules

If all went well, then you are now the proud owner of a freshly built Java connector.

Configure Apache to load the Connector Module

Here is an excerpt from httpd.conf:

# Load mod_jk
#
LoadModule jk2_module modules/mod_jk2.so

# First Virtual Host.
#

DocumentRoot /web/host1
ServerName host1.apache.org
JkMount /*.jsp ajp13
JkMount /servlet/* ajp13


# Second Virtual Host. Also accessible via HTTPS
#

DocumentRoot /web/host2
ServerName host2.apache.org
JkMount /*.jsp ajp13
JkMount /servlet/* ajp13



DocumentRoot /web/host2
ServerName host2.apache.org
SSLEngine On
JkMount /*.jsp ajp13
JkMount /servlet/* ajp13

Do the module load changes to httpd.conf and restart apache to see what happens. Ensure that apache still runs before continuing:

service httpd restart

Configure Apache and Tomcat to use the Connector

File jk2.properties is used on the Tomcat side. It's installation path in the $TOMCAT_HOME/conf directory. workers2.properties is used on the webserver side. For the Apache servers the default path is in the ServerRoot/conf directory.

NOTE: Although JK2 has many things in common with mod_jk, the configuration is quite different, and all the directives should be inside the workers2.properties. This enables JK2 to have the same configuration file no mater what the web server it's connected to.

The minimum configuration is the simplest one to make the JK2 working. The used channel will be socket, and lot of options are used by default. Both the Tomcat and web server are on the same computer.

jk2.properties:

# The default port is 8009 but you can use another one
#/ulannelSocket.port=8019

So, if port 8009 is OK, then we don't have to do anything to this file. That is all needed on the Tomcat side to configure the JK2.

workers2.properties:

# Define the communication channel
[channel.socket:localhost:8009]
info=Ajp13 forwarding over socket
tomcatId=localhost:8009
# Map the Tomcat examples webapp to the Web server uri space
[uri:/examples/*]
info=Map the whole webapp

So, normally, we don't have to do anything here either.

That's it, you can now restart Tomcat and Apache and access Tomcat from the Apache server.

/usr/local/jakarta-tomcat-5.5.4/bin/shutdown.sh
/usr/local/jakarta-tomcat-5.5.4/bin/startup.sh
service httpd restart

Browse to http://localhost/examples/

Hmm, Apache gives a 404, can't find it... Bah! Humbug!

Add a path to the configuration file to httpd.conf:

# Load mod_jk2
LoadModule jk2_module modules/mod_jk2.so
JkSet config.file /usr/local/jakarta-tomcat-5.5.4/conf/workers2.properties

Reload Apache and test again:

service apache reload
links http://localhost/examples/

404... Grrrrr...

Wait a minute - that error message comes from Tomcat, not Apache - which means that the redirector works, it is just my example Java application that is bad... sigh!

'Hope this helps!
Herman