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.

Configuring mod_jk

Now that we have built and loaded mod_jk, we need to tell Apache and Tomcat how to enable the communication. Fortunately, the Tomcat developers already have part of the configuration set up, so we'll just have to take advantage of that and set up some very simple files.

Configuration of the Tomcat connector is done via "workers" that will enable the connection. Change directory to the Tomcat conf/ directory and create a new file (with your favorite text editor) called workers.properties. In this example, we will set up a simple worker -- please consult the Tomcat documentation for further instructions and examples. Here is the example properties file:

# Setup for Mac OS X
workers.tomcat_home=/usr/local/tomcat
workers.java_home=/System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Home

 ps=/
worker.list=ajp12, ajp13

# Definition for Ajp13 worker
#
worker.ajp13.port=8009
worker.ajp13.host=127.0.0.1
worker.ajp12.type=ajp13

Apache will need to find this file to load the resources and create the connection with the running version of Tomcat. To do this, we'll have to edit the same http.conf file that we edited earlier. This time, add the following lines to the end of the file (adjust the paths to something appropriate for your Tomcat installation):

JkWorkersFile /usr/local/tomcat/conf/jk/workers.properties JkLogFile /usr/local/tomcat/logs/mod_jk.log JkLogLevel debug

Before continuing, we can test the configuration to see if everything has been set up correctly. First, restart Tomcat, then Apache. You can restart Apache through the "Web Sharing" option in the System Preferences, or by opening a command line and entering:

sudo apachectl restart

If everything has been installed correctly, the tail of the Tomcat logs/catalina.out file should read:

Starting service Tomcat-Standalone Apache Tomcat/4.0.4 Starting service Tomcat-Apache Apache Tomcat/4.0.4

With this last step, Tomcat is now able to serve requests for servlets and JSPs from the Apache Web Server. In order to define how an external browser uses an application, we'll have to define a "Virtual Host" in the httpd.conf file. Virtual host configurations can be somewhat complicated, and often reflect how you want users to refer to your application. For example purposes, we'll define our virtual host to be the default "localhost," which is by default recognized at the IP address 127.0.0.1. (For further reading on creating virtual hosts in a real-world deployment environment, consult the book Apache: The Definitive Guide.)

To enable the virtual host, first check that the ServerName is set to the localhost "loopback" address. Alter the definition of ServerName to read:

ServerName 127.0.0.1 

(There is a bit of documentation in the httpd.conf file about how the ServerName works, and the prerequisites for defining server names.)

With the server name defined, we can define a simple virtual host that will serve as an entry to the "examples" application included with Tomcat. This virtual host can be added to the end of the file:

<VirtualHost 127.0.0.1> DocumentRoot
/usr/local/tomcat/webapps JkMount /*.jsp ajp12 JkMount
/examples/servlet/* ajp12 </VirtualHost> 

The only "trick" involved is using the JkMount directive, which instructs the mod_jk module to use a worker defined previously in the workers.properties file.

After defining the virtual host, restart Apache. The examples should now be accessible at the addresses http://localhost/examples/jsp/ and http://localhost/examples/servlets/, respectively. Be sure to follow the links to verify that Tomcat is answering requests. As a second test, you may wish to check the access logs for both Apache and Tomcat. The Apache server should be serving the requests for the static front pages for the examples, while Tomcat registers the access requests for the JSP and servlet applications. After this final check, we've now enabled our Mac to serve Java-based applications using the built in Apache Web Server!

Chad Thompson is a developer based in Des Moines, IA. His primary interests are creating Java and XML based software, development methodologies (esp. Extreme Programming), and a recent rabid fascination with Mac OS X.

Return to the Mac DevCenter.

Copyright © 2009 O'Reilly Media, Inc.