OK, it’s time to update my ageing Tomcat. I was running 5.0.19 on Mac OS X but for some reason was getting strange Struts errors, such as not being able to embed bean:message tags inside html:link tags. It works fine on the G4 but not the G5.

First stop then is Tomcat central but what’s the story with the connector? Apparently mod_jk2 is dead, due to lack of developer interest!
mod_jk2 is dead, long live mod_jk (again)

So what’s the latest mod_jk? That’s an easy question with no easy answer. The releases so far have gone:
mod_jk 1.2.7 beta -> beta2 -> beta3 -> 1.2.8 rc1
what happened to the release of 1.2.7? and why would I want an rc? What is an rc? If it’s a candidate for release then it’s obviously not a proper release, so where is the proper release?

According to this page it’s mod_jk 1.2.6. OK, download that but what trickery is this? It expands to mod_jk 1.2.8! There is no 1.2.6 or 1.2.7!

Anyway, once the Tomcat versioning and docs hurdles are overcome it’s a simple case of following the instructions on the installation page. In short, for Mac OS X:

• cd jakarta-tomcat-connectors-1.2.8-src/jk/native
• ./configure –with-apxs=/usr/local/apache/bin/apxs
• cd apache-2.0
• make -f Makefile.apxs
• make -f Makefile.apxs install

You’ll then have mod_jk.so in /usr/local/apache/modules

Mac OS X and JDK 1.5

Before you can use Tomcat 5.5.7 on OS X, you’ll have to go back to the Tomcat download page and get the compatibility package. It’s not obvious. I finally found it as “5.5.7 Compat tar.gz”. Expand it to get the files:

jakarta-tomcat-5.5.7/bin/jmx.jar
jakarta-tomcat-5.5.7/common/endorsed/xercesImpl.jar
jakarta-tomcat-5.5.7/common/endorsed/xml-apis.jar

and copy them to the corresponding directories in your Tomcat 5.5.7 directory.

Configure workers.properties

Next we have to configure /usr/local/apache/conf/workers.properties, using this page.

The two most important settings are:

workers.tomcat_home=/usr/local/tomcat
workers.java_home=/Library/Java/Home

Next we have to define a worker to handle requests transferred from Apache. I just deleted the default AJP12 and AJP13 workers as Tomcat seems to ignore everything after the first worker:

worker.list=sgarbh

worker.sgarbh.type=ajp13
worker.sgarbh.host=localhost
worker.sgarbh.port=8009
worker.sgarbh.socket_keepalive=1

This sets up a worker called “sgarbh” which you can use in your Apache virtual hosts to hook servlet requests. In fact, that’s what we’ll do now. Set up Apache to work with Tomcat.

Apache and Tomcat

/usr/local/apache/conf/httpd.conf
add these lines at the end of the file:

LoadModule jk_module modules/mod_jk.so
JkWorkersFile /usr/local/tomcat/conf/workers.properties
JkLogFile /var/log/apache/logs/jk/mod_jk.log
JkLogLevel trace

Here’s what they mean:

• LoadModule – this tells Apache to load the mod_jk connector we just built. It was put into the apache modules directory by make -f Makefile.apxs install
• JkWorkersFile – this tells the mod_jk connector where it can find it’s configuration file. That’s where we specify what workers are available for handling servlet requests transferred from apache
• JkLogFile – this is where to put the mod_jk connector’s log file. The directory you specify must exist and be writable by apache/tomcat. If you delete this file or the lines in it, it won’t be recreated/updated until you restart apache
• JkLogLevel – what sort of debugging info do you want? I set mine to “trace” to debug the workers and virtual hosts problems I was having but when it’s all fixed and you run a production system, you should set this to “info”

So now we’ve defined a worker to handle servlet requests, loaded the connector into apache. What’s still required? We need to map virtual hosts or content areas within virtual hosts to tomcat workers:

Apache virtual hosts and Tomcat workers

/usr/local/apache/conf/httpd.conf

<VirtualHost:80>
  ServerName test.uni.ac.uk
  DocumentRoot /WWW/test.uni.ac.uk/htdocs
  ServerAdmin test@uni.ac.uk
  ErrorLog /var/log/apache/logs/test.uni.ac.uk-error_log
  CustomLog /var/log/apache/logs/test.uni.ac.uk-access_log combined
  DirectoryIndex index.htm index.php
  JkMount /test-servlet/* sgarbh
</VirtualHost>

The JkMount directive tells Apache to send all requests for http://test.uni.ac.uk/test-servlet to the tomcat connector called “sgarbh”, which we defined earlier in our /usr/local/tomcat/conf/workers.properties.

Next we have to fool around with aliases and paths. This is where you wished mod_jk2 hadn’t disappeared as mod_jk is not as easy to configure. To divert all requests to /struts to Tomcat, you’ll have to add this lot to you VirtualHost container:

Alias /struts “/WWW/struts”
<Directory “/WWW/struts/”>
  Options Indexes +FollowSymLinks
</Directory>
JkMount /struts/* sgarbh
<Location “/*/WEB-INF/*”>
  AllowOverride None
  deny from all
</Location>