JSP on Windows: Apache 2, Tomcat 4.1, JK 2

Introduction

This document describes how to set up a working JSP system that connects to Apache on Windows (I'm working on 2K). This system lets you process JSP files that are in the ordinary Web server folders as well as use specific Web applications.

The system created is a simple one that handles only a single host, not virtual hosts (although if you know about virtual hosts maybe you can extend it). We are using Apache 2.0.48, JK 2.0.43, and Tomcat 4.1.29 (the current versions at time of first writing).

Important: all other documents describing this process are wrong. They miss out vital configuration steps. You're going to spend all day tearing your hair out if you believe them, so don't do that, that's what I just did. Also, don't bother looking at Apache's docs on this subject - unless they rewrote them since, they're utterly worthless.

Also important: I make no guarantees about security implications (or whether this actually works for that matter; hey, most likely this document is wrong too). And this document doesn't cover other versions of the software, like Apache 1 for example.

Really really important: Under no circumstances contact me asking for help configuring your software. Don't email me about that. I don't know shit about server configuration. If it doesn't work, ask somebody who does, not me. (On the other hand, if you are somebody who knows about server configuration and you notice anything hideously wrong in here, let me know, maybe I'll fix it, thanks.)

Thanks to Eric Barr for pointing out an omission in the previous version of this text.

Basic installation

• Set up Apache 2.0.48 if it isn't already installed. Configure it how you like. (This document doesn't cover Apache configuration.) You can get Apache from httpd.apache.org.
  
• Make sure Apache is working by retrieving a webpage from http://localhost/.
  
• Install Sun's Java JDK 1.4.2 or similar version, if not already installed. You can get Java from java.sun.com. (You do need the JDK and not just a JRE.)
• Set an environment variable JAVA_HOME to point to the JDK directory. (I missed out this step before, but somebody emailed to tell me it's necessary; the Tomcat documentation mentions it.) If you're not sure how to do this, there are instructions here.
  
• Install Apache Tomcat 4.1.29 (these instructions may also work with version 5). You can get it from jakarta.apache.org. When installing, Tomcat should tell you it is using the JDK you just installed. Turn on the NT service option during install so that Tomcat runs as a service (this isn't default!).
  
• Make sure Tomcat is working by retrieving http://localhost:8080/.
  

Remember the directories you used to install Apache and Tomcat in. I'm going to call those <APACHE> and <TOMCAT>.

• Download the JK2 connector. Again, this comes from jakarta.apache.org. Make sure to get the version for Apache 2 servers. This comes as just a .zip file with a .dll (mod_jk2-2.0.43.dll) in it. Copy this DLL into <APACHE>/modules. (The other files in there are all called .so and yours is a DLL - don't sweat it, this is right.)
  

Set up Tomcat

Edit server.xml

Begin by editing the file <TOMCAT>/conf/server.xml. You might want to make a backup first.

Required task

First thing is to make sure Tomcat is looking in the same place as Apache for your JSP files. Otherwise it ain't gonna find them, even if Apache does pass on the request. (If you only want to use Tomcat web applications and don't need JSP files processed inside your Apache folders, then you can skip this step.)

• Find the line beginning <Context path="/examples"...
• Add the following:
  <Context path="" docBase="<APACHE>/htdocs"
                  debug="0" reloadable="true" crossContext="true"/>
  

(Obviously, if you changed your Apache document root from the default, use that instead.)

Optional tasks

• Near the top you should see a Connector tag described as 'non-SSL Coyote HTTP/1.1 connector'. This is the one that makes Tomcat listen on port 8080. You don't want to do that since requests are going to come from Apache, so comment that whole tag out.
• Comment out all of the <Context path="/examples">; be careful, you need to get the whole thing all the way down to the </Context> and there are nested comments. Of course, if you actually want the examples, don't do this.
  

Set up Apache

Edit workers2.properties

You're probably thinking, huh? my Apache doesn't have one of those files. Well, it doesn't yet, but you're going to make one.

• Create the file workers2.properties in <APACHE>/conf.
• The file contents should be as follows:
  # Doesn't work without this (I don't know why)
[shm]
file=<APACHE>/logs/shm.file
size=1048576

# Example socket channel, override port and host.
[channel.socket:localhost:8009]
port=8009
host=127.0.0.1

# define the worker
[ajp13:localhost:8009]
channel=channel.socket:localhost:8009

Edit httpd.conf

Finally, a file you've actually heard of! Add this to httpd.conf (e.g. at the end):

LoadModule jk2_module modules/mod_jk2-2.0.43.dll

<Location "/*.jsp">
  JkUriSet worker ajp13:localhost:8009
</Location>

<Location "/tomcat-docs">
  JkUriSet worker ajp13:localhost:8009
</Location>

You can probably see that this causes all files ending .jsp, and anything beginning with /tomcat-docs (you can get rid of that one if you like, it's just an example), to be processed by Tomcat instead of Apache.

Any webapps (like tomcat-docs) will come from within the Tomcat webapps folder, but all your JSP files can be placed inside the normal Apache root.

If you want to make other URIs be processed by Tomcat, you can just add them in the same way. Hopefully it's obvious how - and because this goes in httpd.conf you don't have to remember some other bizarre configuration file when you're making changes.

Restart services

You'll need to use the Services control panel.

• Restart Tomcat
• Restart Apache
  

Rumours suggest you should wait a few seconds between these, but I don't think it matters any more (maybe it once did).

Test!

Webapp test

Make sure Tomcat webapps still work by accessing http://localhost/tomcat-docs/ - you should find that this works, even though you accessed it via Apache (port 80) and the files are within Tomcat's webapps folder. That's because it's configured to pass on the request in httpd.conf.

JSP file test

Within your Apache documents tree, create a file test.jsp:

<%= new java.util.Date() %>

Request http://localhost/test.jsp and you should see (after a pause, first time round) the current date. Woo! Again, that's because *.jsp is configured to pass on the request, in httpd.conf.

End

That's all for now folks!