John Turner

last updated 12/18/2002

First, you need a sane build environment. In the open source world, that means GNU tools.

You’ll also need openssl and openssh installed. I’m assuming at this point that you have the following tools installed, GNU and otherwise:

• autoconf
• automake
• binutils
• gcc (I used version 2.95.3)
• glib
• gzip
• libtool
• make
• tar (make sure its GNU tar)
• wget
• zlib

Install all of the packages listed above. Note that you’ll need to install gzip first, as the other packages may be compressed.

Apache + Tomcat is five major steps: install JDK, build/install Apache, build/install Tomcat, build/install a connector, configure.
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.

Note: things in bold are typically Linux commands that would be entered at a command prompt.

Install JDK
=====================

1. go to java.sun.com and download J2SE for Linux: http://java.sun.com/j2se/1.4.1/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_1_01-linux-i586.bin.
2. Install the J2SE. I copied the bin file from the previous step to /usr/local/, then ran it with ./j2sdk-1_4_1_01-linux-i586.bin. This leaves /usr/local/j2sdk1.4.1_01.
3. Set JAVA_HOME as an environment variable, pointing to the location of the J2SE you just installed, in this case “/usr/local/j2sdk1.4.1_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/j2sdk1.4.1_01
   export JAVA_HOME

4. Verify that JAVA_HOME is set: echo $JAVA_HOME You should see the value “/usr/local/j2sdk1.4.1_01″ returned.

Build/Install APACHE
=====================

1. grab Apache source from a mirror. You want version 2.0.43. The filename is httpd-2.0.43.tar.gz.
2. unpack it. I like to put it in /usr/local/src/. This will leave you with /usr/local/src/httpd-2.0.43.
3. read /usr/local/src/httpd-2.0.43/INSTALL for installation detail
4. I’m going to put Apache 2.0.43 in /usr/local/apache2, which will leave me /usr/local/apache for Apache 1.3.x if needed. We’ll want SSL support (included in Apache 2.0.x), as well as DSO support. So, in /usr/local/src/httpd-2.0.43, setup the Apache build with: ./buildconf
5. Then, once the configure script has been tweaked, run it with: ./configure –prefix=/usr/local/apache2 –enable-ssl –enable-shared=so
6. when configure completes, run make.
7. when make completes, run make install.
8. You should now have an Apache instance in /usr/local/apache2. Verify config: /usr/local/apache2/bin/apachectl configtest
9. If you get a “Syntax OK” message, startup Apache: /usr/local/apache2/bin/apachectl start
10. Verify Apache is running: http://some.server.name or http://localhost. You should see the Apache welcome page
11. Shutdown Apache until you can get the connector installed: /usr/local/apache2/bin/apachectl stop

Build/Install TOMCAT
=====================

1. 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.
2. So, at a command prompt, as root, run: groupadd tomcat (this adds a group called tomcat to your system)
3. Next, run: useradd -g tomcat -c “Tomcat User” -s /bin/sh tomcat (this creates a user called ‘tomcat‘ in the group tomcat with a shell of /bin/sh
4. Next, run: passwd tomcat. Choose a password that you can type twice, but is difficult to guess or otherwise determine. Mixed case letters, a few numbers, and a special character or two is good. It doesn’t matter, because you needn’t log in as tomcat, ever. You can su to the tomcat user from root as needed. The reason for the tomcat user is so that you can startup Tomcat as user tomcat instead of user root.
5. Now, grab the Tomcat binary package for 4.1.18. Get it here:
   http://jakarta.apache.org/builds/jakarta-tomcat-4.0/archives/v4.1.18/bin/jakarta-tomcat-4.1.18.tar.gz
6. unpack it to /usr/local. You should end up with /usr/local/jakarta-tomcat-4.1.18
7. add a symbolic link for easy management: ln -s /usr/local/jakarta-tomcat-4.1.18 /usr/local/tomcat
8. set CATALINA_HOME as an environment variable, pointing to /usr/local/tomcat
9. startup Tomcat to test your installation: /usr/local/tomcat/bin/startup.sh. Verify the Tomcat examples are available
   at http://some.server.name:8080/examples

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, with JK2 to come later.

Building JK Connector
=======================

NOTE: you can get a JK binary for Linux here: http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.2/bin/. You are welcome to skip building JK from source and use the binary instead, but if you would rather build from source, here’s how to do it:

1. Grab the connector source from the Jakarta site:
   http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.2/src/jakarta-tomcat-connectors-jk-1.2.2-src.tar.gz
2. Unpack it to /usr/local/src/
3. From this point on, CONNECTOR_HOME = /usr/local/src/jakarta-tomcat-connectors-jk-1.2.2-src
4. cd CONNECTOR_HOME/jk/native.
5. run the configure script: ./configure –with-apxs=/usr/local/apache2/bin/apxs –with-java=${JAVA_HOME}
6. run make
7. the mod_jk.so file will be in CONNECTOR_HOME/jk/native/apache-2.0. Copy it to your Apache modules directory.

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. Edit server.xml in CATALINA_HOME/conf.
2. look for a line that says “Server” and has a port of 8005. Add the following directly below:

   <Listener className=”org.apache.ajp.tomcat4.config.ApacheConfig”
   modJk=”/usr/local/apache2/modules/mod_jk.so” />

3. in the Host container add the following Listener directive (yes, it looks very similar to the one above):

   <Listener className=”org.apache.ajp.tomcat4.config.ApacheConfig” append=”true” forwardAll=”false”
   modJk=”/usr/local/apache2/modules/mod_jk.so” />

4. change the name parameter in the Host directive to your apache ServerName (the default is localhost)
5. Edit httpd.conf in APACHE_HOME/conf.

   - make sure your ServerName matches the name=”" parameter in your tomcat Host element in server.xml

   - add the following line at the very end:

   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. 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. That file should look like this:
   

   # BEGIN workers.properties
   worker.list=ajp13
   worker.ajp13.port=8009
   # change this line to match apache ServerName and Host name in server.xml
   worker.ajp13.host=localhost
   worker.ajp13.type=ajp13
   # END workers.properties

7. Startup tomcat: $CATALINA_HOME/bin/startup.sh
8. Wait at least 10 seconds for tomcat to finish. Start apache: /usr/local/apache2/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 johnturner AT gmail 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.