Tomcat, Apache and the Jk Connector

But if you want to do something with JSP/Servlets you need an Application Server that knows something about Java. Tomcat seems the most used for this, even if in the last years he had some competition by other products (Bea WebLogic, IBM WebSphere, Macromedia JRun et similia). The big disadvantages of those, is that they are not free.

Tomcat 5 is fast enough to be used to serve static html without big troubles, so you could get away by using Tomcat alone both for static and dynamic html. But sometimes you want to do something more, like performing sophisticated url rewriting, load or bandwidth control and the like. So, having a fully-fledged web-server in front of Tomcat is a good idea.

The solution is to 'connect' TomCat with Apache, somehow.

To do so, you use a "connector", that is nothing more than a piece of software that is installed in Apache (static compile or loaded at runtime) and knows how to call TomCat when necessary passing the whole request for processing and passing back the results.

This, veeeeeeery shortly, is the whole concept behind the 'connector'.

Warning: this document is based on Apache 1.3.x and Jk 1.2.x on Linux, the same instructions apply to Apache 2.x, further revisions could add (maybe) different versions of the Connector, but don't hold your breath.

But I'm using Windows... Stop reading right here! I know nothing about Windows, never used Apache on Windows and, frankly, don't give a damn about it. If you're using TomCat to develop and test Servlets or JSP you don't need a connector, no reason to mess around with Apache, if you want to run Apache on Windows on a production server don't ask me how. Don't send me mail to ask for documentation or pointers: I don't know.

When the Apache group started rewriting the whole Apache and built Apache 2, even the connector was rewrote and it came out as Jk2. The main difference between Jk1 and Jk2 was that the latter had the whole configuration file rewritten.

I never really liked the new "improved" configuration, too cumbersone and complicated. And, apparently, I wasn't the only one to not like it. After a while the (merry) news that Jk2 was dead and the work would have transferred on Jk1 spread around. So unless you have specific reasons to use Jk2, I suggest you get Jk1.

If it doesn't, then is time to read the Apache documentation and fix it before continuing.

Warning!!! Before you begin whine and send me mail about the fact that it doesn't work remember that: 1) the default configuration of Apache does work. So save the default config file before screwing it completely. 2) If Apache doesn't work there is no sense in going forward with more screw up. One damn thing at a time.

Then you need TomCat. Installed and working too. TomCat works by default on port 8080, so if you open another browser on http://ip.of.the.server:8080 you should see another merry page with "Tomcat" written all over the place.

Again, if it doesn't work, read the documentation. No sense in going on until both Apache and Tomcat don't work on their own. And again, the default configuration of Tomcat does work.

The Jk. Yeah, sure, you need it. On Apache web site you can find a pre-compiled binary or the source of the entire thing. Now, I've never had any luck with the pre-compiled, for some reasons they've never worked with me. So I always compile my own Jk.

To compile the Jk you need a C compiler and the whole lot of tools (automake, autoconf, make, linker...). If you don't have this stuff or you don't have the possibility to install them, then maybe you can try with the pre-compiled version. Otherwise you can see if your distribution does have a pre-compiled somewhere.

Let's suppose you have all the tools and you want to compile the code. Good: download the sources and unpack them somewhere, a ton of junk came out from the package, but the only thing you need is in the jk/native subdir.

Read the README and BUILDING file in there isn't a bad idea. In short: ./configure and then make. After that, you have in apache- the mod_jk.so. Just copy this where the other Apache modules are and you should be ready.

NOTE: if you don't want to use a dynamic module but you want to have it statically compiled in Apache, follow the instructions on Apache's web site.

httpd.conf
In httpd.conf you have to add:

LoadModule jk_module /where/is/mod_jk.so

JkWorkersFile   /where/is/workers.properties
JkLogFile       /where/you/want/jk_log        
JkLogLevel      debug
JkMount         /servlets-examples/*    ajp13

The same way you have to specify the path of the workers.properties file and where you want the log file.

workers.properties
This file contains the configuration for the various processes that communicate with TomCat. Minimum you need one "worker", nothing stops you to have multiple workers with different configuration. See the documentation for more info on this.

A minimal configuration is the following:

# workers.properties -
workers.tomcat_home=/usr/local/tomcat
workers.java_home=/usr/lib/java
ps=/

worker.list=ajp13
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13

The "port" and "host" entry refers to where Tomcat is listening, the default configuration is on port 8009. Attention: for 'listening' I mean where tomcat is listening for connection throught the connector, not using http. They are different.

Attention: The type of worker is ajp13 for Tomcat 5 and ajp12 for Tomcat 4. Don't mix them up.

When this is done, you should be able to issue an httpd -t or apachectl configtest and ess an "Ok", meaning: the configuration file is ok and the module can be loaded fine.

This means that the connector is working and TomCat is called into action when it has to.

But when ti has to? This is the pourpose of the JkMount directive that is in the httpd.conf.

In short, every 'directory' defined in JkMount is 'passed' to TomCat trought the defined worker.

JkMount	/servlets-examples/*	ajp13

We can add other JkMount directives and call TomCat for other applications. For example, adding

JkMount	/manager/*	ajp13

Suit yourself! The alternative is to use mod_proxy to call TomCat when necessary, like:

ProxyVia Off
ProxyPass	/application/	http://ip.of.server.here:8080/application/
ProxyPassReverse  /application/	http://ip.of.server.here:8080/application/

This basically does the same but is more brutal and the connector has more configuration options. See the documentation of the connector himself.

1. Be sure that TomCat knows about the new application

   Meaning: open your browser on http://...:8080/yourappshere/ and be sure that you get your application. Be sure that everything in your application works when called directly. If it doesn't work like this, there is no sense in expecting that it works from Apache.

2. Check if JkMount works

   If you added a JkMount directive and then type the URL you get an error from Aapche, it means that Apache doesn't see the JkMount directives. Remember that Apache's error have "Apache...something" written as last line, while TomCat contains "Apache Tomcat/something". Be sure you clean the cache of your browser before trying again.

3. Check if JkMount refer to the application

   If your application is Application1 and you have "mounted" it as Application2 probably it won't work.