Chapter 3. Installing Tomcat

This chapter covers downloading and installing the Tomcat binaries on a Linux system.

3.1. Prerequisites

Before we begin, we will need to have a Java 2 SDK installed. This document is based on the IBM Java 2 SDK v 1.4.1. With Tomcat 5, because of dramatic changes in Linux in the last year, there are a few things you will need to be aware of.

If you are using Red Hat 9, Fedora Core or any Linux distribution that uses the NPTL (Native POSIX Thread Library), you may have problems getting Java to run properly. If you're getting frequent segmentation faults, you might want to turn off NPTL. My advice is to get the latest versions of everything, that is, install version 1.4.1 of the Java 2 SDK or better, and get the 2.6 Linux kernel for superior performance.

I will not cover the installation of the Java SDK here. I have a write-up on this -- and how you can turn off NPTL -- at this location.

There are significant differences between Tomcat 4 and Tomcat 5.

3.2. Downloading The Software

You can find the Tomcat binaries at : http://jakarta.apache.org/site/binindex.cgi. Scroll to the bottom of the page to find the links for Tomcat 5.x, 4.x and the web server connectors.

With Tomcat 5, there are now 7 files available for download. If you are running Linux/UNIX, the package you are looking for is the tarball, which at the time of this writing is 5.0.18 tar.gz. Click on the link and your download should start automatically.

Table 3-1. Tomcat 5 Packages as at 14 February 2004

Package Name Operating System Remarks
jakarta-tomcat-5.0.25.tar.gz UNIX/Linux This is the base Tomcat package. The servlet engine and startup scripts are in this package.
jakarta-tomcat-5.0.25-deployer.tar.gz UNIX/Linux This is the Tomcat Deployer package. The deployer is for easily deploying and undeploying web applications, especially if you are using an IDE. See the Appendix for integrating the deployer with Eclipse.
jakarta-tomcat-5.0.25-embed.tar.gz UNIX/Linux This is the embedded Tomcat package. [TBD]
jakarta-tomcat-5.0.25.exe Microsoft Windows This is the installer for Microsoft Windows. This probably works on NT4/2000/XP. Not so sure about 95/98/ME. If you know, please email me.
jakarta-tomcat-5.0.25.zip, jakarta-tomcat-5.0.25-deployer.zip, jakarta-tomcat-5.0.25-embed.zip Windows/UNIX/Linux You can use this zip file on UNIX/Linux, but you will have to remember to set the permissions properly before it will work. Why go to all that trouble? Just use the tar package.

If you are using Windows, you have a choice of either the zip file or the EXE file. I haven't tried running Tomcat 5 on Windows, so I cannot say anything else about it.

3.3. Installing The Software

There are many ways that you can get Tomcat installed on your Linux system. You could use the rpm's that are now available on jpackage.org or the tarballs from the Jakarta site. This document covers only the Jakarta tarballs. I have never used the rpm packages before.

If you have already downloaded the binary, simply copy it to the directory you want to install it under and expand the file. For example, if I downloaded the Tomcat tar file into /home/someuser/downloads and wanted to install it under /opt, here is what I would do. As root user:

# cp /home/someuser/downloads/jakarta-tomcat-5.x.xx.tar.gz /opt
# tar -zxvf jakarta-tomcat-5.x.xx.tar.gz

A directory called jakarta-tomcat-5.x.xx will be created and the Tomcat files will expand under it.

Previously, I would have recommended that the jakarta-tomcat-5.x.xx directory be renamed to just tomcat. However, because I expect Tomcat 5 to be updated more frequently for now, since it has only just been released, I would instead recommend creating a symbolic link to a tomcat directory.

# ln -s jakarta-tomcat-5.0.25 tomcat

In order for Tomcat to startup and shutdown, you will also need to add an environment variable pointing to the Tomcat directory (CATALINA_HOME), and one variable pointing to your Java SDK directory (JAVA_HOME). I will make the following assumptions:

JAVA_HOME

Java is installed into /opt/IBMJava2-141.

CATALINA_HOME

Tomcat is installed into /opt/jakarta-tomcat-5.x.xx and symlinked to /opt/tomcat.

Insert the following lines inside /etc/profile or /root/.bashrc.

export JAVA_HOME=/opt/IBMJava2-141
export CATALINA_HOME=/opt/tomcat

Now, save the file and reboot the system to ensure that all changes take effect.

3.4. Starting and Stopping Tomcat

Before we begin, we will need to ensure that CATALINA_HOME and JAVA_HOME are correctly set. To do this, we open a terminal and type the following :

# echo $CATALINA_HOME
# echo $JAVA_HOME

If you get a blank line, or if the directory points anywhere besides where it is supposed to, you will have to correct these environment variables first, before continuing.

If everything is fine, you can start Tomcat with the following command. As root,

# $CATALINA_HOME/bin/startup.sh

To check if Tomcat is running fine, you should open a browser and point the URL to http://localhost:8080. You should see the default Tomcat welcome page. It would be a good idea, at this point, to browse the documentation or try out the example servlets and JavaServer Pages samples.

To stop Tomcat, as root,

# $CATALINA_HOME/bin/shutdown.sh

If Tomcat does not start and you downloaded the zip file, the cause is probably due to permissions. Ensure that the following files are executable : inside $CATALINA_HOME/bin directory,

# chmod +x startup.sh
# chmod +x shutdown.sh
# chmod +x tomcat.sh 

After you have made the files executable, try starting and stopping Tomcat again.

3.5. Running Tomcat as Non-Root User

I don't believe there any issues with running Tomcat as root user. However, for the more security-conscious readers out there, here are some instructions on running Tomcat as a non-root user.

At this stage, the Tomcat packages, files and binaries are owned by root. We will first need to create a Tomcat user and group that will own these files, and under which Tomcat will run.

Tomcat User :: tomcat

Tomcat Group :: tomcat

Not too imaginative, huh ? We will now create the Tomcat user and group. Open a terminal window and, as root,

# groupadd tomcat
# useradd -g tomcat -d /opt/tomcat tomcat
# passwd tomcat

Notice that we specified the home directory of Tomcat to be /opt/tomcat. Some people believe that this is good practice because it eliminates an additional home directory that needs to be administered.

Now, we will put everything in /opt/tomcat under Tomcat user and group. As root,

# chown -R tomcat:tomcat /opt/tomcat

If /opt/tomcat is a symlink to your Tomcat install directory, you'll need to do this:

# chown -R tomcat:tomcat /opt/jakarta-tomcat-5.x.xx

Verify that JAVA_HOME and CATALINA_HOME environment variables are setup for tomcat user, and you should be good to go. Once the Tomcat binaries are under Tomcat user, the way you invoke it will be different.

To start Tomcat,

# su - tomcat -c /opt/tomcat/bin/startup.sh

To stop Tomcat,

# su - tomcat -c /opt/tomcat/bin/shutdown.sh

Also, be aware that your web applications will need to be deployed (i.e. copied to the web application directories) as user tomcat, instead of root. A little more hassle, but possibly a little safer too.