Apache 1.3 + Tomcat 5.x + Debian Woody

Apache is great. Tomcat is great. Having them work together is great. But trying to get them to work together under Debian Woody can be…shall we say challenging? The JK2 connector is the preferred way to have Apache and Tomcat communicate, but the only binaries for JK2 I could find were for Red Hat, and who wants that? So, it was time to build from source. There were a few gotchas along the way, and so I have written this article to help you avoid the problems, and get your webapps up and running under Woody quickly and easily.

This article assumes that you are using Debain Woody. Installation on other distributions will vary, but the general steps should be the same. You will need permission to install software on the system, and need to know how to start and stop processes.

Here are the steps. Each one will be covered in detail.

1. Install Apache
2. Install APXS
3. Install a Java Development Kit
4. Install Tomcat
5. Download apr (Apache Portable Runtime) source
6. Download apr-util source
7. Download and build jk2 connector sources
8. Configure Apache and Tomcat
9. Start servers and test

Step 1: Install Apache

Installing Apache should be a breeze. As root, just apt-get apache. Or use dselect. Once Apache is installed, fire up your browser and point it at http://localhost. You should see a welcome page. Good job! On to Step 2.

Step 2: Install APXS

APXS is the APache eXtenSion tool. Installing this is also a breeze. As root, apt-get apache-dev. Or use dselect. See? Pretty easy so far. Step 3 coming up.

Step 3: Install Java Development Kit

If you have not already done this, go to Sun and get a Java SDK. You want the SDK (Software Development Kit), not the JRE (Java Runtime Environment). Make sure you get the Linux self-extracting file. I used version 1.4.2_06; it is available here. Detailed installation instructions are available.
For this example, I have installed the SDK in /usr/local, and my JAVA_HOME is /usr/local/j2sdk1.4.2_06.
Once you have the SDK installed, move on to Step 4.

Step 4: Install Tomcat

If you have not already done this, go to Tomcat’s Home Page, and download the Tomcat binaries. I used version 5.0.28.
Installing is just a matter of extracting the archive into a directory. For this example, I installed Tomcat in /usr/local.
Start Tomcat by running the startup script. For this example:

cd /usr/local/jakarta-tomcat-5.0.28/bin
./startup.sh

It is handy to fire up an xterm and watch the Tomcat logs:

tail -f /usr/local/jakarta-tomcat-5.0.28/logs/catalina.out

Test your Tomcat installation by pointing your web browser at http://localhost:8080. You should see the Tomcat welcome page.

Now that you have Apache and Tomcat working, you need to get them talking to each other. On to Step 5.

Step 5: Download the Apache Portable Runtime sources

Using JK2 with Apache 1.3 means that you need the APR (Apache Portable Runtime) source code. You don’t have to compile it – the JK2 build process will build APR for you.
Download the folllowing files from an Apache mirror.

apr-0.9.4.tar.gz
apr-util-0.9.4.tar.gz

The latest version available as of this writing is 1.0.0 – BUT – version 1.0.0 will not compile correctly with JK2 and Apache 1.3. I don’t know why, but I know that version 0.9.4 does work. So download 0.9.4. Or you are on your own.
Once you have the apr and apr-util source archives, extract them. You will need to know the full path to the source code when building JK2. In this example, the source archives were extracted in /usr/local, so the source code for apr is located at /usr/local/apr-0.9.4, and the source code for apr-util is located at /usr/local/apr-util-0.9.4.

Step 6: Download and Build JK2 Source

We’re getting closer. Download the JK2 source archive from the Jakarta Site Source Downloads page. The latest version at the time of this writing is 2.0.4.
Extract the archive, and change to the JK2 native directory:

tar zxf jakarta-tomcat-connectors-jk2-src-current.tar.gz
cd jakarta-tomcat-connectors-jk2-2.0.4-src/jk/native2

Run the configure script, specifying the location of apxs, apr, and apr-util:

./configure –with-apxs=/usr/bin/apxs –with-apr=/usr/local/apr-0.9.4 –with-apr-util=/usr/local/apr-util-0.9.4

Build the connector:

make

Now, you are ready to install the connector. But you should stop Apache and Tomcat first:

/etc/init.d/apache stop
/usr/local/jakarta-tomcat-5.0.28/bin/shutdown.sh
cd ../build/jk2/apache13
/usr/bin/apxs -n jk2 -i mod_jk2.so

JK2 is now built and installed. Move on to Step 7, and configure your servers to use it.

Step 7: Configure Apache and Tomcat

There are three files you need to worry about. The Apache configuration file, httpd.conf; the Tomcat configuration file, server.xml; and the JK2 configuration file, workers2.properties.

For Apache, the following line needs to be added to httpd.conf (located in /etc/apache by default on Debian):

LoadModule jk2_module /usr/lib/apache/1.3/mod_jk2.so

Now look at your Tomcat configuration file (server.xml), located in the conf directory of your Tomcat installation. The JK2/AJP 1.3 connector is defined in the default configuration file. Make sure it is still there. It should look something like this:

<!--– Define a Coyote/JK2 AJP 1.3 Connector on port 8009 –-->
<connector port="8009″ enableLookups=" false="" redirectport="8443″ debug=" 0="" protocol=""><br /></connector>

Now, the JK2 configuration file. Create a file called workers2.properties in the Apache configuration directory:

touch workers2.properties /etc/apache

Put the following lines in workers2.properties:

[channel.socket:localhost:8009]
port=8009
host=127.0.0.1
[ajp13:localhost:8009]
channel=channel.socket:localhost:8009
[uri:/jsp-examples/*]
worker=ajp13:localhost:8009

Step 8: Start Servers and Test

At this point, everything should be in place for Apache to serve the webapps that are configured in the workers2.properties file. So it is time to start the servers and test.

First, start Tomcat. You should see something like this in the Tomcat logs:

INFO: JK2: ajp13 listening on /0.0.0.0:8009
Nov 19, 2004 9:58:18 AM org.apache.jk.server.JkMain start
INFO: Jk running ID=0 time=11/137 config=/usr/local/jakarta-tomcat-5.0.25/conf/jk2.properties

Now, start Apache.

And, the moment of truth has arrived. Point your browser at http://localhost/jsp-examples. You should get the Tomcat jsp example page, without having to specify the port.

You can now add more webapps to the workers2.properties file. Just add more [uri] sections, one for each webapp that you want Apache to serve.

Once you have Tomcat and Apache working together, you can start to make the configuration changes required for your environment. Everybody has different needs, and not all possible combinations can be addressed here. But you should now have a good place to start.

If you find errors in this documentation, please let me know.

Happy serving!