Appendix A: Installing Tomcat 4.0

---

In this appendix we'll discuss the basics of how to install and configure Tomcat 4.0, the latest version of the open source JSP and Servlet Reference Implementation.

Installing Tomcat 4.0

While there are many servlet and JSP engines available (as of this writing, Sun's "Industry Momentum" page at http://java.sun.com/products/jsp/industry.html lists nearly 40), we have chosen to focus our attention on Tomcat 4.0. Tomcat is produced by the Apache Software Foundation's Jakarta project, and is freely available at http://jakarta.apache.org/tomcat/.

As Tomcat is primarily used by programmers, its open source development model is of particular benefit as it brings the developers and users close together. If you find a bug, you can fix it and submit a patch. If you need a new feature, you can write it yourself, or suggest it to the development team.

Tomcat is also the reference implementation of the JSP and Servlet specifications, version 4.0 supporting the latest Servlet 2.3 and JSP 1.2 versions. Many of the principal developers are employed by Sun Microsystems, who are investing considerable manpower into ensuring that Tomcat 4.0 provides a high-quality, robust web container with excellent performance.

A Word on Naming

The naming of Tomcat 4.0 components can be a little confusing, with the names Tomcat, Catalina, and Jasper all flying around. So, to avoid any problems with terminology:

• Catalina is a servlet container - that is, an environment within which Java servlets can be hosted.

• Jasper is the JSP component of Tomcat - in fact, it's just a servlet that understands how to process requests for JSP pages.

• Tomcat comprises Catalina, plus Jasper, plus various extra bits and pieces including batch files for starting and stopping the server, some example web applications, and mod_webapp.

• mod_webapp is the component that will allow you to connect Tomcat to the Apache web server. Catalina includes a web server of its own, but you may also wish to connect it to an external web server to take advantage of Apache's extra speed when serving static content, or to allow you to run JSP or servlet-based applications alongside applications using other server-side technologies such as PHP. As of this writing mod_webapp is in beta testing, but expect it to become stable soon. In time, connectors for other major web servers should also appear.

Basic Tomcat Installation

These steps describe installing Tomcat 4.0 on a Windows 2000 system, but the steps are pretty generic; the main differences between platforms will be the way in which environment variables are set:

• You will need to install the Java 2 Platform, Standard Edition software development kit, if you have not already done so. JDK 1.3 can be downloaded from http://java.sun.com/j2se/1.3/.

• Download a suitable Tomcat 4.0 binary distribution from (for example, jakarta-tomcat-4.0.1.zip from http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.0.1/bin/) and unzip it into a suitable directory.

• On Windows 2000 you have the alternative of downloading a Windows installer, jakarta-tomcat-4.0.1.exe, and simply double-clicking its icon. Note that installing Tomcat 4 as a Windows service is as easy as ticking a box.

• Create CATALINA_HOME and JAVA_HOME environment variables pointing to the directories where you installed the Tomcat and Java 2 SDK files. Typical values are C:\jakarta-tomcat-4.0.1 for CATALINA_HOME and C:\jdk1.3 for JAVA_HOME.

Under Windows 2000, environment variables are set using the System control panel. On the Advanced tab, click on the Environment Variables... button. In the resulting dialog box, add CATALINA_HOME and JAVA_HOME as system variables:

These environment variables allow Tomcat to locate both its own files (using CATALINA_HOME), and the Java 2 SDK components it needs, notably the Java compiler, (using JAVA_HOME).

If you are using Windows 98, environment variables are set by editing the C:\autoexec.bat file. Add the following lines:

    set CATALINA_HOME=C:\jakarta-tomcat-4.0.1    set JAVA_HOME=C:\jdk1.3 

Under Windows 98 you will also need to increase the environment space available, by right-clicking on your DOS prompt window, selecting Properties, going to the Memory tab, and setting the initial environment to 4096 bytes.

Editing the autoexec.bat file doesn't work the same on Windows Me as it does on Windows 95/98. First, you need to start Microsoft System Information. You can use either of the following methods:

• Click Start | Programs | Accessories | System Tools | System Information.

• Click Start | Run, and type msinfo32.exe in the Open box, and then click OK

To create a new entry:

• Select Tools | System Configuration Utility

• Click the Environment tab, and click New

• Enter the appropriate information in the Variable Name and Variable Value boxes, and then click OK

To activate the new environment variable select the corresponding check box for this entry, and restart your computer.

Running Tomcat

Start Tomcat by running the startup.bat batch file (startup.sh on Unix-type systems), which can be found in the <CATALINA_HOME>\bin\ directory (in other words, the bin directory inside the directory where Tomcat is installed). Alternatively, Windows users can run Tomcat from the Start menu. Choose Start | Programs | Apache Tomcat 4 | Start Tomcat.

Tomcat will start up and print some status messages:

If you have installed Tomcat 4.0 as a service on Windows 2000, it is controlled instead by the Services utility within Administrative Tools.

We now have Tomcat 4.0 up and running, using its internal web server (on port 8080). Point your web browser at http://localhost:8080/. You should see the default Tomcat home page:

Spend some time exploring the examples and documentation provided with Tomcat.

To shut down Tomcat, run the shutdown.bat batch file (shutdown.sh on Unix-type systems), again from the <CATALINA_HOME>\bin\ directory. Again, Windows users can accomplish the same task from the Start menu. Choose Start | Programs | Apache Tomcat 4 | Stop Tomcat.

The Tomcat 4.0 Directory Structure

Looking inside our Tomcat installation directory we find a few text files, and various directories:

• bin

  Contains Windows batch files and Unix shell scripts for starting and stopping Tomcat, and for other purposes, together with the bootstrap.jar JAR file needed for the first stage of starting Tomcat.

• classes

  Not created by default, but if it exists any .class files it contains will be visible to all web applications.

• common

  Contains Java code needed by all parts of Tomcat: JAR files in the common\lib\ directory, and .class files in common\classes\. Notable among the JAR files is servlet.jar, which contains the classes defined by the Servlet 2.3 and JSP 1.2 specifications. You will need to have servlet.jar listed in your CLASSPATH environment variable when compiling classes (for example, servlets) that use these APIs.

• conf

  Contains Tomcat's configuration files, notably server.xml (dealt with in the Tomcat 4.0 Configuration section below) and the server-wide web.xml.

  Note that settings in the server-wide web.xml file apply to the whole server, but that this behavior is not mandated by the Servlet specification. Applications making use of it will not be portable to other servlet containers.

• lib

  Populated with various JAR files required by web applications, including parts of the JSP engine. You can add your own JAR files here and they will be visible to all web applications.

• logs

  Contains Tomcat's log files. Logging is configured in server.xml.

• server

  Contains the files comprising Catalina, and other required libraries: JAR files in server\lib\, and .class files in server\classes\.

• src

  Contains the source code for Tomcat, along with the documentation (interspersed with the source code).

• webapps

  The location where Tomcat looks for web applications to deploy. Any WAR file placed here, or any expanded web application directory structure stored within the directory, will automatically be deployed when Tomcat starts up.

  The URL path under which the application is deployed will correspond to the name of the WAR file or directory; for example, if you place a myapplication.war file or a myapplication directory within webapps, Tomcat will automatically deploy it as http://localhost:8080/myapplication/.

  The automatic deployment settings may not suit your application, in which case you may prefer to store the application outside the webapps\ directory and configure it as desired using server.xml.

• work

  Used by Tomcat to store temporary files, notably the .java source files and compiled .class files created when processing JSP pages.

Tomcat 4.0 Configuration

The Tomcat documentation has improved vastly compared to early versions and should be your first stop if you need to configure Tomcat in any way. However, there are a few steps that are sufficiently common that we cover them here.

Deploying a Web Application

There are two ways to tell Tomcat to deploy a web application:

• As mentioned above, you can deploy an application simply by placing a WAR file or an expanded web application directory structure in the webapps directory.

• However, the default settings may not be suitable for your application, in which case it will be necessary to edit <CATALINA_HOME>\conf\server.xml and add a <Context> element for your application.

The default server.xml file is well commented, and you should read these to familiarize yourself with the contents of this file. Various additional elements, not shown or described here but included in the default server.xml, provide for logging and other similar functionality, and define authentication realms. The default server.xml also includes commented-out sections illustrating how to set up a secure (HTTPS) connector, and to set up database-driven authentication realms. It also includes elements that work together with the mod_webapp Apache module.

The outline structure of server.xml is as follows:

    <Server>      <Service>        <Connector/>        <Engine>          <Host>            <Context/>          </Host>        </Engine>      </Service>    </Server> 

At the top level is a <Server> element, representing the entire Java Virtual Machine:

    <Server port="8005" shutdown="SHUTDOWN" debug="0"> 

The <Server> element may contain one or more <Service> elements. A <Service> element represents a collection of one or more <Connector> elements that share a single 'container' (and therefore the web applications visible within that container). Normally, that container is an <Engine> element:

      <Service name="Tomcat-Standalone"> 

A <Connector> represents an endpoint by which requests are received and responses are returned, passing them on to the associated <Container> (normally an <Engine>) for processing. This <Connector> element creates a non-secure HTTP/1.1 connector, listening on port 8080:

        <Connector className="org.apache.catalina.connector.http.HttpConnector"                   port="8080" minProcessors="5" maxProcessors="75"                   acceptCount="10" debug="0"/> 

An <Engine> element represents the Catalina object that processes every request, passing them on to the appropriate <Host>:

        <Engine name="Standalone" defaultHost="localhost" debug="0"> 

The <Host> element is used to define the default virtual host:

          <Host name="localhost" debug="0" appBase="webapps"> 

A <Context> element is used to define an individual web application:

           <Context path="/examples" docBase="examples" debug="0"                    reloadable="true">           </Context> 

The attributes of the <Context> element are:

• path

  Determines the URL prefix where the application will be deployed. In the example above, the application will be found at http://localhost:8080/examples/.

• docBase

  Specifies the whereabouts of the WAR file or expanded web application directory structure for the application. Since a relative file path is specified here, Tomcat will look in its webapps directory (this was configured in the <Host> element, above) but an absolute file path can also be used.

• debug

  Specifies the level of debugging information that will be produced for this application.

• reloadable

  Intimates whether the container should check for changes to files that would require it to reload the application. When deploying your application in a production environment, setting its value to false will improve performance, as Tomcat will not have to perform these checks.

          </Host>        </Engine>      </Service>      <!-- Snip details of service for the mod_webapp connector -->    </Server> 

The Manager Application

Tomcat 4.0's default configuration includes a web application that allows web applications to be deployed, undeployed, and reloaded while Tomcat is running. This application is installed by default in the manager web application, and contains four commands:

• http://localhost:8080/manager/list

  List all web applications currently deployed in this virtual host.

• http://localhost:8080/manager/deploy?path=/myapp&war=mywar

  Deploy the web application specified by the war request parameter, at the context path given by the path parameter.

• http://localhost:8080/manager/reload?path=/myapp

  Reloads all the Java classes in the specified web application. This works even if automatic class reloading is disabled.

• http://localhost:8080/manager/undeploy?path=/myapp

  Shuts down and undeploys the specified web application.

When specifying a web application to the deploy command, the value of the war request path must have one of these forms:

• file:/absolute/directory/path

  The absolute path to the directory containing the unpacked web application

• jar:file:/absolute/path/to/mywar.war!/

  A URL specifying the absolute path to the WAR file

• jar:http://host:port/path/to/mywar.war!/

  A URL specifying the location of the HTTP-accessible WAR file

Before you can use the manager application you need to set up a user in tomcat-users.xml with the role manager:

    <tomcat-users>      <user name="tomcat" password="tomcat" roles="tomcat" />      <user name="role1" password="tomcat" roles="role1" />      <user name="both" password="tomcat" roles="tomcat,role1" />      <user name="admin" password="adminpassword" roles="manager" />    </tomcat-users> 

With this addition, the manager application works just fine:

Getting Help

If you need help with Tomcat 4.0, and this appendix and the documentation just haven't helped, your first port of call should be the Tomcat web site, http://jakarta.apache.org/tomcat/. There are two mailing lists dedicated to Tomcat issues:

• tomcat-user

  This is where you can ask questions on configuring and using Tomcat. The Tomcat developers should be on hand to help out as necessary.

• tomcat-dev

  This is where the developers themselves lurk. If you decide to get stuck in with contributing to improving Tomcat itself, this is where the action is.

B

bin directory, Tomcat 4.0, 5

C

Catalina

• Tomcat 4.0 component, 1

• Tomcat, Catalina and Jasper relationship, 1

classes directory, Tomcat 4.0, 6

common directory, Tomcat 4.0, 6

components

• mod_webapp, Tomcat component, 2

• Tomcat, Catalina and Jasper relationship, 2

conf directory, Tomcat 4.0, 6

Connector> element

• Tomcat 4.0 configuring, 7

Container> element

• Tomcat 4.0 configuring, 7

Context> element

• attributes, 8

• Tomcat 4.0 configuring, 8

D

debug attribute, <Context> element, 8

deploy command

• war request values, configuring Tomcat 4.0, 9

docBase attribute, <Context> element, 8

E

elements

• Connector> element, 7

• Container> element, 7

• Context> element, 8

• Engine> element, 8

• Host> element, 8

• Server> element, 7

• Service> element, 7

Engine> element

• Tomcat 4.0 configuring, 8

environment variables

• Windows 2000 Tomcat installation, 2

• Windows 95 Tomcat installation, 3

• Windows 98 Tomcat installation, 3

• Windows Me Tomcat installation, 3

H

Host> element

• Tomcat 4.0 configuring, 8

J

J2SE (Java 2 Platform, Standard Edition)

• SDK, download web site, 2

Jakarta see Tomcat 4.0.

Jasper

• defined, 2

• Tomcat, Catalina and Jasper relationship, 1

L

lib directory, Tomcat 4.0, 6

logs directory, Tomcat 4.0, 6

M

manager web application, Tomcat 4.0

• commands, 9

mod_webapp

• Tomcat component, 2

P

path attribute, <Context> element, 8

R

references to web sites

• J2SE SDK download, 2

• Sun's Industry Momentum page, 1

• Tomcat 4.0 binary distribution, 2

• Tomcat 4.0 download, 1

• Tomcat 4.0 help, 10

reloadable attribute, <Context> element, 8

S

server directory, Tomcat 4.0, 6

Server> element

• Tomcat 4.0 configuring, 7

Service> element

• Tomcat 4.0 configuring, 7

src directory, Tomcat 4.0, 6

Sun's Industry Momentum page

• web site, 1

T

Tomcat

• mod_webapp, Tomcat component, 2

• Tomcat, Catalina and Jasper relationship, 1

Tomcat 4.0

• binary distribution, download web site, 2

• components names, explaining, 1

• configuring, 7

• deploying web applications, 7

• directory structure, 5

• download, web site, 1

• help is available, 10

• installing, 1

  • generic Windows steps, 2

  • Windows 2000, 2

  • Windows 95/98, 3

  • Windows Me, 3

• manager web application commands, 9

  • manager role setup in tomcat-users.xml, 9

  • war request path values, deploy command, 9

• running on installation, 4

• server.xml default file, elements, 7

• shutting down, 5

Tomcat see also Tomcat 4.0.

tomcat-users.xml, Tomcat 4.0

• manager role setup, 9

W

webapps directory, Tomcat 4.0, 6

work directory, Tomcat 4.0, 6

---