One-way ticket to Java: Installing Apache Tomcat on Ubuntu

This article is a guide to install and run Apache Tomcat 6 on Ubuntu 9.10. It covers version 6.0.20, but the steps are almost the same for any Tomcat 6 version. During the installation, we will create an script to help us control the server. This script will start, stop or restart the server depending on the parameters. Keeping the same folder structures used in previous posts, Tomcat 6 will be installed within the user's home folder, specifically, inside the servers folder (take a look at this post).

Apache Tomcat is an open source software implementation of the Java Servlet and JavaServer Pages technologies, Tomcat 6 implements the Servlet 2.5 version and JavaServer Pages 2.1 version. In others words, Tomcat supplies an implementation of the Java Servlet and JavaServer Pages specifications in the form of a Web container, and you, as application developer, should develop your applications in the form of components (Servlets and JSPs) and deploy them over this container. Where do I listened this before?

These are some of the key tomcat directories, all relative to $CATALINA_HOME, the tomcat home directory:

/bin: startup, shutdown, and other scripts.
/conf: configuration files. The most important one in here is server.xml, the main configuration file for the container.
/logs: log files are stored here by default.
/webapps: this is where your web applications go.

All of the information in the configuration files is read at startup, meaning that any change to the files requires a restart of the container to be applied.

Environment

Required software that has already been installed and configured on the system.

Ubuntu 9.10
JDK 6 Update 16

Required files (~/downloads)

Downloaded files required during the installation process.

apache-tomcat-6.0.20.tar.gz
- http://tomcat.apache.org/
- Binary Distributions

Installation steps

Step 1 - Unpack and move to the desired location

First of all, create the folder where this server and subsequent servers will be installed in the future (e.g. ~/lab/servers). Then, unpack the apache-tomcat-6.0.20.tar.gz file and move it to the previous created folder. Finally, create a symbolic link, a short cut that will allow us to keep the same folder structure whatever the version is installed.

~$ mkdir -p ~/lab/servers
~$ cd downloads
~/downloads$ ls -l
-rw-r--r-- 1 me me   5998298 apache-tomcat-6.0.20.tar.gz
~/downloads$ tar -xvzf apache-tomcat-6.0.20.tar.gz
[...]
apache-tomcat-6.0.20/webapps/manager/sessionsList.jsp
apache-tomcat-6.0.20/webapps/manager/status.xsd
apache-tomcat-6.0.20/webapps/manager/xform.xsl
~/downloads$ mv apache-tomcat-6.0.20 ~/lab/servers
~/downloads$ ln -s ~/lab/servers/apache-tomcat-6.0.20/ ~/lab/servers/tomcat

Terminal

Step 2 - Set the environment variables for Apache Tomcat

Before running Tomcat, the JAVA_HOME environment variable should be set to the base path of your JDK installation. This variable should have been configured during the installation of the Java Sun JDK, but it will be explained here again anyway. At the same time as we add the JAVA_HOME variable, we will add the CATALINA_HOME variable and modify also the PATH variable. The CATALINA_HOME environment variable represents the root of your Tomcat installation (this variable will be used inside the script code to control the server). Finally, we will append to the PATH environment variable the path to the user's local bin folder, which we will create later to put there the launcher script.

We can edit the ~/.profile file or ~/.bashrc file. The difference between these files is that the former is loaded once when you log in, whereas the latter is loaded every time you start a new terminal.

Add the following lines at the end of the file. Remember, when declaring JAVA_HOME, the right part of the equality should point the base path of your JDK installation.

# Java environment variables
export JAVA_HOME=$HOME/lab/jvm/java-6-sun

# Apache Tomcat enviroment variables
export CATALINA_HOME=$HOME/lab/servers/tomcat

# User environment variables
export PATH=$PATH:$HOME/bin

~/.bashrc or ~/.profile

Log out or close all the terminals, depending on the file edited, to apply the changes.

Create a script to start, stop and restart Tomcat

Create the user's bin folder, if it is not created already. In this folder will be stored the launchers of the programs.

~$ mkdir ~/bin

Terminal

Inside the ~/bin folder, create a new file called tomcat with the following content inside it.

# Starts, stops and restarts Apache Tomcat server

case $1 in
start)
        sh $CATALINA_HOME/bin/startup.sh
        message="Tomcat started."
        ;;
stop)
        sh $CATALINA_HOME/bin/shutdown.sh
        message="Tomcat stopped."
        ;;
restart)
        sh $CATALINA_HOME/bin/shutdown.sh
        sh $CATALINA_HOME/bin/startup.sh
        message="Tomcat restarted"
        ;;
*)
        message="Use: tomcat start|stop|restart"
        ;;
esac
echo $message
exit 0

Script to start, stop and restart the Apache Tomcat server.

Save it, and change the permissions to make it executable.

~$ chmod +x ~/bin/tomcat

Terminal

At this point, since we have already added the ~/bin folder inside the PATH environment variable, we can now start, stop or restart the Tomcat server from any point inside the file system.

Test

Open a terminal and execute the tomcat script with the start parameter, this should start the server. Check the values of CATALINA_HOME and JRE_HOME from the output generated on the start up of the server.

~$ tomcat start
Using CATALINA_BASE:   /home/me/lab/servers/tomcat
Using CATALINA_HOME:   /home/me/lab/servers/tomcat
Using CATALINA_TMPDIR: /home/me/lab/servers/tomcat/temp
Using JRE_HOME:       /home/me/lab/jvm/java-6-sun
Tomcat started.

Terminal

Launch your favourite web browser and write on the address bar this location: http://localhost:8080. You should see a page similar to the figure below, if so, you have successfully installed the server in your user account.

Tomcat server welcome page.

The next step is to verify the set up of the JDK. This will be done by executing one of the JSP examples provided by the Tomcat server. At the page shown in the figure above, choose "JSP Examples", inside the menu at the bottom left. Now look for the JSP example "Numberguess" and select the Execute link. If everything was installed properly you should see a page similar to the figure below.

JSP example Numberguess.

If you do not see the previous page, you should check that the location of your JAVA_HOME environment variable matches the location of your JDK installation. However, if everything is working properly, you can reward yourself playing the game for a while. To conclude, I know that it would be interesting to test the Tomcat server running our own small web application. But, since the next articles about Servlets and JSPs will use the Tomcat server, this section will finish right here and will leave further tests for the following posts.