Introduction

The original idea of these Hidden Help Files was to record how to do things that ought to have been simple, but which were hampered by a lack of documentation. Since it’s taken me several days’ graft to get Tomcat working on my Godaddy virtual shared server, this is a good candidate. I’ll try to remember all the steps involved.

Tomcat lets you run Java™ servlets and JSP pages. For largely historical reasons, my main work website is all written as JSP (I probably would have saved myself a lot of bother if I’d used PHP instead — I’m not doing anything complicated). Anyway, I’m in the process of moving from a Positive Internet shared server to a Godaddy virtual shared server, so I get root access and full control over what I install and how it runs. The down-side is that I have to take responsibility for setting everything up correctly.

The Architecture

The Go Daddy server comes with Red Hat Linux 9. This is rather old, but at least it ties in with the Red Hat Linux 9 Bible book I’ve got. Mine was running Apache 2.0.40. You can find out your current Apache version by typing

apachectl -v.

What needs to happen is that when a request comes in for a JSP page (or a servlet), Apache hands it over to Tomcat for processing. The mechanism for this hand-over is JK.

JK vs. JK2

JK is a bit confusing. From what I’ve read, a new refactored version of JK, called JK2, was developed but then went a bit stale. Meanwhile, development of the original JK continued apace, and this is now the recommended mechanism to use. Because of this, there are all sorts of contradictory instructions on the Web for setting up one or the other of these things.

Component version

I set up the following versions of the various components:

  • Apache 2.0.40 (rebuilt with ./configure --enable-so --enable-rule=SHARED_CORE)
  • Tomcat 5.5.9
  • jakarta-tomcat-connectors-1.2.13 (i.e. JK, built against the reconfigured Apache).

You may find it useful to know that these things play nicely together!

Configuration files

Once everything is installed, you should be able to use Apache and Tomcat independently.

If you create an index.html page in your domain’s httpdocs directory then

  • http://www.mydomain.com should cause Apache to serve up your static index.hmtl page
  • http://www.mydomain.com:8080 should cause Tomcat to generate and display a default page.

Directory structure

At first I intended to put all my JSP files directly into httpdocs. However, if you do this and the tomcat service breaks then Apache may well serve these pages up as plain text; this doesn’t seem very secure. Instead I decided to put all my JSP files in a parallel directory called jsp.

httpd.conf

First, a word of warning. The Apache on the original server was scattered all over, but when I rebuilt it I put it all in one place. This meant that there were two versions of Apache on the machine. Make sure that the correct one is running (which httpd and which apachectl — you may want to remap these). It’s no good changing the config files if the old executable is running and picking up its config files from a different place!

Append index.jsp to the DirectoryIndex entry, and then add the following block to the end:

LoadModule    jk_module  /usr/local/apache2/modules/mod_jk.so
JkWorkersFile /usr/local/apache2/conf/workers.properties
JkLogFile     /var/log/httpd/mod_jk.log
JkLogLevel    error
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
JkOptions     +ForwardKeySize +ForwardURICompat -ForwardDirectories
JkRequestLogFormat     "%w %V %T"
JkMount  /*.jsp ajp13
JkMount  /about/*.jsp ajp13
JkMount  /contact/*.jsp ajp13
JkMount  /editing/*.jsp ajp13
JkMount  /references/*.jsp ajp13
JkMount  /software/*.jsp ajp13
JkMount  /writing/*.jsp ajp13

workers.properties

This should be in the same directory as httpd.conf. This defines a single worker called ajp13.

workers.tomcat_home=/usr/local/jakarta-tomcat-5
workers.java_home=/usr/java/jdk1.5.0_04
ps=/
worker.list=ajp13
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13
worker.ajp13.lbfactor=1

server.xml

We need to modify this so that Tomcat listens to mod_jk.so.

Add this inside the main <Service …> tag:

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

<Listener
    className="org.apache.jk.config.ApacheConfig"
    configHome="/usr/local/jakarta-tomcat-5/"
    modJk="/usr/local/apache2/modules/mod_jk.so"
    jkWorker="ajp13"
    forwardAll="False"
    jkLog="/usr/local/jakarta-tomcat-5/logs/jk-tomcat5.log"
    jkDebug="debug"
    noRoot="False"
    workersConfig="/usr/local/apache2/conf/workers.properties" />

and this within the main <Engine …>:

<Host name="www.myhostname.com">
    <Context path="" docBase="/home/httpd/vhosts/myhostname.com/jsp" debug="1" reloadable="true"/>
</Host>

This sets the document base to the jsp parallel subdirectory.

Final thoughts

With this parallel directory scheme, for every subdirectory that you want to use you need to

  1. add a JkMount to httpd.conf
  2. add the directory and its file(s) to jsp
  3. (if you want automatic mapping to index.jsp) create an empty directory of the same name within httpdocs </ol> This third point is probably a good idea anyway, since you will need somewhere to put any static content that you want Apache to serve up directly.

    Achnowledgements

    I'd like to thank Paul Constantine and Alan Chandler for replying to my frantic post to the jakarta-tomcat-user mailing list. Paul's blog entry helped me over the final hurdle.