Luminas Technology: Servlet engines: Tomcat quick-start guide

This documentation assumes you already have a working installation of Apache (from http://www.apache.org/httpd.html) and a working installation of Java (from http://java.sun.com/). It is also heavily linux biased - I make no apology for that!

Firstly, you will need the Tomcat servlet engine for Apache. This allows the webserver to run server-side java code ("servlets"). There are a number of free and commercial servlet engines out there, but these instructions will deal with Tomcat specifically. Tomcat is the reference implementation of the Servlet 2.2 technology.

Grab a copy of the latest release build from http://jakarta.apache.org/. At time of writing, this is Tomcat 3.2.3, and is available at: http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.3/bin/.

Unarchive it in an appropriate place:

		cd /usr/local
		tar xzvf jakarta-tomcat-3.2.3.tar.gz

The current version of the Tomcat distribution doesn't have the right permissions set on the files. Fix this by typing:

		chmod +x /usr/local/jakarta-tomcat-3.2.3/bin/tomcat.sh

For detailed instructions on installing and configuring Tomcat, see the documentation in the distribution, but essentially, just do:

		cd /usr/local/jakarta-tomcat-3.2.3/bin
		./tomcat.sh start

You should then be able to see Tomcat running at http://127.0.0.1:8080/.

Next you will need to grab the Apache Tomcat redirector. This is available from the same place as the Tomcat distribution, eg http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.3/bin/linux/i386/mod_jk-eapi.so. Download the module and place it in the Apache modules directory, usually /usr/lib/apache/1.3/.

Configure Tomcat to use AJP13. This provides speed benefits and the ability to use HTTPS. Add the following to TOMCAT/conf/server.xml:

		<Connector className="org.apache.tomcat.service.PoolTcpConnector">
			<Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp13ConnectionHandler"/>
			<Parameter name="port" value="8009"/>
		</Connector>

Now it's time to configure Apache. The mod_jk howto suggests using the automatically generated Tomcat config, but sadly this tries to find loadable modules in /etc/apache/libexec and it tries to put log files in /usr/local/apache... neither of which is the Debian way. So, edit your httpd.conf and add:

		# Configuration for Tomcat
		LoadModule jk_module /usr/lib/apache/1.3/mod_jk-eapi.so
		JkWorkersFile /usr/local/jakarta-tomcat-3.2.3/conf/workers.properties
		JkLogFile /var/log/apache/mod_jk.log
		JkLogLevel warn
		JkMount /*.jsp ajp13

The last line will ensure that all requests for .jsp files will be diverted to Tomcat.

Finally, it's time to test things. Start Tomcat then Apache:

		cd /usr/local/jakarta-tomcat-3.2.3/bin
		./tomcat.sh start
		apachectl graceful

Then, assuming you have the Tomcat default distribution, you should be able to visit http://127.0.0.1/examples/jsp/num/numguess.jsp to see a live example passed from Apache to Tomcat. Note that you need to start Tomcat and then Apache (always in that order) and if you restart Tomcat, you will need to restart Apache as well.