Integrating Tomcat with Apache Via the mod_jk Module

In a previous article, we learned about installing and configuring Jakarta Tomcat to run on Mac OS X.

In this basic install, Tomcat applications are accessed via port "8080," which means that you have to give your friends and relatives a Web address such as "http://www.mysite.com:8080".

Running a Web application on a non-standard port may be acceptable for development, but often gets you curious looks from friends, relatives, and possible customers. (Even the most original, creative domain name is ruined if you have to tack "8080" on the end of the URL!)

Obviously, we'd like to serve our dynamic HTML content through the standard HTTP port of "80," plus use the features of the Apache Web Server that we have under our command, such as secure communications, scripting language support, and better performance when serving static HTML pages. Fortunately, the Apache project provides such a connection through the mod_jk module that allows Apache to connect to other resources. (For further reference, please consult an earlier series of articles written about Apache Web serving with Mac OS X.)

Building mod_jk

While there are a few available methods for integrating Tomcat with Apache, the recommended (and currently maintained) approach is to integrate Tomcat with Apache via the mod_jk module. (mod_jk is the approach used with the latest Coyote connector modules provided by the Tomcat developers.) However, since there is no readily available binary, we'll have to build the mod_jk module before we can proceed. (For those that want to skip this step, the compiled module used by the author, plus all files used to create it, are available here.)

In order to build mod_jk, we'll need the sources from the Jakarta Tomcat connectors project, and a package that contains a library needed to compile the sources. Before proceeding, you should also verify that the latest version of the Mac OS X Development Tools are installed; several of the "make" utilities we'll need are part of the Developer Tools package.

First, grab the latest release version of the Tomcat connectors from the Jakarta Project. (The version used in this article is the connector for Tomcat 4.0.4, available on the source download page.) Grab the connectors package (in this example, jakarta-tomcat-connectors-4.0.4.src.tar.gz). Open a terminal window, cd to the directory where your source download is, and unpack the "tarball":

tar xzvf jakarta-tomcat-connectors-4.0.4-src.tar.gz

This should leave you with a folder with all of the connector sources.

Before we can build, we'll also need to grab a library for use in compiling the mod_jk module. This library is called dlcompat, and is available from the Fink project, on the source archive page. (Feel free to grab the latest version.) Again, unpack the source tarball to a local directory:

tar xzvf dlcompat-20020606.tar.gz

Now, we're ready to build the mod_jk module. First, we'll change our working directory to the directory where the needed mod_jk.c file is. In the version of the Jakarta Tomcat Connectors, this file is under the jk/native/apache-1.3 directory. There are a number of shell scripts here for various system builds. In particular, there is a file that we will modify:

-rw-r--r-- 1 cothomps staff 2961 Feb 13 11:53
build-hpux-cc.sh

While the build script will remain mostly intact, there are a few changes that we will need to make. The build script file, in its entirety, is listed below:

#!/bin/sh

# build-macosx.sh for mod_jk.so
#
# A modified version of Mike Braden's build-hpux.sh
# This builds mod_jk without JNI support
# Usage: sh build-macosx.sh
#
 # Chad Thompson (6/25/02)
# # Precondition: You'll need to grab the 'dlcompat' files from
# the fink project http://fink.sourceforge.net. Two files are
# needed in particular:
 # * dlfcn.h
# * dlfcn.c
# # NOTE: The version of Apache included with Mac OS X 1.5.1
# is the Darwin compiled version of Apache 1.3.23. Procedures
# may be different for later versions. (Apache 2.0 is just
# gaining steam at the time of this writing, and is currently
 # not included in OS X)


# The 'JAVA_HOME' for Mac OS X v. 1.5.1; modify accordingly
JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Home

 DLCOMPAT_HOME=/Users/cothomps/apache/dlcompat-20020606

#### End of configuration - do not change below

if [ -f /usr/sbin/apxs ] ; then
 # APXS is preinstalled on Mac OS X
 APXS=/usr/sbin/apxs
else
 echo Error: Unable to locate apxs.
 echo Verify that APACHE_HOME is set correctly in this script.
 exit 1
fi
if [ ! -d $JAVA_HOME/include ] ; then
 echo Error: Unable to locate Java libraries.
 echo Verify that JAVA_HOME is set correctly in this script.
 exit 1
fi

JAVA_INCLUDE="-I${JAVA_HOME}/include -I$DLCOMPAT_HOME"

INCLUDE="-I../common $JAVA_INCLUDE"

SRC="../common/*.c mod_jk.c $DLCOMPAT_HOME/dlfcn.c"

# Run APXS to compile the mod_jk module and its components
echo Building mod_jk
$APXS -o mod_jk.so $INCLUDE -c $SRC

# Check to see if the last command completed
if [ $? -ne 0 ] ; then
 echo Error with apxs
 exit 1
fi

echo mod_jk build complete.

#
# Clean up
#
rm jk_*.o
rm mod_jk.o

After the file is modified, run the build script:

sh build-macosx.sh

If everything is correct, the terminal window should begin filling with many lines that begin "cc"; this indicates that the build is proceeding. If everything completes successfully, you should be left with the last line printed by the shell script:

mod_jk build complete

Congratulations! If you do an ls -l command, a new file should be ready for your use:

-rw-r--r-- 1 cothomps staff 397692 Jul 3 15:14 mod_jk.so

With the module library now compiled, we need to install the module and instruct Apache how to load the mod_jk libraries. To do so, we'll have to do a few tasks as the "superuser." (I hope you paid attention to the warnings about using the superuser account!)

First, copy our newly-created module to the directory that holds the other Apache module files:

sudo cp mod_jk.so /usr/libexec/httpd/ 

Second, we'll have to modify the configuration file that controls the operation of the Apache Web Server, httpd.conf. Use your favorite text editor (the author's preference is the emacs text editor).

emacs /etc/httpd/httpd.conf 

Add the following to the end of the httpd.conf file, just a few simple instructions instructing Apache to load the module.

# Add and load the mod_jk module
LoadModule jk_module libexec/httpd/mod_jk.so
AddModule mod_jk.c

We'll have to add some additional lines in a few minutes, but this is enough to instruct Apache to load the module upon startup.