Author: Jeff Peterson - jeff /at\ coded \dot/ com
Date: 10/08/2004
Version: 1.1
(c) 2004 All Rights Reserved

*******************************************************************************
** This document is provided for information purposes only.  The author      **
** does not provide any warranty or guarantee of fitness and expressly       **
** disclaims all liability.  Perform all actions AT YOUR OWN RISK!           **
*******************************************************************************


Table of Contents
      1. Introduction
      2. Installing Java
	 a. Getting Java
	 b. Installing Sun Java
	 c. Preparing Dummy Packages (Woody)
	 d. Preparing Dummy Packages (Sarge / Sid)
	 e. Building and Installing Dummy Packages
      3. Installing Tomcat4
      4. Connecting Tomcat4 with Apache
	 a. Installing Mod-JK Connector
	 b. Configuring Apache
	 c. Configuring Tomcat4
	 d. Testing the Connector
      5. A Note About Development Servers
      6. Revision History
      

1. Introduction

This how-to describes the process involved for installing Java and Tomcat 4.  Additionally, it details how to configure Apache to forward all Java-related (think JSP,etc) requests to Tomcat.

At last check, Debian has several antique versions of Java available.  For licensing reasons, Sun's implementation is not available.  This document will cover the steps necessary to seamlessly run Sun's implementation of Java on Debian.

At the time of writing, this document applies to Debian Woody and Sid.  I have not tested it on Sarge but I would expect it to work.

This document assumes that you already have Apache installed and functioning.

2. Installing Java (source: http://wiki.osuosl.org/display/DEV/Java+on+Debian)

2.a. Getting Java

First step to installing Java is getting Java.  For this we will use the Sun Java J2SE SDK.  It is available through java.sun.com or more specifically, http://java.sun.com/j2se/downloads/index.html.  I recommend to get the JDK for the most recent version but you may choose your favorite version >= 1.3.

2.b. Installing Sun Java

Once downloaded, make the JDK .bin file executable and then execute it.  Accept the License.  Watch as it extracts itself.

Move the extracted folder (jdk1.x.x) to /usr/local/lib/.  This will probably require root privileges.

Create a symlink:
# ln -s /usr/local/lib/jdk1.x.x and /usr/local/lib/jdk.

I also like to have the following symlink:
# ln -s /usr/local/lib/jdk1.x.x /usr/local/java.

Set the privileges on /usr/local/lib/jdk1.x.x to your liking.  I recommend
# chown -R root:src jdk1.x.x

Now we need to setup the environment so that java functions properly. Edit /etc/profile with your favorite text editor.

Add the following lines:

# Java stuff
export JAVA_HOME="/usr/local/lib/jdk"
export CLASSPATH=".:${JAVA_HOME}/jre/lib"
export JDK_HOME="{$JAVA_HOME}"
export PATH="{$JAVA_HOME}/bin:${PATH}"

This will add the Java binaries to the path and setup several other variables which are helpful.

2.c. Preparing Dummy Packages (Woody)

To get the Java packages recognized on Debain Woody is a bit more tricky.  For Sarge and Sid, see below.

First of all we need to backport the java-common package from testing to stable.

This can be done simple enough by changing your /etc/apt/sources.list file.
Comment out all existing lines and add the following

deb http://mirrors.kernel.org/debian/ testing main non-free contrib

Update your sources
# apt-get update

# Install the java-common package
apt-get install java-common

Return your /etc/apt/sources.list to its original condition and re-update your sources
# apt-get update

Install some other packages that we are going to need
# apt-get install kaffe equivs


2.d. Preparing Dummy Packages (Sarge / Sid)

In order for Debian to recognize that Java is installed we need to jump through a couple hoops.  This process will satisfy the dependencies that certain programs have on Java without using Debian's antique versions of Java.

In order to do this we are going to need to install a few debian packages (as root).
# apt-get update
# apt-get install install kaffe equivs java-common java2-common


2.e. Building and Installing Dummy Packages

Make yourself a temporary directory to build the dummy packages in.
# mkdir /usr/src/java
# cd /usr/src/java

Copy the dummy package control files to the temp folder and build them.  For your convenience, the packages are available already compiled in the src/ directory of this document.
# cp /usr/share/doc/java-common/dummy-packages/*.control .
# equivs-build java-compiler-dummy.control
# equivs-build java-virtual-machine-dummy.control
# equivs-build java1-runtime-dummy.control
# equivs-build java2-runtime-dummy.control
# equivs-build java2-compiler-dummy.control

Now install the packages
# dpkg -i java*.deb

The next step is to tell Debian to use the new JDK.  This is done with the update-alternatives command.  There are a lot of commands so a script has been provided.  Please see src/update-java-defaults.sh

The last thing to do is verify that Java is working.  As root,
# java -version

This will create the system preference directories and verify that java is working.

Now Java is installed to Debian's satisfaction.


3. Installing Tomcat4

Under Debian the process for installing Tomcat4 is very strait-forward.  I highly recommend using Tocat4 as opposed to other versions of Tomcat available.

To install Tomcat4 do the following:
# apt-get install tomcat4 tomcat4-webapps

Some additional packages will likely be automatically installed. Simple Huh?

Next lets configure Tomcat to use the Sun Java implementation.  To do this, edit the file /etc/default/tomcat4.  Set JAVA_HOME to /usr/local/lib/jdk. Done.

Restart Tomcat
# /etc/init.d/tomcat4 restart

We should now be able to test the tomcat installation.  Open up a web browser and go to:

http://tomcat-server:8180

where tomcat-server is the machine running you just installed tomcat on.  Make sure that the JSP and Servlet Examples work.  Now we are ready to move on.

4. Connecting Tomcat with Apache

The next step is to provide seamless integration of tomcat into apache.  It would be rather annoying for every customer to have to go to mydomain.com:8180.  At the same time we don't want Tomcat to be serving non-java-based pages.  This is because Apache is much faster and better at it.

The general approach is to use a connector between Apache and Tomcat which will allow Apache to dispatch JSP and Servlet requests to Tomcat for processing.  At the same time, all non-Java-based pages will be handled by Apache.

4.a. Installing Mod-JK Connector

The first thing to do is install the Apache<->Tomcat connector
# apt-get install libapache-mod-jk

I recommend not having the httpd.conf configuration file auto-updated.  It is prone to errors.


4.b. Configuring Apache

Edit /etc/apache/httpd.conf. Add the following line in the appropriate section.

LoadModule jk_module /usr/lib/apache/1.3/mod_jk.so

Add the virtual host(s) which will need JSP/Servlet support.  To do this, add the following lines, customizing as necessary.

<VirtualHost my.domain.name>
    ServerName my.domain.name
    ServerAlias www.my.domain.name
    DocumentRoot /home/www/my.domain.name/htdocs

    JkMount /*.jsp ajp13
    JkMount /resolver ajp13
    JkMount /status ajp13

    <Location "/WEB-INF">
        AllowOverride None
        deny from all
    </Location>

</VirtualHost>


4.c. Configuring Tomcat4

Edit /etc/tomcat/jk/workers.properties. Update the following properties:

workers.tomcat_home=/usr/share/tomcat4
workers.java_home=/usr/local/lib/jdk
worker.list=ajp13

Edit the /etc/tomcat4/server.xml file to add support for your virtual hosts in apache and enable the AJP connector.

Add the following lines after '</Host>'.  Customize as necessary.

<Host name="my.domain.name">
  <Context path="" docBase="/home/www/my.domain.name/htdocs" debug="0" />
</Host>

Uncomment the AJP 1.3 Connector
    <Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
               port="8009" minProcessors="5" maxProcessors="75"
               acceptCount="10" debug="0" address="127.0.0.1"/>


Restart Apache and Tomcat
# /etc/init.d/apache restart
# /etc/init.d/tomcat4 restart

4.d. Testing the Connector

Create a file called date.jsp in your website's document root.  Its contents are as follows:

<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTM 4.0 Final//EN">
<HTML>
<HEAD>
<TITLE>Current Date</TITLE>
</HEAD>
<BODY>

The current date is:
<% out.println(new java.util.Date()); %>

</BODY>
</HTML>

Now go to http://my.domain.name:8180/date.jsp.  You should see output to the effect of "The current date is: <date>".  This is good.  This means that Tomcat4 is functioning properly.

Now go to http://my.domain.name/date.jsp.  You should see the same thing as before.  This means that apache is correctly using the connector and everything is good to go.

If you see an "Internal Server Error" page it is because you missed one of the configuration options for the Apache<->Tomcat connector.  Go back and recheck things.

5. A Note About Development Servers

Tomcat has this nasty habit of caching your servlet class files.  Normally this is a good thing.  It improves performance considerably.  However, it can really get in the way of things during development.  You don't want to have to restart tomcat each time you change one of your classes.

The workaround for this is as follows:

Add 'reloadable="true"' to your sites' <Host> tag in /etc/tomcat4/server.xml

Alternatively, you can add '<DefaultContext reloadable="true" />' inside the the <Engine> context.  This will make it apply to all virtual hosts.

6. Revision History

1.0 - 10/08/2004 - Initial Release
1.1 – 07/14/2005 – Fixed Typo's