3.2 Installing the Tomcat Server

Tomcat supports many features and configuration options. In this section, I only describe the basics that you need to know to get Tomcat up and running. If you plan to use Tomcat extensively for development or as a production server, you'll find extensive information in Jason Brittain and Ian Darwin's Tomcat: The Definite Guide (O'Reilly).

You can download the Tomcat server in binary format or as source code that you compile yourself. If you're primarily interested in learning about JSF, I recommend that you use the binary download for running the examples in this book and to develop your own applications. If you're a Java programmer and are interested in seeing how Tomcat is implemented, feel free to download the source as well and take a look at the internals.

The binary distribution is available at http://jakarta.apache.org/site/binindex.cgi. On this page, you will find three types of builds: release builds, milestone builds, and nightly builds. Release builds are stable releases that have been tested extensively and verified to comply with the supported specifications. Milestone builds are created as intermediary steps towards a release build. They often contain new features that aren't yet fully tested but are generally known to work. A nightly build, however, may be very unstable. It's actually a snapshot of the latest source code and may have been tested only by the person who made the latest change. You should use a nightly build only if you're involved in the development of Tomcat.

I recommend that you download the latest release build. All examples in this book were developed and tested using Version 5.0.18, but any release later than 5.0.18 should work fine as well. The release builds are available as archive files of different formats. Which one to pick and how to install it varies a bit, depending on your platform.

3.2.1 Windows Platforms

For Windows, select jakarta-tomcat-5.0.18.zip^[2] and save it to your hard drive—for instance, in a directory named C:\Jakarta. Unpack the package either with a ZIP utility program such as WinZip or use the jar command included in the Java distribution. Use the Command Prompt window where you set the JAVA_HOME and PATH environment variables, change to the directory in which you downloaded the ZIP file, and unpack it:

^[2] There's also a file with an .exe extension in the list of downloads. This is a GUI installer for Windows. While it simplifies the installation, it makes it almost impossible to debug installation problems and it doesn't work at all for older versions of Windows, e.g., Windows ME. I suggest that you use the command-line installation process described in this chapter, at least until you're familiar enough with Tomcat to handle the GUI installer issues.

C:\> cd Jakarta

C:\Jakarta> jar xvf jakarta-tomcat-5.0.18.zip

This creates a directory structure that has a top directory named jakarta-tomcat-5.0.18 and a number of subdirectories. Like most software packages, the top directory contains a file named README.txt; do that. Software distributions change and if, for instance, the instructions in this chapter no longer apply when you download the software, the README.txt file should contain information about how to get started. Additional details are found in the file named RUNNING.txt.

You should also set the CATALINA_HOME environment variable to point to the Tomcat installation directory:

C:\Jakarta> set CATALINA_HOME=C:\Jakarta\jakarta-tomcat-5.0.18

If you wonder about the variable name, Catalina is the name of the servlet container and Jasper is the name of the JSP container; together, they are known as the Tomcat server.

The Tomcat installation directory contains a number of subdirectories, described later. The bin directory contains Windows batch files for starting and stopping the server. The batch files are named startup.bat, shutdown.bat, and catalina.bat. The catalina.bat file is the main script for controlling the server; it's called by the two other scripts (startup.bat and shutdown.bat). To start the server in a separate window, change to the bin directory and run the startup.bat file:

C:\Jakarta> cd jakarta-tomcat-5.0.18\bin

C:\Jakarta\jakarta-tomcat-5.0.18\bin> startup

A new Command Prompt window pops up; you see startup messages similar to this:

Feb 29, 2004 12:53:59 PM org.apache.coyote.http11.Http11Protocol init

INFO: Initializing Coyote HTTP/1.1 on port 8080

Feb 29, 2004 12:53:59 PM org.apache.catalina.startup.Catalina load

INFO: Initialization processed in 2260 ms

...

INFO: Server startup in 7408 ms

Just leave this window open; this is where the server process is running.

If you're running this on a Windows 95/98/ME platform, you may see an error message "Out of environment space," when you try to start the server. That's because the default amount of space allocated for environment variables isn't enough. To be able to run Tomcat, run this command in the Command Prompt window before you run the startup.bat file again:

C:\Jakarta\jakarta-tomcat\bin> COMMAND.COM /E:4096 /P

This command sets the environment space to 4,096 bytes (4 KB). That should be enough for running this batch file. If you still get the same message, use a higher value.

For some installations, this command may not work. If it doesn't, try this instead:

At this point, the server may not start due to other problems. If so, the extra Command Prompt window may pop up and then disappear before you have a chance to read the error messages. If this happens, you can let the server run in the Command Prompt window with this command instead:

C:\Jakarta\jakarta-tomcat-5.0.18\bin> catalina run

On Windows NT/2000 and Windows XP, you should first make sure that the Command Prompt window has a large enough screen buffer so that you can scroll back in case the error messages don't fit on one screen. Open the Properties window for the Command Prompt window (right mouse button in the upper-left corner), select Layout, and set the screen buffer size height to a large value (for instance, 999). Unfortunately, the Command Prompt screen buffer can't be enlarged for Windows 95/98/ME, so scrolling back isn't an option. If you run into problems on these platforms, double-check that you have installed the Java SDK correctly and that you have set the JAVA_HOME and PATH environment variables as described earlier.

3.2.2 Unix Platforms (Including Linux and Mac OS X)

For Unix platforms, you can download the jakarta-tomcat-5.0.18.tar.gz file, for instance to /usr/local, and use these commands to unpack it (assuming you have GNU tar installed):

[hans@gefion /] cd /usr/local

[hans@gefion local] tar xzvf jakarta-tomcat-5.0.18.tar.gz

If you don't have GNU tar installed on your system, use the following command:

[hans@gefion local] gunzip -c jakarta-tomcat-5.0.18.tar.gz | tar xvf -

This creates a directory structure that has a top directory named jakarta-tomcat-5.0.18 and a number of subdirectories. As in most software packages, the top directory contains a file named README.txt; do that. Software distributions change and if, for instance, the instructions in this chapter no longer apply when you download the software, the README.txt file should contain information about how to get started. Additional details can be found in the file named RUNNING.txt.

You should also set the CATALINA_HOME environment variable to point to the Tomcat installation directory:

[hans@gefion local] export CATALINA_HOME=/usr/local/jakarta-tomcat-5.0.18

Catalina is the name of the servlet container, and Jasper is the name of the JSP container; together, they are known as the Tomcat server.

The Tomcat installation directory contains a number of subdirectories, described later. The bin directory contains Unix scripts for starting and stopping the server. The scripts are named startup.sh, shutdown.sh, and catalina.sh.

Start the server in the background with this command:

[hans@gefion jakarta-tomcat-5.0.18] ./startup.sh

If you want to have Tomcat start each time you boot the system, you can add the following commands to your /etc/rc.d/rc.local (or equivalent) startup script:

export JAVA_HOME=/usr/local/jdk1.4.2

export CATALINA_HOME=/usr/local/jakarta-tomcat-5.0.18

$CATALINA_HOME/bin/startup.sh