Integrating Tomcat with Apache
March 7, 2008
If you write JavaServer Pages or use Servlets to provide the functionality of your Web site, you're probably already aware of Tomcat. Tomcat is the Apache Foundation's reference implementation of the JavaServer Pages and Servlet technologies. Tomcat 3 covers the Servlet 2.2 and JSP 1.1 revisions, while Tomcat 4 covers Servlet 2.3 and JSP 1.2. Tomcat itself is part of the Jakarta Project, which is a suite of Java development tools developed through the Apache foundation.
Installing Tomcat itself is relatively easy download the corresponding installer from the Tomcat pages at Apache, expand the files or run the installer, and then use the corresponding script to start up the Tomcat service. Tomcat has its own built-in HTTP service that handles and services requests from clients. We'll look at the specific steps later in this article.
To integrate the Tomcat server processes with the Apache HTTP server we need the mod_jk module, which implements the interface between Tomcat and Apache, combined with some small steps to configure Apache and Tomcat to our needs.
Tomcat is written in Java, while Apache and its modules are written in C, so how do the two work together?
Well, when Tomcat executes as well as creating an HTTP listener service, it also creates a number of "worker" processes responsible for executing JSPs/servlets. The mod_jk module is written in C, so it's incapable of interpreting Java classes directly. Instead, mod_jk communicates with the various worker processes created by Tomcat through a network connection. There is, of course, slightly more to it than that, but the core execution is handled through Apache to Tomcat and back again.
There are some advantages to this method, even though it looks convoluted. The primary advantage is flexibility. For example, if you wanted to run Apache (and mod_jk) on one physical server but the Tomcat service and the actual JSPs and servlets on another machine, you can. Some companies use this method to provide an additional level of security, with the Tomcat server behind another firewall only accessible from the Apache server.
Another advantage is stability if a significant failure within Tomcat caused it to fail completely, it wouldn't render your entire Apache service unusable, just your servlets and JSP pages.
We'll be using Tomcat 4.1.18, although the connector pack we'll be using will actually work with any version of Tomcat you want to use.
After you've installed Java, make sure you set your JAVA_HOME environment variable to point to your Java installation, as it's needed not only by Tomcat but also by other tools we use in this article. You'll probably also want to set your PATH variable to point to the bin directory within the Java directory so you have easy access to all the Java tools.
Now download Tomcat. There's no installer under Unix/OS X, so once downloaded, extract the package and then copy the directory created to where you want to store your Tomcat installation. Within Windows use the installer.
Once installed, you can startup and shutdown Tomcat using the provided scripts. These are in the bin directory and called startup (Windows) or startup.sh (Unix). By default Tomcat runs on port 8080. To change this, edit the file conf/server.xml in the Tomcat directory and replace 8080 with the port number you want to use.
You can test your installation by opening up a web browser and entering a suitable URL for your machine.
Shutdown scripts are provided in the bin directory if you want to shutdown your Tomcat installation.
Download the file and copy it into your libexec or modules directory within your Apache server installation.
Original date of publication, 05/03/2003
Next: Configuration and Beyond
As with other modules, there are two parts to the configuration. The first just tells Apache that the module exists and where to find it using a LoadModule directive. The second part tells the module how to function within the Apache environment. For mod_jk the minimum we need is:
JkLogFile specifies the location of a log for mod_jk errors and information. JkLogLevel and JkLogStampFormat specify what the log contains and what it looks like.
The Workers File
If you built mod_jk from the source you can find a sample workers.properties file that will work perfectly with the default configuration file for Tomcat in the jk/conf directory. In fact, it's probably worth downloading the connector source code for that file alone!
If you don't want to download the source, then you should be able to get by using the following:
To test out your installation, copy a suitable JSP or servlet into your Web server directory and then try accessing it from a browser. Remember that you must have both Tomcat and Apache running. Assuming everything is working OK then you should get the desired result. If there's an error, you'll need to check one of the various log files for more information. To help you determine which one, look at the error message reported in the browser.
If the error was generated by Tomcat, then you need to check the Tomcat logs in the main Tomcat installation directory. It probably means either there is an error in your JSP or a class on which it relies or there is a problem with accessing the file in question. Because requests are forwarded to Tomcat immediately, a missing file will be reported by Tomcat, not Apache.
If it's an error generated by Apache, check the Apache logs and the mod_jk logs. If the error is reported in the mod_jk log, then it probably points to a problem with the configuration somewhere.
If you get an Internal Server Error from Apache, then check whether Tomcat is running before digging any deeper.
Original date of publication, 05/03/2003