Integrating Tomcat with Apache

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.

Installing Tomcat
Tomcat is very easy to install, as the only prerequisite is Java. If you don't already have the Java SDK (you need the SDK rather than the runtime) you can get a copy of Java for most platforms here.

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.

Installing mod_jk
The easiest way to get hold of a suitable mod_jk library is to go to the project's build directory. From there you'll find a number of directories for different platforms. Within each directory are two files, mod_jk for use with Apache 1.3.x and the other for use with Apache 2.x.

Download the file and copy it into your libexec or modules directory within your Apache server installation.

Building mod_jk
If you really want (or need) to, you can build your own mod_jk from the source. You'll need to download the Jakarta Tomcat Connectors pack. You'll also need Ant, the Apache Java build engine.

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:

LoadModule jk_module libexec/mod_jk.so

JkWorkersFile /usr/local/apps/jakarta-tomcat-4
      /conf/workers.properties

JkLogFile /usr/local/apache/logs/mod_jk.log

JkLogLevel info

JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
The JkWorkersFile should point to the location of the file that specifies how mod_jk should connect to the Tomcat service and interact with the various worker processes created by Tomcat.

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

The Workers file defines the various links between Apache, mod_jk and Tomcat. Essentially, Apache forwards any request for a given URL to the Tomcat service, but we must tell Apache how to identify which Tomcat process to communicate and forward the request.

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:

workers.tomcat_home=/usr/local/apps/jakarta-tomcat-4

workers.java_home=/usr/java1.4.1
ps=/
worker.list=ajp13
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13
That creates a connector called ajp13 (we'll need that in a minute), which is located on the local machine on port 8009. This is one of the standard ports listened to by Tomcat. You can define as many different connectors as you like, providing of course you have a corresponding Tomcat process listening on the right port.

Forwarding Requests
The final step is to tell Apache which files should be assigned to Tomcat for processing and which of the workers to direct the request to. You do this using the JkMount directive, which effectively mounts a Tomcat worker process to a given file specification. For example, to redirect all requests for files ending in .jsp on this server to the worker identified as ajp13, you would use:

JkMount /*.jsp ajp13
The file specification uses Unix-like wildcard specifications, so we could have specified that all files be forwarded to Tomcat using:

JkMount /* ajp13
Testing it Out
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.

Discuss this article in the ServerWatch discussion forum

Unsure About an Acronym or Term?
Search the ServerWatch Glossary
 

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