Tomcat

From Software By Jeff

Tomcat (http://jakarta.apache.org/tomcat) is the Apache project's Java JSP and Servlet server. It gives web hosts and developers a way to host programs and scripts for delivery to the web. It comes packaged and ready to handle web requests. If desired, Tomcat can be used without Apache and meet all of a web site's needs.

The Apache web server offers a lot more than simple web page delivery. Its ability to let other scripting engines easily hook in provides it tremendous power. An Apache web server may be required to handle static web pages, simple shtml included files, PERL scripting, PHP, Python, Ruby, and Java, as well as CGI executables written in any language. Additionally, it may be required to do so for virtual domains, or as part of a server farm. The Apache web server provides an excellent front-end for Tomcat, but its setup is not as easy as it might need to be.

This discussion is based on using source to build the system; binaries are typically available, and that simply means installing instead of building. This assumes you have a C compiler installed, and are comfortable with the make; install methods used to create software.

The discussion is also based on a simple Apache installation; that is, no virtual domains nor multiple Apache hosts on the one server.

First, make sure you have Java (http://java.sun.com) on your system; get a JDK--it'll be necessary for Tomcat to compile JSP pages on the fly. Then get the latest stable Apache HTTP Server (http://httpd.apache.org/download.cgi). You'll need the mod_jk (http://jakarta.apache.org/site/downloads/downloads_tomcat-connectors.cgi) connector for Apache to know how to deliver requests to Tomcat. Then download Tomcat (http://jakarta.apache.org/site/downloads/downloads_tomcat-5.cgi).

Then install each. Finally, configure each to work together.

Make sure to get the latest stable releases. For this discussion, on this day, the latest JDK is v1.5, Apache is v2.0, mod_jk is 1.2, and Tomcat is v5.5. The minor revision numbers change too frequently, and for the purposes of our discussion don't provide enough difference to be of concern.

JDK

It may be the case that there is a Java installation on the system already, but it's probably the Standard Environment installation--the Java runtime. It is important to install a JDK--the Java Development Kit. Fundamentally the difference is important to us only because Tomcat will need to be able to compile the JSP pages. Tomcat is written in Java, and will run on the Standard Edition. If you are not going to be hosting JSP pages, the SE install may meet your needs.

Alternatively, the Jikes (http://jikes.sourceforge.net) project provides a just-in-time compiler alternative to the one from Sun. Since we're advocating Open Source at this site, it behooves us to mention this option. We leave it to you, for now, to download, install, and configure Jikes if you prefer that route to installing a JDK.

The documentation continues assuming you've installed the JDK. Currently from Sun there are only binary releases of the JDK. This helps us since that means that the installation will pretty much be limited to extracting and copying files; which the installation program or script actually does for us.

Download and extract/execute the program from Sun. Depending on the version and OS used, the program will either extract everything right in your directory, or offer to install in a directory of your choice. Accordingly, be in the right place, with the right privliges. Ensure the new installation is in your environment's PATH, and that you have the rights to use the software.

Apache

Although binaries are available, we're going to discuss installing from source. This is done to provide us a little control over the resulting binary, including at the very least ensuring that dynamic module loading is enabled. Additionally, we may be forced to compile plug-ins and add-ons from souce, as we will with the mod_jk module we'll need to connect the web server to Tomcat.

Download and extract the source. Configure the build using a statement at the minimum like the following:

./configure --prefix=/usr/local/apache-2.0 --enable-http --enable-so

This tells the make process to eventually install the program in the /usr/local/apache-2.0 directory; techincally this is not required, but we want to know where it goes--the default installs everything in /usr/local, potentially clouding this installation with the installation of past or future releases. The program will have compiled-in capabilities to handle HTTP requests, and the ability to dynamically load DSO modules. This is the barest-bones configuration we can live with.

For a few more friendly features let's expand our installation with the following configuration line:

./configure --prefix=/usr/local/apache-2.0 --enable-http --enable-so --enable-dav --enable-speling --enable-cgi --enable-rewrite

This gives us Apache's built-in ability to do WebDAV and to correct minor URI errors. The ability to use other CGI programs is enabled, giving us the ability to run pre-compiled programs and compliant scripts. Additionally, we've enabled URI re-writing, which we may want to "spoof" incoming requests when we cannot just easily map them.

Do the normal make; make install process and the installation will finish with everything in /usr/local/apache-2.0 and almost ready to use.

mod_jk

Arguably, installing the mod_jk before we install Tomcat seems fruitless. It is true that the settings between the two must mesh, but really the mod_jk has more to do with Apache than with Tomcat, so we install it at the same time. Additionally, it is the case that mod_jk will work without a Tomcat installed; nothing will happen, but it will work.

There are contributed binaries of mod_jk installed, but they're not only not endorsed by Apache, but the use of those binaries removes our ability to control them.

Download and extract the v1.2 mod_jk source. There was a movement to create a v2, but that has since been abandoned. The features promised in v2 were not delivered, and maintenance on v1.2 is much more current. Curiously, the protocol used is ajp13, so don't confuse that protocol name with the version number of the module that makes it available.

Building is as simple as downloading, extracting, building, and adding the finished mod_jk library (.dll on Windows .so on other OSs) to the Apache modules directory.

Configuring mod_jk before installing Tomcat will simply result in "500 Server Error" messages when a mapping use is attempted. In fact, this will happen any time Apache is running but Tomcat is not.

httpd.conf

Configuration of mod_jk requires editing the Apache's httpd.conf file. This is usually located in the Apache installation's conf directory, but on some OSs may be installed in /etc/apache instead. Find and add lines like the following near the other LoadModules. The module needs to be loaded before it can be used, of course, but has no other dependencies so it can be anywhere in the LoadModules list.

<IfModule !mod_jk.c>
  LoadModule jk_module modules/mod_jk.so
</IfModule>

Then add a mapping so that Apache knows when to send things to Tomcat. These details can be anywhere in the httpd.conf file, after the LoadModule above, and is often placed immediately following; keep the IfModule block, though, in case a failure occured in trying to load the module.

<IfModule !mod_jk.c>
  JkWorkersFile modules/workers.properties
  JkMountFile modules/uriworkermap.properties  
</IfModule>

Other options are available to control the placement of log files and whatnot, but we'll leave that to the industrious reader to add into this section.

The first line, JkWorkersFile, sets the workers file that will contain the configuration for workers. Workers are simply the configuration items that Apache will use to communicate with a Tomcat server. Apache can talk to one or more local or remote Tomcat servers, and can even be configured to load balance these worker connections.

The second line, JkMountFile, sets the file in which the URL mappings will occur.

Note that you can provide the mappings contained in these files within the Apache httpd.conf, but by having them external, they can be altered and automatically reloaded by the mod_jk module without restarting Apache!

workers.properties

Make a workers.properties file that will hold the specifics for your workers. Put the file in the location specified in the httpd.conf file. Workers are tied to specific Tomcat instances, and can therefore be configured to direct work to different machines or even different Tomcat installations or host settings on the same machine.

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

This configures a worker named tomcat (the name can be anything you want) to which Apache will forward requests to the host (localhost) and port (8009) using the protocol type (ajp13) as specified; these can indicate another machine or port, but use the ajp13 protocol. Other workers can be added by simply adding them (comma delimited) to the worker.list property, and adding the sections (worker.name.) as appropriate. The name needs to match the one to which work is sent indicated on the httpd.conf JkMount.

uriworkermap.properties

/*.jsp=tomcat
/servlets/*=tomcat

The first mount is easy and obvious; we want our JSP scripts interpreted by Tomcat, not served as text by Apache. Nothing more than JSP will be handled because of this mount, and any JSP request on any path will be sent to Tomcat with this mount directive.

The second mount causes some concern and a little more care. Any request sent to the server's /servlets/ directory (e.g., http://your.server/servlets/foo) will be sent to the Tomcat server as specified in the workers.properties file. This includes /servlets/image.gif as well as /servlets/page.jsp and /servlets/servletClass. The configuration of what happens with the request is inside Tomcat, not inside Apache, so be careful when expecting other resources like images to be in the same path.

Tomcat

Installation of Tomcat is the easiest part of all of the installations necessary. Building Tomcat from source is a painful process, and since it's all Java and not C, we like the binary installation. Simply download the latest, and unpack it. The archive typically creates a tomcat directory; our habit is to rename that tomcat-version as appropriate, and if possible, make a symlink using tomcat. The directory into which this is installed is referred throughout the Tomcat documentation as $TOMCAT_HOME; therefore, if you installed this into /usr/local/tomcat, that is what they mean by $TOMCAT_HOME.

Inside the Tomcat directory, we're concerned mostly with the conf directory. We're going to make sure that AJP is enabled, and configured to match the Apache configuration. Additionally, we'll make sure our server is configured to handle our software where we want it to happen.

AJP

Inside the server.xml of the Tomcat conf directory is a line not unlike the following. Very simply ensure that it is not within an XML comment (generally it is not, but we want to be sure), and that the port matches that which was configured in the mod_jk file. This can be any port, as long as it's unique from other ports in use on the system, but typically the default of 8009 is sufficient.

<Connector port="8009" enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

That's it. The Tomcat can now handle AJP calls from Apache servers with mod_jk installed.

Host

For our simple setup, we want to ensure that the Host is correctly configured, too. A Host is Tomcat's way of relating requests to the file system. Here's the default Host from a freshly unpacked Tomcat installation.

      <Host name="localhost" appBase="webapps"
       unpackWARs="true" autoDeploy="true"
       xmlValidation="false" xmlNamespaceAware="false">

It tells us that the Tomcat server will look in its webapps directory for the contents of what it will serve. If this is acceptable, leave it alone. If you wish to have your applications in a directory outside of the Tomcat directory structure, which we recommend, change the appBase attribute to the absolute path of your applications.

      <Host name="localhost" appBase="/var/tomcat/webapps"
       unpackWARs="true" autoDeploy="true"
       xmlValidation="false" xmlNamespaceAware="false">

In this manner, we simply need to make sure to make the change to the appBase attribute whenever we update Tomcat, and the web apps take care of themselves.

Note that we've left the unpackWARs and autoDeploy both set to true. This allows us to simply deploy applications by putting new WAR files in the directory, or

Context

The idea of contexts takes a little getting used to. A "context" is what Tomcat calls an application; it is essentially all of the goods within a directory that make a thing tick. Typically within a context directory you'd have at least a WEB-INF directory and the JSP pages that are required for the application to run, in whatever directory structure makes sense; the compiled classes and libraries and such go into the WEB-INF directory of the context.

Simply, any directory under the webapps directory defined in the Host appBase that contains a WEB-INF directory is a context. Note that the webapps directory can itself be a context (the root) by having a WEB-INF directory in it. And contexts can contain contexts; the magic appearance of the WEB-INF directory spawns a context from that directory on. That way you can have webapps/app1 and webapps/app2 as wholly separate appliactions, each with their own resources, server as http://server.name/servlets/app1 and http://server.name/servlets/app2, given our previous Apache mod_jk discussion.

We'll touch on the XML way to define contexts in a later edit...

Other Tips

Ten things you should do to your Tomcat installation: onjava.com (http://www.onjava.com/pub/a/onjava/2003/06/25/tomcat_tips.html)