Configuring Tomcat5 and Apache2 with Virtual Hosts using mod_jk

Version 1.0

Author: C. Troy Popplewell

Visit the forums at .

Last edited: 02/10/2006


This tutorial explains how I was able to setup a web server in order to support Java Server Pages (JSP) and Servlets using virtually hosted websites. Although this setup worked for this particular environment, I can make no guarantees that it will work for yours, but it should with some tweaking. I’ll explain later on. I have spent a lot of time gathering several resources in order to get this to work. Many portions of these resources have been deprecated and required a few workarounds. It is my intention that this tutorial will help anyone that has attempted to install such a system without success. If you find any inconsistencies within this tutorial, please notify me at the email address above.


The ultimate goal is to provide instructions on how to incorporate JSP/Servlet support on the ISPConfig web hosting software. I felt it was necessary to provide this first segment separately for those that do not wish to use the ISPConfig web hosting control panel.

System Details

The system used in this tutorial has the following installed:

Operating System: Debian Sarge (3.1)

Webserver: Apache 2.0.54

JDK: JDK 5.0

Servlet Container: Tomcat

Tomcat Connector: Jakarta Tomcat Connector mod_jk (not mod_jk2)

Debian Sarge (3.1)

If you plan on utilizing ISPConfig to host your websites with Debian Sarge, I highly recommend the how-to provided by Falko Timme here: The Perfect Setup - Debian Sarge (3.1) which prepares your system to support ISPConfig. There are “Perfect Setup� tutorials for other distributions as well. Otherwise, you should be able to find many other resources on the internet for installing Debian. This tutorial is specifically based on configuring Apache and Tomcat to work on Debian using the mod_jk connector.


Since installing Apache is beyond the scope of this tutorial, I will assume that you already have Apache 2.0.x installed and running. If you need instructions on installing and configuring Apache 2.0.x please refer to the documentation at the Apache website. Again, you can also find instruction here: The Perfect Setup - Debian Sarge (3.1).

Installing JDK (Java Development Kit)

In order to run Tomcat, you will need to install JDK and set the JAVA_HOME environment variable to identify the location of the JDK environment on your system. I have chosen to use JDK 5.0.

  1. You can download JDK 5.0 at

  1. Click on Download JDK 5.0 Update 6 to go to the download page.

  1. Click Accept to accept the license agreement.

  1. Next choose the Linux self-extracting file. This is the download for the self-extracting binary file rather than the rpm.

  1. Download to your preferred download directory. Change to that directory and make it executable by executing the following command:

chmod +x jdk-1_5_0_06-linux-i586.bin

  1. Now execute the file:


  1. You should now have a new directory called j2sdk1.5-sun. Now move this directory to the location where it should be run. I chose /usr/lib/.

mv j2sdk1.5-sun /usr/lib

  1. Now create a symbolic link called jdk to JAVA_HOME by the following command. This allows you to easily switch back and forth between different jvms should you ever need to

cd /usr/lib

ln -s j2sdk1.5-sun jdk

  1. Now we need to set the JAVA_HOME environment variable. Add the following at the end of /etc/profile just after export PATH.


export JAVA_HOME

/etc/profile is executed at startup and when a user logs into the system. In order to update the environment you will need to log out and log back in to the system.

  1. Check to make sure JAVA_HOME is defined correctly by executing the command below. This should report the location of the Java SDK which should be /usr/lib/jdk.


  1. Now test Java with the following command. You should be returned with /usr/bin/java. If so, you have successfully completed this section.

which java

Installing Tomcat

In this section you will download and install Apache Tomcat 5.5.15. For this particular setup, there is no need to build the package from source, we will download the binary version.

  1. Download the binary version to your preferred download directory from here: Choose the tar.gz from the core section for 5.5.15.

  1. Now change to that directory and extract the files using the following command:

cd /mydownloads (be sure to change to your download directory)

tar xvzf apache-tomcat-5.5.15.tar.gz

  1. You should now have a new directory called apache-tomcat-5.5.15. Now move this directory to the location where it should be installed. Again, I chose /usr/lib/. Note that this location will be referred to as CATALINA_HOME in the Tomcat documentation.

mv apache-tomcat-5.5.15 /usr/lib

  1. Next change to the /usr/lib/ directory.

cd /usr/lib

  1. Now create a symbolic link called apache-tomcat to CATALINA_HOME by the following command.

ln -s apache-tomcat-5.5.15 apache-tomcat

This will save you from having to make changes to startup and shutdown scripts each time you upgrade Tomcat and if you so desire, it also allows you to keep several versions of Tomcat on your system and easily switch amongst them.

  1. You should now be able to start and stop Tomcat from the CATALINA_HOME/bin directory. If you are using another shell other than the bash shell you will nee to add sh to the beginning of the command. You should now be able to test that Tomcat is installed by starting it and opening your browser and entering http://localhost:8080 into your browser. Port 8080 is the default port for Tomcat and can be easily changed in the /usr/lib/apache-tomcat/conf/server.xml file. (We will work with this file later on.) If you plan to access this page remotely, be sure to forward the respective port to your server’s IP address within your router. You should now see the Tomcat welcome page that contains links to Tomcat documentation as well as sample JSP/Servlet scripts. Verify that Tomcat is running by executing some of the examples found on the welcome page.

cd /usr/lib/apache-tomcat/bin


To shutdown the server, you will need to execute the following command. Feel free to try it, but for now we will leave Tomcat running.


Share this page:

Suggested articles

9 Comment(s)

Add comment


By: Anonymous

Great article! It will be very helpful for those people using Apache and tomcat to handle JSP etc.

The newly released Apache server 2.2 includes AJP Proxy support by default and other new features, I haven't tried it, but I think it should ease the configuration bridging apache and tomcat using the jk module. maybe you can look into it and give us another wonderful HOWTO :)

thank you!

By: lwpro2

for me, the easy to overlook part is that, apache forward the request to tomcat ajp1.3 connector port 8009(by default), not the container service port 8080(most of the time).

 so should be carefully as,



By: Anonymous

The "Debian-way" of using the JVM would be to convert it to an deb first. This is very simple

apt-get install mpkg-j2sdk

Then simply

mpkg-j2sdk jdk-1_5_0_06-linux-i586.bin

afterwards you can install the correspondig deb by doing a

dpkg -i jdk...deb

By: Anonymous

- JDK is not a requirement anymore, you only need JRE. From Tomcat web site:

"Tomcat 5.5 uses the Eclipse JDT Java compiler for compiling JSP pages. This means you no longer need to have the complete Java Development Kit (JDK) to run Tomcat, but a Java Runtime Environment (JRE) is sufficient. The Eclipse JDT Java compiler is bundled with the binary Tomcat distributions."

- One other thing that you should add in your howto is to configure Tomcat to run as a non-root user. The default is to run as root which is not secure, should tomcat be compromised, and not required, as tomcat listen to port 8080. You will find below an example of init.d file.





# tomcat This shell script takes care of starting and stopping

# tomcat.

# description: tomcat is a servlet/JSP engine, which can be used

# standalone or in conjunction with Apache


# Provides: Tomcat

# Required-Start: $local_fs $network $remote_fs apache2

# Required-Stop: $local_fs $network $remote_fs apache2

# Default-Start: 3 5

# Default-Stop: 0 1 2 6

# Short-Description: Tomcat

# Description: Tomcat



# See how we were called.

case "$1" in


# Start daemons.

echo -n "Starting tomcat: "

cd ~tomcat

su - tomcat -c '/opt/jakarta/tomcat/bin/ start'


[ $RETVAL -eq 0 ] && touch /var/lock/subsys/tomcat




# Stop daemons.

echo -n "Shutting down tomcat: "

cd ~tomcat

su - tomcat -c '/opt/jakarta/tomcat/bin/ stop'


[ $RETVAL -eq 0 ] && rm -f /var/lock/subsys/tomcat




$0 stop

$0 start




echo "Usage: tomcat {start|stop|restart}"

exit 1


exit $RETVAL

By: Anonymous

I appreciate your efforts and that you share your work with others.

But if you use Debian why don't you do things the Debian way and reduce your howto to around 5 "apt-get install" statements and a reference to /usr/share/doc/libapache2-mod-jk?


jan (yeah (ät) yeahrock (dot) de)

By: Anonymous

mod_jk has a bevy of options that should, in general, be set in in order to tune the connection to Apache as well as Tomcat. By default it's pretty wide open as far as connections and timeouts are concerned; it's very easy for Apache to accept way, way way more load than Tomcat sitting behind it can handle. Here are some of the important ones I've found and what I typically set them to, the actual reading of the docs is left up to you. :)

# Specify the size of the open connection cache.
# below are in seconds

# Advanced ping-pong options
# 0 (full recovery)
# 1 (don't recover if tomcat failed after getting the request)
# 2 (don't recover if tomcat failed after sending the headers to client)
# 3 (don't recover if tomcat failed getting the request or after sending
# the headers to client).
# below are in milliseconds
# under load it can take awhile to get a reply when doing an initial JSP compile

By: noota

great article, man! helped me a lot and the best thing is that it actually works)


Thank you for the very good article. Besides the valuable configuration hints you are providing I took benefit from the advanced worker properties posted by Anonymous on Mon, 2006-03-06 21:59.

 I want to add that for "heavy" load on the tomcat workers it can be necessary to increase to maximum amount of threads. I specifiied that in each of the server.xml of my tomcats

  enableLookups="false" redirectPort="8443" protocol="AJP/1.3"
  useBodyEncodingForURI="false" URIEncoding="UTF-8"
  maxThreads="350" minSpareThreads="25" maxSpareThreads="75" />
-Toddy (info (the-at) tinyimage (the-dot) com)

By: atc