PART I: getting TOMCAT to start up and answer
1) install java
go to http://java.sun.com/
download and install jdk. newest version 1.3.1_01, file name
is j2sdk-1_3_1_01-linux-i386-rpm.bin (or something like that.)
feed it into a shell:
sh j2sdk-1_3_1_01-linux-i386-rpm.bin
scroll through the license agreement, answer yes at the bottom,
and it will unpack into jdk-1.3.1_01.i386.rpm
install the rpm file:
rpm -ivh jdk-1.3.1_01.i386.rpm
default install from this rpm file will be in /usr/java/jdk1.3.1_01
2) tomcat docs are at
http://jakarta.apache.org/tomcat/tomcat-3.2-doc/index.html
but have not been consistently kept up to date. keep this in mind when
going through the install & setup.
3) download tomcat components, ancillaries
go to:
http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.3/bin/
download:
jakarta-servletapi-3.2.3.tar.gz
jakarta-tomcat-3.2.3.tar.gz
create a directory for them (/home/jakarta, /tools/jakarta,
/usr/jakarta, or some such) and unpack them into subdirectories
of this root directory.
also download mod_jk from
http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.3/bin/linux/i386/
for redhat 6.2 and newer, you will want mod_jk-eapi.so (this is because
apache as distributed for current redhat has the eapi compiled in. other
apache distributions may or may not. if you don't know, download both,
and if you try the wrong one, you'll get a warning when apache starts and
can switch to the other one.)
4) set up Environment variables
these can be set in your shell, but if you plan to actively use
tomcat, you will want to set them in a profile. the following assumes
that you are using bash as your shell.
to set environment variables globally (for all users), edit /etc/profile
to set them locally (for a single user), edit ~/.bash_profile
here are the environment variables for tomcat & java setup:
JAVA_HOME=/usr/java/jdk1.3.1_01
TOMCAT_HOME=/tools/jakarta/jakarta-tomcat-3.2.3
PATH="$PATH:$JAVA_HOME/bin"
CLASSPATH=$JAVA_HOME/lib
Note the CLASSPATH environment variable will get more entries as you
develop java projects. note also that these must be exported after they
are set to be visible, e.g. "export JAVA_HOME TOMCAT_HOME PATH CLASSPATH"
5) the default permissions in the binary directory for tomcat are wrong
for some silly reason.
cd $TOMCAT_HOME/bin
chmod 744 *.sh
6) edit workers.properties (again, it's in $TOMCAT_HOME/conf/)
search for workers.tomcat_home
change this to the absolute path to your tomcat installation, e.g.
workers.tomcat_home=/tools/jakarta/jakarta-tomcat-3.2.3
next one down is workers.java_home; same deal
workers.java_home=/usr/java/jdk1.3.1_01
next one down is what slash works in your file system; unix and
windows are opposite, use / for unix (default is windows style for
some mysterious reason):
#ps=\
ps=/
7) we're not done yet, but this is a good point to test how it works so far.
tomcat is not yet tied to the apache web server, but it can run standalone
and can answer queries on port 8080 (web servers normally answer on port 80)
it comes with some test programs and examples already set up, so you
can just start it and see if they're there and working.
to start tomcat, go to your tomcat bin directory (on my systems,
/tools/jakarta/jakarta-tomcat-3.2.3/bin) and enter the shell command
./startup.sh
tomcat should start right up, in the background. it will emit some messages
to the shell window. you will want to watch for this message:
2001-10-13 20:36:43 - PoolTcpConnector: Starting HttpConnectionHandler on 8080
which means that tomcat is now listening in standalone mode on port 8080
bring up your web browser and type a suitable URL (my test set up is
on a machine with an ip address of 10.1.1.6, so what follows is the URL
i used):
http://10.1.1.6:8080/
you should get an index page with links for JSP Examples and Servlet
Examples. try them out.
note that if you are running the web browser on the system as you have
installed tomcat, you can also use the following URL:
http://127.0.0.1:8080/
or perhaps:
http://localhost.localdomain:8080/
http://localhost:8080/
it should work; if it doesn't, look at $TOMCAT_HOME/logs for potential
errors. look anyway, even if it works, to see if there's anything that's
not quite right.
PART II: Hooking Tomcat up to Apache
this is where the online tomcat documentation really falls down. some of
the oldest documentation refers to setups that are based on the old
mod_jserv module, which is now obsolete. newer documentation refers to
mod_jk, but fails to clearly explain the difference between the eapi and
no-eapi versions of mod_jk.
if you have a redhat 6.2 or newer redhat distribution, you need
mod_jk-eapi.so. for other systems, you will need to experiment. the rest
of this document is predicated on a newer redhat distribution (i'm using
7.1 at this writing).
8) take a copy of mod_jk-eapi.so (which you downloaded in step 3 above)
and place it in /etc/httpd/modules; set its permissions
chmod 755 mod_jk-eapi.so
9) add the following line (with an appropriate absolute path) to the end
of /etc/httpd/conf/httpd.conf
include /tools/jakarta/jakarta-tomcat-3.2.3/conf/mod_jk.conf-local
10) go to the tomcat conf directory, create the mod_jk.conf-local file
by making a copy of the mod_jk.conf-auto file:
cd $TOMCAT_HOME/conf
cp mod_jk.conf-auto mod_jk.conf-local
11) edit the new file. on about the 7th line, change
LoadModule jk_module libexec/mod_jk.so
to
LoadModule jk_module modules/mod_jk-eapi.so
(the -auto file is automatically generated by tomcat, but the code
which generates is making assumptions that do not apply to the RedHat
setup for the apache web server. we make a -local copy and put the
change in it because the -auto file is overwritten every time tomcat
starts. there is a way to alter the -auto file generation, but i've
not yet looked into it.)
12) edit server.xml in the same directory
12a) now you need to make a decision. if your server is sitting behind
a firewall or is otherwise isolated from the internet, you probably
wish to leave the tomcat engine listening on port 8080 as it permits
you to test servlets and java server pages independently of apache.
if exposed to the internet, you probably want to search for the
string "Normal HTTP" and comment out the connector, like this:
the comment out all that is between them. i leave the 8080
connector up on my home development engine, but shut it down on krusty.
12b) you DO wish to enable AJP13 support. search for the
string "Apache AJP12"
copy the connector (5 lines plus 2 comment lines), and paste
in a new copy right after. edit the new copy, changing
Ajp12ConnectionHandler to Ajp13ConnectionHandler and
port 8007 to port 8009. leave the original AJP12 connector intact.
you should end up with about 15 lines that look like the following:
the AJP12 connector works tolerably well, but the AJP13 connector
has much, much better support for SSL and session maintenence.
13) restart tomcat
cd $TOMCAT_HOME/bin
./shutdown.sh
./startup.sh
14) restart apache
cd /etc/rc.d/init.d/
./httpd stop
./httpd start
15) test
http://yourdomainoriphere/examples/jsp/
http://yourdomainoriphere/examples/servlets/
if you get the same stuff you got with port 8080 access, you're nearly
there. part III (being written) will address how to set up something
besides the examples.