Of all of the popular servlet and JSP engines, Tomcat is the hardest to configure. Tomcat is also the most fluid of the popular servers: compared to most other servers, Tomcat has more frequent releases and each version has more significant changes to the setup and configuration instructions. So, to handle new versions of Tomcat, we maintain an up-to-date Web page at http://www.coreservlets.com/ for installing and configuring Tomcat. Our online Tomcat configuration page includes sample versions of the three major files you need to edit: autoexec.bat , server.xml , and web.xml . If you use a version of Tomcat later than 4.1.24, you may want to refer to that Web site for details. Instructions consistent with release 4.1.24 follow.
Your first step is to download the Tomcat zip file from http://jakarta.apache.org/tomcat/. Click on Binaries and choose the latest release version. Assuming you are using JDK 1.4, select the "LE" version (e.g., tomcat-4.1.24-LE-jdk14.zip ). Next , unzip the file into a location of your choosing. The only restriction is that the location cannot be protected from write access: Tomcat creates temporary files when it runs, so Tomcat must be installed in a location to which the user who starts Tomcat has write access. Unzipping Tomcat will result in a top-level directory similar to C:\jakarta-tomcat-4.1.24-LE-jdk14 (hereafter referred to as install_dir ). Once you have downloaded and unzipped the Tomcat files, configuring the server involves the following steps. We give a quick summary below, then provide details in the following subsections.
The following subsections give details on each of these steps. Please note that this section describes the use of Tomcat as a standalone server for servlet and JSP development . It requires a totally different configuration to deploy Tomcat as a servlet and JSP container integrated within a regular Web server (e.g., with mod_webapp in the Apache Web Server). For information on the use of Tomcat for deployment, see http://jakarta.apache.org/tomcat/tomcat-4.1-doc/.
Setting the JAVA_HOME Variable
The most critical Tomcat setting is the JAVA_HOME environment variablean improper setting stops Tomcat from finding the classes used by javac and thus prevents Tomcat from handling JSP pages. This variable should list the base SDK installation directory, not the bin subdirectory. For example, if you are running Windows and you installed the SDK in C:\j2sdk1.4.1_01 , you might put the following line in your C:\autoexec.bat file. Remember that the autoexec.bat file is executed only when the system is booted .
On Windows NT/2000/XP, you could also right-click on My Computer, select Properties, then Advanced, then Environment Variables. Then, you would enter the JAVA_HOME value and click OK.
On Unix (Solaris, Linux, MacOS X, AIX, etc.), if the SDK is installed in /usr/local/java1.4 and you use the C shell, you would put the following into your . cshrc file.
setenv JAVA_HOME /usr/local/java1.4
Rather than setting the JAVA_HOME environment variable globally in the operating system, some developers prefer to edit the Tomcat startup script and set the variable there. If you prefer this strategy, edit install_dir /bin/catalina.bat (Windows) and insert the following line at the top of the file, after the first set of comments.
Be sure to make a backup copy of catalina.bat before making the changes. Unix users would make similar changes to catalina.sh .
Specifying the Server Port
Most of the free servers listed in Section 2.2 use a nonstandard default port to avoid conflicts with other Web servers that may already be using the standard port (80). Tomcat is no exception: it uses port 8080 by default. However, if you are using Tomcat in standalone mode (i.e., as a complete Web server, not just as a servlet and JSP engine integrated within another Web server) and have no other server running permanently on port 80, you will find it more convenient to use port 80. That way, you don't have to use the port number in every URL you type in your browser. Note, however, that on Unix, you must have system administrator privileges to start services on port 80 or other port numbers below 1024. You probably have such privileges on your desktop machine; you do not necessarily have them on deployment servers. Furthermore, many Windows XP Professional implementations have Microsoft IIS already registered on port 80; you'll have to disable IIS if you want to run Tomcat on port 80. You can permanently disable IIS from the Administrative Tools/Internet Information Services section of the Control Panel.
Modifying the port number involves editing install_dir /conf/server.xml , changing the port attribute of the Connector element from 8080 to 80, and restarting the server. Replace install_dir with the base Tomcat installation location. For example, if you downloaded the Java 1.4 version of Tomcat 4.1.24 and unzipped it into the C directory, you would edit C:\jakarta-tomcat-4.1.24-LE-jdk14\conf\server.xml .
With Tomcat, the original element will look something like the following:
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8080" minProcessors="5" maxProcessors="75" ... />
It should change to something like the following:
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="80" minProcessors="5" maxProcessors="75" ... />
Note that this element varies a bit from one Tomcat version to another. The easiest way to find the correct entry is to search for 8080 in server.xml ; there should be only one noncomment occurrence. Be sure to make a backup of server.xml before you edit it, just in case you make a mistake that prevents the server from running. Also, remember that XML is case sensitive, so, for instance, you cannot replace port with Port or Connector with connector .
Enabling Servlet Reloading
The next step is to tell Tomcat to check the modification dates of the class files of requested servlets and reload ones that have changed since they were loaded into the server's memory. This slightly degrades performance in deployment situations, so is turned off by default. However, if you fail to turn it on for your development server, you'll have to restart the server or reload your Web application every time you recompile a servlet that has already been loaded into the server's memory.
To turn on servlet reloading, edit install_dir /conf/server.xml by adding a DefaultContext subelement to the main Service element and supply true for the reloadable attribute. The easiest way to do this is to find the following comment:
<!-- Define properties for each web application. ... ... -->
and insert the following line just below it:
Again, be sure to make a backup copy of server.xml before making this change.
Enabling the ROOT Context
The ROOT context is the default Web application in Tomcat; it is convenient to use when you are first learning about servlets and JSP (although you'll use your own Web applications once you're more experiencedsee Section 2.11). The default Web application is already enabled in Tomcat 4.0 and some versions of Tomcat 4.1. But, in Tomcat 4.1.24, it is disabled by default. To enable it, uncomment the following line in install_dir /conf/server.xml :
<Context path="" docBase="ROOT" debug="0"/>
Turning on the Invoker Servlet
The invoker servlet lets you run servlets without first making changes to the WEB-INF/web.xml file in your Web application. Instead, you just drop your servlet into WEB-INF/classes and use the URL http:// host /servlet/ ServletName (for the default Web application) or http:// host/webAppPrefix /servlet/ ServletName (for custom Web applications). The invoker servlet is extremely convenient when you are first learning and even when you are in the initial development phase of real projects. But, as discussed at length later in the book, you do not want it on at deployment time. Up until Apache Tomcat 4.1.12, the invoker was enabled by default. However, a security flaw was recently uncovered whereby the invoker servlet could be used to see the source code of servlets that were generated from JSP pages. Although this may not matter in most cases, it might reveal proprietary code to outsiders, so, as of Tomcat 4.1.12, the invoker was disabled by default. We suspect that the Jakarta project will fix the problem soon and reenable the invoker servlet in upcoming Tomcat releases. In the meantime, however, you almost certainly want to enable it when learning. Just be sure that you do so only on a desktop development machine that is not accessible to the outside world.
To enable the invoker servlet, uncomment the following servlet-mapping element in install_dir /conf/web.xml . Note that the filename is web.xml , not server.xml , and do not confuse this Tomcat-specific web.xml file with the standard one that goes in the WEB-INF directory of each Web application.
<servlet-mapping> <servlet-name>invoker</servlet-name> <url-pattern>/servlet/*</url-pattern> </servlet-mapping>
Increasing DOS Memory Limits
If you use an old version of Windows (i.e., Windows 98/Me or earlier), you may have to change the DOS memory settings for the startup and shutdown scripts. If you get an "Out of Environment Space" error message when you start the server, you will need to right-click on install_dir /bin/startup.bat , select Properties, select Memory, and change the Initial Environment entry from Auto to at least 2816. Repeat the process for install_dir /bin/shutdown.bat .
In some cases, it is also helpful to set the CATALINA_HOME environment variable to refer to the base Tomcat installation directory. This variable identifies the location of various Tomcat files to the server. However, if you are careful to avoid copying the server startup and shutdown scripts and instead use only shortcuts (called "symbolic links" on Unix) instead, you are not required to set this variable. See Section 2.9 (Establish a Simplified Deployment Method) for more information on using these shortcuts.
Testing the Basic Server Setup
To verify that you have configured Tomcat successfully, double-click on install_dir /bin/startup.bat (Windows) or execute install_dir /bin/startup.sh (Unix/Linux). Open a browser and enter http://localhost/ ( http://localhost:8080/ if you chose not to change the port to 80). You should see something similar to Figure 2-1. Shut down the server by double-clicking on install_dir /bin/shutdown.bat (Windows) or executing install_dir /bin/shutdown.sh (Unix). If you cannot get Tomcat to run, try going to install_dir /bin and typing catalina run ; this will prevent Tomcat from starting a separate window and will let you see error messages such as those that stem from the port being in use or JAVA_HOME being defined incorrectly.
Figure 2-1. Tomcat home page.
After you customize your development environment (see Section 2.7), be sure to perform the more exhaustive tests listed in Section 2.8.