Apache/Tomcat/Jakarta Howto

This document is intended to act as a step by step guide in how to integrate Apache2 with Tomcat/Jakarta using the mod_jk connector for supporting seamless virtual hosts. This is not intended to be a replacement for existing documentation for the respective items of software, but rather is intended to be focused on the configuration required.

Requirements

• Apache2
• Tomcat
• libapache-mod-jk or libapache2-mod-jk

In Debian based systems, these packages are easily installed using apt-get. Tomcat will be available as either Tomcat4 or Tomcat5 or Tomcat6 depending on the version you are running. For other distributions, look around. There are likely to be .rpms available for Redhat/Mandrake/Suse/Fedora/Centos type distributions. I prefer apt .deb packages since dependencies are generally handled much better, though the yum package updater works well too.

I will not go into configuring an Apache hosted website since that is not the scope of this document. Nor will I go into creating a Tomcat application - again, this is outside of the scope of this document. I will assume you have written a main website and also have written a webapp or series of .jsp pages to be served by Tomcat.

Setting the Stage

Let us define a case scenario to work with. You have a website named "myserver.com". Your main website is filled with the everyday kind of drivel (ie: Linux is great, blah blah blah). You have created a JSP site to calculate the solution to world hunger. You want your server to serve the JSP site when your server is called with the name "worldhunger.myserver.com".

You could handle this the following way. You could create a new server that just runs tomcat and move your site to the /usr/share/tomcat/webapps/ROOT directory. You could then create a DNS entry for worldhunger.myserver.com to point to your new server.

Why not? Well, you now have 2 servers doing the work that 1 server can do. You have also shot yourself in the foot for performance on your new worldhunger server since Tomcat can in no way meet standard HTTP requests on the same level as Apache can.

What's the solution then? mod_jk to the rescue!

Down to Business

In most cases Tomcat places it's webapps directory in /usr/share/tomcat/ webapps. This will vary on the distribution and package of course, but for the remainder of this document this is how we will refer to it.

Here is the catch to it all though - in order to reference one of these webapps you need to refer to it as http://mydomain.com/mywebapp. This can be clumsy if you want the site referred to by a FQDN. As previously mentioned you could stuff your webapp into the special ROOT folder, but then you can only serve one site, instead of the multiple sites that should be available.

As you should know, Apache is capable of serving up different site content based on the name it is called by using the VirtualHost containers. All we need to do now is create a special VirtualHost that will pass on required requests to the Tomcat server. Thus is the purpose of mod_jk born.

Consider the following VirtualHost container - normally this would tell Apache that any requests passed to it using the prefix "worldhunger" should serve up content from the worldhunger webapp directory.

NameVirtualHost *:80 Port 80 SSLDisable ServerName worldhunger.* ServerAdmin shaun@albinorabbit.homelinux.org DocumentRoot /usr/share/tomcat/webapps/worldhunger

The only problem here is that Apache doesn't know how to handle *.jsp files, let along web servlets. Let's assume you have installed mod_jk from the .deb package. All you should need to do now is activate it in apache. Default installation should have enabled the module in your /etc/apache-ssl/ modules.conf file.

Configuring mod_jk

Add the following lines to your httpd.conf file:

JkWorkersFile /etc/libapache-mod-jk/workers.properties JkLogFile /var/log/apache-ssl/mod_jk.log JkLogLevel info

These should go at the top level of your configuration before any virtual host definitions. The Workers file may be installed in a different place dependent on your distribution. Basically, the workers file defines the mod_jk processes that listen for any redirecting requests. See the tomcat documentation for further information.

Now, let's modify that virtual host container to make use of this information.

NameVirtualHost *:80 <VirtualHost *:80> Port 80 SSLDisable ServerName worldhunger.* ServerAdmin shaun@albinorabbit.homelinux.org JkMount /*.jsp ajp13 JkMount /servlet/* ajp13 DocumentRoot /usr/share/tomcat/webapps/worldhunger </VirtualHost>

What this will do is have apache pass any requests for *.jsp files to the mod_jk worker named ajp13 (configured by default with mod_jk installation) as well as any requests for files in the servlet directory. Anything else will be handled locally by apache.

Configure Tomcat

Now you need to create a corresponding entry for tomcat, otherwise it will only respond to the /worldhunger reference. The file to edit will be /usr/share/ tomcat/server.xml.

<Host name="worldhunger.albinorabbit.homelinux.org" debug="0" unpackWARs="true"> <Alias>*.worldhunger.albinorabbit.homelinux.org</Alias> <Logger className="org.apache.catalina.logger.FileLogger" directory="logs" prefix="worldhunger." suffix=".log" timestamp="true"/> <Context path="" docBase="/usr/share/tomcat/webapps/worldhunger" debug="0" reloadable="true"/> </Host>

Make sure that you pay attention to nesting with this entry - this needs to be a top level entry!

Restart tomcat and apache and test your settings. That's all there is to it!