Installing Tomcat

Now that you’ve installed Java, it’s time for you to install the Tomcat server. The Windows installations are first, followed by instructions for Linux.

The first step for all systems is obtaining the appropriate distribution. This may be a binary or source distribution, depending on your needs. Whatever your requirements, Tomcat is available from http://jakarta.apache.org/site/binindex.cgi. Choose the most stable version of Tomcat 5.0.x or Tomcat 5.5.x provided. The choice will largely depend on what version of Java you’re using. If you have JDK 5, then choose Tomcat 5.5.x; otherwise you can pick either, because Tomcat 5.5.x can be modified to work with earlier versions of Java (download the appropriate compatibility zipped file).

You can select a binary installer if you’re a Windows user and want to use Tomcat as a service, or you can select a zipped version of the binaries for any system.

If you’re interested in the latest version of Tomcat or want to download an older version, you’ll find both of these options below the binary downloads.

Note 

Tomcat 5.5 doesn’t come with documentation for Tomcat’s internal APIs. If you require this documentation, click the title link for the Tomcat 5.5 distribution (the link above the list of download options starting with KEYS). This will take you to a directory listing of an Apache download mirror. Click bin, and then select jakarta-tomcat-5.5.x-fulldocs.tar.gz. This is a Web application to replace the default tomcat-docs Web application.

You’ll also require Ant for various deploy and build tasks later in the book. Ant is a build tool like make and is another excellent Jakarta project.

Installing Tomcat on Windows Using the Installer

If you choose to install Tomcat with the installer, save it in a convenient location and double-click it to begin installation. As always, you must agree with the license agreement before you can continue with the installation.

Figure 2-2 shows the screen where you choose which components to install.

Figure 2-2: Tomcat’s installation options

Installing Tomcat As a Service

If you select the Service option, as shown in Figure 2-2, you’ll install Tomcat as a service, with all the functionality that entails. This is a useful option if you want Tomcat to run every time you start your machine or if you want it to run as a unique user so you can track its behavior. Remember that this isn’t available on Windows 98 and its derivatives. However, you’ll see a work-around for this a bit later in the “Running Tomcat in the Background” section.

Tomcat will run at startup and will run in the background even when no user is logged in. This is the option you’d use on a deployment server, but it’s probably not the option you’d use on a development machine.

Note 

The installer will install Tomcat as a service whether you check this box or not. The difference is that the installer will install the service to start automatically by default if you check the box. Otherwise it’s set to manual startup.

Installing Tomcat’s Source Code

If you want to compile Tomcat from source, select this option. Note that you’ll require Ant for this process, which I’ll cover in the “Installing Tomcat from Source” section.

Installing Tomcat’s Documentation

You should install the Tomcat documentation; it’s a useful resource and includes the Servlet and JSP API javadocs. You’ll find these invaluable if you do any Web development.

Installing Tomcat’s Start Menu Items

If you want to add shortcuts to Windows’ Start menu, then select this option.

Installing Tomcat’s Example Web Applications

If you want to examine Tomcat’s example Web applications, then select this option. This is unlikely if you’ll be using Tomcat as a production server because they will simply take up space and are certainly a security risk. The examples aren’t written with security or performance in mind, and, as well-known applications, they’re vulnerable to denial-of-service attacks and attempts to gain root access. If your users want to have them in a deployment environment, by all means let them.

Finishing the Installation

Once you’ve chosen the components you want to install, click Next. The installer will then ask you for information on installation directories, the location of Java, an administrator’s username and password, and the port details. Fill in these as appropriate for your installation.

Note 

All public Web servers run on port 80, which is the default HTTP port. When a browser attempts to connect to a Web site, it uses port 80 behind the scenes; that is, you don’t have to specify it. Tomcat’s HTTP service runs on port 8080 by default to avoid a clash with other Web servers that may already be running. You’ll see how to change this in Chapter 4.

If you’re using Tomcat 5.5.x and JDK 1.4, then extract the contents of jakarta-tomcat-5.5.x-compat.zip to the appropriate subdirectory of %CATALINA_HOME%. You can see where the files are to be placed in Figure 2-3.

Figure 2-3: Tomcat 5.5.x compatibility file for JDK 1.4

Here jakarta-tomcat-5.5.2 is %CATALINA_HOME%, so move the files to the corresponding directory of your %CATALINA_HOME% like this:

• %CATALINA_HOME%\bin\jmx.jar

• %CATALINA_HOME%\common\endorsed\xercesImpl.jar

• %CATALINA_HOME%\common\endorsed\xml-apis.jar

These APIs are now part of the new Java specification and as such are missing from Tomcat 5.5.x.

Setting Environment Variables

The scripts provided with Tomcat will usually be able to guess at your setup so that no further intervention is strictly necessary. However, it’s prudent to add the following environment variables.

Adding the CATALINA_HOME Environment Variable

%CATALINA_HOME% is the directory where you chose to install Tomcat. Tomcat needs to know this information to find the resources that are referenced as relative paths to this folder. If you chose the default directory while installing, this will be C:\Program Files\Apache Software Foundation\Tomcat 5.x.

To add the environment variable in Windows XP, navigate to Start Settings Control Panel, and choose System. Now choose the Advanced tab, and click the Environment Variables button. Click the New button in the System Variables section, call the new variable CATALINA_HOME, and enter the path to your installation.

In Windows 98, set the environment variables in c:\autoexec.bat. Open the file, and add the following path to your installation:

 set CATALINA_HOME=c:\tomcat5.x 

For Windows ME, you can use the System Configuration utility to set environment variables. To run it, choose Start Programs Accessories System Tools System Information. You’ll see a Microsoft help and support page, from which you should select the Tools menu and then the System Configuration utility. From here, select the Environment tab, and set the CATALINA_HOME variable to point to your Tomcat installation directory.

CATALINA_HOME in Windows 9x

In Windows 9x, problems with file length and spaces in the path make it safer to install Tomcat directly onto c:\ rather than under Program Files. You’ll also need to increase the default environment space to Tomcat by opening a DOS prompt window, right-clicking it, choosing Properties, selecting the Memory tab, and setting the initial environment to 4096 bytes (4 kilobytes).

Testing the Installation

To test the installation, you must first start the server. You can start the server in two ways: manually or as a service.

Starting the Server Manually

You can start the server manually by selecting Start Programs Apache Tomcat 5.x and then selecting the Tomcat 5.x Program Directory option. Navigate to the bin directory, and double-click startup.bat. A new terminal window will start that shows the server is running. You can also run it from a command prompt, like so:

 > %CATALINA_HOME%\bin\startup.bat 

Note that if the window appears and promptly disappears again, you can try the tips in the “Troubleshooting and Tips” section.

If you want to shut down the server, use the shutdown.bat file in the bin directory.

Starting the Server As a Service

If you want to start the server as a service, you have three choices. First, you could have selected to start the server at the end of installation.

Second, choose Start Settings Control Panel, and select Administrative Tools. You then select the Services icon, which will contain an entry for Tomcat, as shown in Figure 2-4.

Figure 2-4: The Services administrative tool with the Tomcat service highlighted

To start the service, right-click the Tomcat entry, and then choose Start. You won’t see a console window, as described previously, because the server is running as a service. Once you’ve started the service, you can then restart and stop it by right-clicking the service’s entry in the Services window.

You can also start and stop the service using the Tomcat monitor. To start the monitor, select Start Programs Apache Tomcat 5.x Monitor Tomcat. You’ll see a new icon in your system tray with a red stop sign on it. You can double-click the icon to display the Apache Tomcat Properties box, as shown in Figure 2-5.

Figure 2-5: The Apache Tomcat Properties box

You can start, stop, pause, and restart the service here as you could in the Services utility. You can also start and stop the service by right-clicking the monitor’s icon and selecting the action you want to perform.

Running Tomcat in the Background

If you don’t want to run Tomcat as a service, or are unable to because you’re running Windows 9x/ME, you can still run Tomcat without a command prompt/DOS prompt window open while Tomcat is running by modifying the catalina.bat file in %CATALINA_HOME%\bin. Replace the following text:

 %_RUNJAVA% 

with this:

 %_RUNJAVAW% 

This command calls the windowless version of the java executable. Tomcat will now start with no attached Tomcat window, but one will appear and disappear.

You should now check that the server is indeed running (the absence of a window makes it hard to check by the usual means) by going to the server’s home page as described in the next section. If you find a problem, run the startup batch file from the %CATALINA_HOME%\bin directory and note the error messages.

Viewing the Default Installation

Tomcat, like most servers, comes with a default home page that you can use to check the installation. Enter the following address in a browser: http://localhost:8080/. You should see a page similar to the one in Figure 2-6.

Figure 2-6: The Tomcat default home page

As mentioned, Tomcat connects to port 8080 by default. This is to avoid problems with other servers, such as Apache or IIS, that may be running on the machine.

If you have any problems, refer to the “Troubleshooting and Tips” section later in this chapter.

Installing Tomcat on Windows Using the Zipped File

Installing Tomcat using the zipped file is extremely straightforward. It’s significantly bigger than the executable installer but has the same contents. All you have to do to install Tomcat from the zipped file is to uncompress the contents to a convenient directory.

The final step of installation is to add the %CATALINA_HOME% environment variable as described previously. To start the server, you need to navigate to %CATALINA_HOME%\bin (no shortcut this time, though you should create your own).

Now start the server as per the previous manual instructions; that is, double-click startup.bat. A new terminal window will start that shows the server is running.

You can also run it from a command prompt, like so:

 > %CATALINA_HOME%\bin\startup.bat 

If you’re using Tomcat 5.5.x and JDK 1.4, then extract the contents of jakarta-tomcat-5.5.x-compat.zip to the same location as the Tomcat zipped file. You can see where to place the files in Figure 2-3. The Tomcat zipped file and the compatibility zipped file have the same structure so that installation is simple.