Galatea
FlashGuideTM: Integrating Apache
2.0.36 and Tomcat 4.0.x on Windows

By Lajos Moczar
Last updated:
05/29/02

This
FlashGuideTM covers integrating Apache 2.0.36 and Tomcat 4.0.x on Windows. These
instructions have been tested using mod_jk on Windows 98 and XP. Thanks to Mark
Vlach for pointing me to a useful resource. You must use JDK 1.3.1 or greater
when building mod_jk for Tomcat.

There is a known
problem with Netscape 4.7.x, mod_jk and Apache 2.0. When access a Tomcat page
using Netscape 4.x, part of the page displays, the browser hangs, and eventually
displays "Document done" without showing the entire page. This is NOT fixed in
2.0.36, as I reported earlier.
Installing Apache 2.0
binary on Windows

1.

Download the Windows binary http://www.apache.org/dist/httpd/binaries/win32/apache_2.0.43-win32-x86-no_ssl.msi.
Be sure to read the notes at http://www.apache.org/dist/httpd/binaries/win32.
If you want to build your own, you'll have to wait for my forthcoming
FlashGuide explaining how.

2.

Install Apache by double-clicking on the downloaded file and
following the prompts

Installing Tomcat on
Windows

1.

Download Tomcat 4.0.5 at http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.0.5/bin/jakarta-tomcat-4.0.5.zip.
If you prefer, download Tomcat 4.1.12 instead from http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.1.12/bin/jakarta-tomcat-4.1.12.zip.

2.

Install Tomcat by unzipping/untaring the download file and placing
in the desired directory (I used c:\apps)

3.

Note the location of your Tomcat installation - we will refer to
this as %CATALINA_HOME%.

Installing the mod_jk
binary

Follow
these next four sections if you want to use mod_jk

1.

Download mod_jk at http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/win32.
Note that mod_jk.dll is different for Apache 1.3.x and Apache 2.0.x, so
you'll be looking for something like mod_jk-2.0.42.dll.

2.

Copy mod_jk-2.0.42.dll to %APACHE_HOME%\modules

Building jk
jars

Tomcat
4.0 does not include jars for the jk connectors, so you have to build your
own as described here.

1.

Download the tomcat connectors source from http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.0.3/src/jakarta-tomcat-connectors-4.0.2-01-src.zip.

2.

Unpack the distribution in the desired directory

3.

Make sure you have ant installed and %ANT_HOME% set. If not, follow
these steps:

a.

Download
ant from http://jakarta.apache.org/builds/jakarta-ant/release/v1.4.1/bin/jakarta-ant-1.4.1-bin.zip

b.

Unpack
the distribution in the desired directory

c.

Set
%ANT_HOME% in your environment to point to the ant
installation

4.

Cd to the jk directory

cd jakarta-tomcat-connectors-4.0.2-01-src\jk

5.

Edit build.properties as follows:

a.

Set
tomcat40.home to point to your Tomcat 4.0.x installation

b.

Set
apache2.home to point to your binary Apache 2.0 installation

c.

Comment
out tomcat33.home, tomcat41.home and iplanet.home, unless you need
them

d.

Your
build.properties should look something like this:

tomcat40.home=c:/apps/jakarta-tomcat-4.0.3
apache2.home=c:/progra~1/apache~1/apache2
apr.include=${apache2.home}/include
apr.lib=${apache2.home}/lib
so.debug=true
so.optimize=false
so.profile=false

6.

Now build and install the jars

ant
ant install

Building
mod_jk

1.

You can download a binary mod_jk.dll binary from http://www.acg-gmbh.de/mod_jk/.
If want to build your own, however, follow these instructions.

This
distribution also includes mod_webapp - feel free to experiment with
it!

2.

Download Apache 2.0.36 source at http://www.apache.org/dist/httpd/httpd-2.0.36.tar.gz

3.

Unpack the distribution into a development directory (I used
c:\devel)

The
distribution directory will be httpd_2.0.36

4.

Set %APACHE2_HOME% to point to the Apache source
distribution

5.

Make sure %JAVA_HOME% is set and pointing to your JDK
installation

6.

With Visual C++, open the
jakarta-tomcat-connectors-4.0.2-01-src\jk\native\apache-2.0\mod_jk.dsp
project

7.

Select the proper project (Release or Debug) and build mod_jk.dll

8.

Copy mod_jk.dll to the modules directory of your binary Apache
2.0.36 installation

Configuring
Tomcat

The
Listener tags are what causes Tomcat to automatically create the
conf/auto/mod_jk.conf file on startup. You can always write your own and
ignore this file.

1.

Edit %CATALINA_HOME%\conf\server.xml

a.

Add the
following lines immediately after the <Server port="8005" ...>
declaration:

<Listener className="org.apache.ajp.tomcat4.config.ApacheConfig"
modJk="c:/Program Files/Apache Group/Apache2/modules/mod_jk.dll" jkDebug="info"
workersConfig="c:/apps/jakarta-tomcat-4.0.3/conf/jk/workers.properties"
jkLog="c:/apps/jakarta-tomcat-4.0.3/logs/mod_jk.log"/>

Changes
the paths as appropriate. We need to specify the fully qualified paths for
workersConfig and jkLog because otherwise, mod_jk won't be able to find
them using the defaults. If you have a path for mod_jk.dll that includes
spaces, you will probably have to edit
%CATALINA_HOME%\conf\auto\mod_jk.conf after Tomcat starts up and add
quotes around the path. And yes, you'll have to do this every time Tomcat
starts up unless you want to make a static version of mod_jk.conf
somewhere else.

b.

Add the
following lines after the <Service name="Tomcat-Standalone">
declaration:

<!-- Define an AJP 1.3 Connector on port 8009 -->
<Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
port="8009" minProcessors="5" maxProcessors="75"
acceptCount="10" debug="0"/>

c.

Finally,
after any <Host name="localhost"> declarations, add a listener:

<Listener className="org.apache.ajp.tomcat4.config.ApacheConfig"
append="true" />

The
append attribute means to append to the existing conf/auto/mod_jk.conf
file

2.

Create a directory called "jk" under
$CATALINA_HOME/conf

3.

Add workers.properties to the jk directory - you can either use one
you have in a Tomcat 3.x installation, or copy this one (yes, I removed
all the comments):

workers.tomcat_home=c:/apps/jakarta-tomcat-4.0.3
workers.java_home=$(JAVA_HOME)
ps=\

worker.list=ajp13, ajp14
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13
worker.ajp13.lbfactor=1

worker.ajp14.port=8010
worker.ajp14.host=localhost
worker.ajp14.type=ajp14
worker.ajp14.secretkey=secret
worker.ajp14.credentials=myveryrandomentropy
worker.ajp14.lbfactor=1

worker.loadbalancer.type=lb
worker.loadbalancer.balanced_workers=ajp13
worker.inprocess.type=jni
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)tomcat.jar
worker.inprocess.cmd_line=start
worker.inprocess.jvm_lib=$(workers.java_home)$(ps)jre$(ps)bin$(ps)classic$(ps)jvm.dll
worker.inprocess.stdout=$(workers.tomcat_home)$(ps)logs$(ps)inprocess.stdout
worker.inprocess.stderr=$(workers.tomcat_home)$(ps)logs$(ps)inprocess.stderr

Naturally, you will take care to set workers.tomcat_home,
workers.java_home and worker.inprocess.jvm_lib as approriate for your
environment.

4.

Start or restart Tomcat. If everything worked correctly, you will
now have a mod_jk.conf file in %CATALINA_HOME%\conf\auto. If not, better
look over this section again ;)

Configuring
Apache

There are
two ways to do this: either simply include the auto-generated mod_jk.conf
file (first step) or manually put in all the jk directives in httpd.conf.
If you have a straight-forward Tomcat installation, do the former. If you
want finer grained control over what is available via mod_jk, or if your
webapps are not located in %CATALINA_HOME%\webapps, do the latter. A good
reason to use the latter method is if the path to mod_jk.dll has spaces in
it. If it does, you'll need to enclose the path as shown in mod_jk.conf in
double-quotes. This applies, for example, if you install Apache 2 in
"c:\Program Files\Apache Group\Apache".

1.

Option 1: edit httpd.conf to inclucde mod_jk.conf

a.

Add the
following lines to the end of the LoadModule section:

Include c:/apps/jakarta-tomcat-4.0.3/conf/auto/mod_jk.conf

Remember,
Tomcat (re)creates mod_jk.conf on every startup, so don't try to edit it!
You'll lose your changes on the next startup.

2.

Option 2: Hard-code the mod_jk directives in httpd.conf:

a.

Add the
following to the LoadModules section:

<IfModule !mod_jk.c>
LoadModule jk_module modules/mod_jk.dll
</IfModule>

b.

Add the
following to the end of httpd.conf:

JkWorkersFile "c/apps/jakarta-tomcat-4.0.3/conf/jk/workers.properties"
JkLogFile "c/apps/jakarta-tomcat-4.0.3/logs/mod_jk.log"

JkLogLevel debug

JkMount /examples ajp13
JkMount /examples/* ajp13

JkMount /jk ajp13
JkMount /jk/* ajp13

JkMount /cocoon ajp13
JkMount /cocoon/* ajp13

This is
all an example. You will have to set the paths for JkWorkersFile and
JkLogFile as approriate. You should make one entry for each webapp you
want to expose via mod_jk.

3.

Test httpd.conf by typing the following:

cd %APACHE_HOME%\bin
Apache

Testing

1.

Always start Tomcat first and then start Apache. If you have to
bounce Tomcat, remember to take down Apache first and restart it after
Tomcat restarts. mod_webapp is very sensitive that way. In fact, some
users have reported that it is necessary to put in 10 second delay between
starting Tomcat and Apache.

2.

If you set up a test to point to the "examples" web app in Tomcat,
first double-check "examples" in Tomcat: in your browser, type:
http://[host]:[port]/examples, where [port] refers to where you have
Tomcat running (usually 8080).

3.

Now try the URL that you defined in httpd.conf to point to
"examples": in your browser, type: http://[host]:[port]/examples, where
[port] refers to where you have Apache running. If you don't get anything,
try restarting Tomcat and then Apache.

©2001-2002 Galatea Information Strategies. All rights
reserved