Building an Apache HTTP + Tomcat environment is five major steps:

  1. install JDK
  2. build/install Apache
  3. build/install Tomcat
  4. build/install a connector, in this case JK
  5. configure and test

Since Tomcat is 100% Java, we'll use the binary install instead of having to deal with ant. My preference is to put things in /usr/local. Use whichever location suits your purposes. Paths, in this scenario, don't have much effect as long as you can guarantee that they are consistent throughout the various configuration steps.

Assumptions

  1. Red Hat RPMs are not used. This is my personal preference as an admin. If you would rather do this with RPMs, you might have a look at Mike Millson's HOWTO.
  2. Mod_jk is used as the Apache connector. For the same tutorial using mod_jk2 instead, check my JK2 HOWTO. (coming soon)
  3. You don't want multiple virtual hosts. If you want to have multiple virtual hosts, that is, more/other than http://localhost, check out my Virtual Hosting HOWTO. (coming soon)
  4. You are root. If you aren't, find someone who is or skip this HOWTO entirely and use Tomcat by itself.

Install JDK

  1. go to Sun's Java download site and download J2SE for Linux: http://java.sun.com/j2se/1.4.2/download.html. I prefer the SDK version, and I prefer the non-RPM version. From here on out, I will assume that you've got the SDK version, and aren't using any RPMs. The file you will have will be called j2sdk-1_4_2_01-linux-i586.bin.
  2. Install the J2SDK. I copied the .bin file from the previous step to /usr/local/, then ran it:
    cp -p j2sdk-1_4_2_01-linux-i586.bin /usr/local/
    ./j2sdk-1_4_2_01-linux-i586.bin
    This leaves /usr/local/j2sdk-1_4_2_01.
  3. Set JAVA_HOME as an environment variable, pointing to the location of the J2SDK you just installed, in this case /usr/local/j2sdk-1_4_2_01. If you want this environment variable to be available to every user system-wide, then put the following two lines into /etc/profile:
    JAVA_HOME=/usr/local/j2sdk-1_4_2_01
    export JAVA_HOME
  4. Verify that JAVA_HOME is set:
    echo $JAVA_HOME
    You should see the value /usr/local/j2sdk-1_4_2_01 returned. If you don't, go back through the steps until JAVA_HOME resolves to the correct value.

Build/Install Apache HTTP

  1. Download the Apache source code from a mirror. You want version 2.0.47. The filename is httpd-2.0.47.tar.gz.
  2. Unpack the distribution. I like to put it in /usr/local/src/.
    cp -p httpd-2.0.47.tar.gz /usr/local/src/
    cd /usr/local/src
    tar xvzf httpd-2.0.47.tar.gz
    This will leave you with /usr/local/src/httpd-2.0.47.
  3. Read /usr/local/src/httpd-2.0.47/INSTALL for installation detail.
  4. I'm going to put Apache 2.0.47 in /usr/local/apache. We'll want SSL support (included in Apache 2.0), as well as DSO support. So, in /usr/local/src/httpd-2.0.47, setup the Apache build:
    cd /usr/local/src/httpd-2.0.47
    ./configure --prefix=/usr/local/apache --enable-ssl --enable-so
  5. When configure completes, compile Apache and install it:
    make
    make install
  6. You should now have an Apache instance in /usr/local/apache. Verify config:
    /usr/local/apache/bin/apachectl configtest
  7. If you get a Syntax OK message, startup Apache:
    /usr/local/apache/bin/apachectl start
  8. Verify Apache is running with http://localhost. You should see the Apache welcome page. If you're installing Apache remotely, you should be able to check http://IP_ADDRESS where IP_ADDRESS is the address of the machine where Apache is installed.
  9. Shutdown Apache until you can get the connector installed:
    /usr/local/apache/bin/apachectl stop

Build/Install Tomcat

It's generally a bad idea to run Tomcat (or any web service) as root. If you don't care about that, you can skip the next few steps. I happen to prefer running web services under non-root user accounts, so I like to setup a user named tomcat before installing/running Tomcat.
  1. At a command prompt:
    groupadd tomcat
    useradd -g tomcat -c "Tomcat User" -d /usr/local/tomcat tomcat
    passwd tomcat
    This adds a group called tomcat to your system, a user called tomcat to your system, and changes the password for the tomcat user (set the password to whatever you like...make it good!). It also sets the home directory for the tomcat user to /usr/local/tomcat (more on that later).
  2. Now, grab the Tomcat binary package for 4.1.27 from a mirror site. The filename is tomcat-4.1.27.tar.gz
  3. Unpack it to /usr/local:
    cp -p tomcat-4.1.27.tar.gz /usr/local/
    cd /usr/local
    tar xvzf tomcat-4.1.27.tar.gz
    You should end up with /usr/local/jakarta-tomcat-4.1.27.
  4. Add a symbolic link for easy management:
    ln -s /usr/local/jakarta-tomcat-4.1.27 /usr/local/tomcat
    This way, you can install various versions of Tomcat and control which version is linked to /usr/local/tomcat. This makes upgrades easier.
  5. Next, set the ownership of the Tomcat directories:
    chown tomcat:tomcat /usr/local/tomcat
    chown -R tomcat:tomcat /usr/local/jakarta-tomcat-4.1.27
  6. Set CATALINA_HOME as an environment variable, pointing to /usr/local/tomcat. If you want this environment variable to be available to every user system-wide, then put the following two lines into /etc/profile:
    CATALINA_HOME=/usr/local/tomcat
    export CATALINA_HOME
  7. Verify that CATALINA_HOME is set:
    echo $CATALINA_HOME
    You should see the value /usr/local/tomcat returned. If you don't, go back through the steps until CATALINA_HOME resolves to the correct value.
  8. Startup Tomcat to test your installation:
    su - tomcat -c /usr/local/tomcat/bin/startup.sh
    Verify the Tomcat examples are available at http://localhost:8080/examples. If you're installing Tomcat remotely, you should be able to check http://IP_ADDRESS:8080/examples where IP_ADDRESS is the address of the machine where Tomcat is installed.
  9. Shutdown Tomcat until you can get the connector installed:
    su - tomcat -c /usr/local/tomcat/bin/shutdown.sh

Build/Install Connector

The two connectors (JK and JK2) are different; JK2 is a complete rewrite of the earlier JK/AJP13 protocol. We'll cover building JK here. For JK2, check out my JK2 HOWTO.
  1. Download the connector source in tar.gz format from the Jakarta site. The file will be called jakarta-tomcat-connectors-jk-1.2-src-current.tar.gz:
  2. Unpack it to /usr/local/src:
    cd /usr/local/src
    tar xvzf jakarta-tomcat-connectors-jk-1.2-src-current.tar.gz
    This will leave you with /usr/local/src/jakarta-tomcat-connectors-jk-1.2.5-src.
  3. From this point on, CONNECTOR_HOME = /usr/local/src/jakarta-tomcat-connectors-jk-1.2.5-src
  4. Change to the native directory, run the configure script, and build the connector:
    cd CONNECTOR_HOME/jk/native
    ./buildconf.sh
    ./configure --with-apxs=/usr/local/apache/bin/apxs
    make
    make install
    This will compile mod_jk.so and copy it to /usr/local/apache/modules. If mod_jk.so isn't in the Apache modules directory, look in CONNECTOR_HOME/jk/native/apache-2.0 or use the find command to find it:
    find / -name mod_jk.so -print
    If you find it someplace other than /usr/local/apache/modules (you shouldn't if you've followed the commands as shown), copy it to /usr/local/apache/modules. Make sure the permissions are 755.

Final Configuration

NOTE: these steps will allow access to the Tomcat examples via Apache on port 80. Successful use of the examples on port 80 shows that mod_jk is working correctly, since Tomcat is configured to run on port 8080 by default for HTTP requests.
  1. You're going to be making edits to a file called server.xml in Tomcat's conf directory. This file is vital to Tomcat operation, so it is a good idea to make a copy before it gets modified:
    cd $CATALINA_HOME/conf
    cp -p server.xml server.xml.ORIG
    Now you've got a safe copy of server.xml as server.xml.ORIG. Worst case, you can copy it back and start over if something gets messed up.
  2. Now, let's edit server.xml in CATALINA_HOME/conf:
    cd $CATALINA_HOME/conf
    vi server.xml
  3. Look for a line that says "Server" and has a port of 8005. Add the following directly below:
  4. In the Host container add the following Listener directive (yes, it looks very similar to the one above):
    Save your changes and exit the editor.
  5. Now, we need to make a small edit to Apache's httpd.conf. Edit httpd.conf in APACHE_HOME/conf. Don't worry about making a copy, the Apache team put one there for you already (it's called httpd-std.conf):
    cd /usr/local/apache/conf
    vi httpd.conf
    Add a single line at the end of the file:
    Include /usr/local/tomcat/conf/auto/mod_jk.conf
    Note: the mod_jk.conf file gets created by Tomcat when Tomcat starts. It gets created every time Tomcat starts. So, if you have your server.xml configured, you can ignore httpd.conf (in most cases) except to add the Include directive for mod_jk.conf. You don't need to create or edit mod_jk.conf, Tomcat will do this for you. Click here for a sample mod_jk.conf file generated automatically by Tomcat on each startup.
  6. Create a file in CATALINA_HOME/conf/jk called workers.properties:
    cd $CATALINA_HOME/conf
    mkdir jk
    chown tomcat:tomcat jk
    cd jk
    vi workers.properties
    In that file, put the following lines:
    worker.list=ajp13
    worker.ajp13.port=8009
    worker.ajp13.host=localhost
    worker.ajp13.type=ajp13
    Save the file. chown the file:
    chown tomcat:tomcat workers.properties
    This file provides necessary information to mod_jk, like where to find Tomcat and what port to use when connecting.
  7. Start Tomcat:
    su - tomcat -c /usr/local/tomcat/bin/startup.sh
    Wait at least 30 seconds for tomcat to complete the startup process. Verify that you have a file called usr/local/tomcat/conf/auto/mod_jk.conf and that the timestamp on that file is recent before going to the next step.
  8. Start apache:
    /usr/local/apache/bin/apachectl start
  9. Verify examples at http://localhost:8080/examples. On success, Tomcat is working correctly.
  10. Verify examples at http://localhost/examples. On success, Apache is working correctly, and JSP and servlet requests are being passed to Tomcat.

Please send comments, suggestions, or changes to john AT johnturner DOT com. Be advised that I will be happy to help where I can, but I am not available for free one-on-one tech support to the whole world. :)