table of contents

Apache Tomcat 6 Tutorial

Configuration Details

For most people, the easiest way to get started with Tomcat is to use a preconfigured version as described in these links:

However, if you want to customize the configuration, this page provides more details.

Executive Summary


Configuration Details

Configuring Tomcat involves four main steps and three optional steps:

  1. Downloading the Tomcat software.
  2. Setting the JAVA_HOME variable.
  3. Changing the port from 8080 to 80.
  4. Telling Tomcat to reload servlets when they are modified.
  5. Enabling the invoker servlet.
  6. Turning on directory listings.
  7. Using the Windows .exe installer instead of the .zip file. (Not Recommended)

Details of each step are given below. If Tomcat is already running, restart it after performing these steps.

1. Download the Apache Tomcat Software

Go to http://tomcat.apache.org/download-60.cgi and download and unpack the zip file for the current release build of Tomcat 6. You specify the top-level directory (e.g., C:\) and the zip file has embedded subdirectories (e.g., apache-tomcat-6.0.10). Thus, C:\apache-tomcat-6.0.10 is a common resultant installation directory. Note: from this point forward, I'll refer to that location as install_dir. For Windows, there is also a .exe installer; I prefer the .zip file, but see the .exe installer section for notes on the differences between the two.

Alternatively, you can use my preconfigured Tomcat version:

This preconfigured version already has the port changed to 80, servlet reloading enabled, and the invoker servlet turned on. It also comes with a sample development directory, sample autoexec.bat file, startup/shutdown shortcuts, and shortcuts for deploying applications.

2. Set the JAVA_HOME Variable

Next, you must set the JAVA_HOME environment variable to tell Tomcat where to find Java. Failing to properly set this variable prevents Tomcat from compiling JSP pages. This variable should list the base JDK installation directory, not the bin subdirectory. For example, on almost any version of Windows, if you use JDK 1.6, you might put the following line in your C:\autoexec.bat file.

  set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_10

On Windows XP, you could also go to the Start menu, select Control Panel, choose System, click on the Advanced tab, press the Environment Variables button at the bottom, and enter the JAVA_HOME variable and value directly. On Windows 2000 and NT, you do Start, Settings, Control Panel, System, then Environment. However, you can use C:\autoexec.bat on those versions of Windows also (unless a system administrator h as set your PC to ignore it).

3. Change the Port to 80

Assuming you have no other server already running on port 80, you'll find it convenient to configure Tomcat to run on the default HTTP port (80) instead of the out-of-the-box port of 8080. Making this change lets you use URLs of the form http://localhost/blah instead of http://localhost:8080/blah. Note that you need admin privileges to make this change on Unix/Linux. Also note that some versions of Windows automatically start IIS on port 80. So, if you use XP and want to use port 80 for Tomcat, you may need to disable IIS (see the Administrative Tools section of the Control Panel).

To change the port, edit install_dir/conf/server.xml and change the port attribute of the Connector element from 8080 to 80, yielding a result similar to that below.

   <Connector port="80" protocol="HTTP/1.1" 
              ... >

You can also:

4. Turn on 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 every time you recompile a servlet that has already been loaded into the server's memory. Since this tutorial discusses the use of Tomcat for development, this change is strongly recommended.

To turn on servlet reloading, edit Edit install_dir/conf/context.xml and change

  <Context>

to

  <Context reloadable="true" privileged="true">

Note that the privileged entry is really to support the invoker servlet (see the following section), so you can omit that entry if you do not use the invoker.

You can also:

5. Enable the Invoker Servlet

The invoker servlet lets you run servlets without first making changes to your Web application's deployment descriptor (i.e., the WEB-INF/web.xml file). Instead, you just drop your servlet into WEB-INF/classes and use the URL http://host/servlet/ServletName (or http://host/webAppName/servlet/ServletName once you start using your own Web applications. The invoker servlet is extremely convenient when you are learning and testing out various APIs. You almost certainly want to enable it when learning, but you should disable it again before deploying any real applications.

To enable the invoker servlet, uncomment the following servlet and servlet-mapping elements in install_dir/conf/web.xml. Do not confuse this Apache Tomcat-specific web.xml file with the standard one that goes in the WEB-INF directory of each Web application.

    <servlet>
        <servlet-name>invoker</servlet-name>
        <servlet-class>
          org.apache.catalina.servlets.InvokerServlet
        </servlet-class>
        ...
    </servlet>
    ...
    <servlet-mapping>
        <servlet-name>invoker</servlet-name>
        <url-pattern>/servlet/*</url-pattern>
    </servlet-mapping>

In Tomcat 6 (but not Tomcat 5.5), you also need the privileged="true" entry in the Context element of context.xml. See the previous section for an example.

You can also:

6. Turn on Directory Listings (Optional)

In previous Tomcat versions, if you entered a URL ending in a slash (/) and there was no welcome-file in the directory (or servlet-mapping that matched the URL), Tomcat displayed a directory listing. In Tomcat 6, the default was changed from true to false for these directory listings. Many developers find it convenient to turn directory listings back on. To make this change, edit install_dir/conf/web.xml and change the init-param value of listings for the default servlet, as below. Do not confuse this Apache Tomcat-specific web.xml file with the standard one that goes in the WEB-INF directory of each Web application.

    <servlet>
        <servlet-name>default</servlet-name>
        <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
        <init-param>
            <param-name>debug</param-name>
            <param-value>0</param-value>
        </init-param>
        <init-param>
            <param-name>listings</param-name>
            <param-value>true</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

You can also:

7. Using the Windows .exe Installer

If you are using Microsoft Windows, you can download a .exe installer instead of the .zip file discussed in this tutorial. In my opinion, it is not worth the bother to do so, but some people like it. If you use it, note these differences:

  • It will prompt you for the desired port. It will ask you what port it should run on, and make the changes in server.xml for you. You will still need to manually edit context.xml and web.xml, however.
  • It will set JAVA_HOME for you. The installer hunts for your Java installation and tries to set JAVA_HOME appropriately. This is a convenience, albeit a minor one.
  • It will setup Start Menu entries. In particular, instead of using startup.bat and shutdown.bat, you can go to the Start Menu, select Apache Tomcat 6.0, select Monitor Tomcat, and select Start or Stop, as shown below. I prefer startup.bat and shutdown.bat so that I can put shortcuts in my development directory (easier to invoke) and/or the desktop (where I can associate keyboard shortcuts).

    Tomcat 5 Monitor


More Information

Online documentation