• Install the Java JDK. Make sure JDK 1.5 or 1.6 is installed. Download from http://java.sun.com/javase/downloads/. If you plan to execute Tomcat manually, you also need to set your PATH environment variable so that both "java -version" and "javac -help" give a result. The PATH variable is not needed if you use Tomcat within Eclipse. Warning: JDK 1.6.0_21. Eclipse has a bug when used with JDK 1.6.0_21 that causes it to run out of memory and crash. If you use 1.6.0_21, please see the PermGen bug fix page.
• Configure Tomcat. Even if you use Eclipse, you may want to change some of the Tomcat configuration settings. But it is probably simplest to start with the preconfigured version (with Eclipse or for manual deployment), then change the settings shown below later once you have experience with the most basic setup. If you use Eclipse, you need to re-register the server once you change the settings.
  1. Download the 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.0. This tutorial uses Tomcat 6.0.28, but the directions are very similar for any recent Tomcat 6 release.
  2. Set the JAVA_HOME variable. Set it to refer to the base JDK directory, not the bin subdirectory. Not needed if you use Tomcat within Eclipse.
  3. Change the port to 80. Edit install_dir/conf/server.xml and change the port attribute of the Connector element from 8080 to 80.
  4. Turn on servlet reloading. Edit install_dir/conf/context.xml and change <Context> to <Context reloadable="true" privileged="true">.
  5. Enable the invoker servlet. Go to install_dir/conf/web.xml and uncomment the servlet and servlet-mapping elements that map the invoker servlet to /servlet/*.
  6. Turn on directory listings. Go to install_dir/conf/web.xml, find the init-param entry for listings, and change the value from false to true.
• Test the server. Eclipse users should skip this section and instead follow the much simpler instructions in the Tomcat with Eclipse page.
  1. Verify that you can start the server. Double-click install_dir/bin/startup.bat and try accessing http://localhost/.
  2. Check that you can access your own HTML & JSP pages. Drop some simple HTML and JSP pages into install_dir/webapps/ROOT and access them with http://localhost/filename.
• Set up your development environment. Eclipse users should skip this section and instead follow the much simpler instructions in the Tomcat with Eclipse page. This part is only for those that want to edit and deploy manually.
  1. Create a development directory. Put it anywhere except within the Tomcat installation hierarchy.
  2. Make shortcuts to the Tomcat startup & shutdown Scripts. Put shortcuts to install_dir/bin/startup.bat and install_dir/bin/shutdown.bat in your development directory and/or on your desktop.
  3. Set your class path. Use the CLASSPATH environment variable. Include the current directory ("."), the servlet/JSP JAR files (install_dir/lib/servlet-api.jar, and install_dir/lib/jsp-api.jar, and install_dir/lib/el-api.jar), and your main development directory from Step 1.
  4. Bookmark the servlet & JSP javadocs. Add the servlet 2.5 API and the JSP 2.1 API to your bookmarks/favorites list.
• Compile and test some simple servlets. Eclipse users should skip this section and instead follow the much simpler instructions in the Tomcat with Eclipse page.
  1. Test a packageless servlet. Compile a simple servlet, put the .class file in install_dir/webapps/ROOT/WEB-INF/classes, and access it with http://localhost/servlet/ServletName.
  2. Test a servlet that uses packages. Compile the servlet, put the .class file in install_dir/webapps/ROOT/WEB-INF/classes/packageName, and access it with http://localhost/servlet/packageName.ServletName.
  3. Test a servlet that uses packages and utility classes. Compile a servlet, put both the servlet .class file and the utility file .class file in install_dir/webapps/ROOT/WEB-INF/classes/packageName, and access the servlet with http://localhost/servlet/packageName.ServletName. This third step verifies that the CLASSPATH includes the top level of your development directory.

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 you use Eclipse, re-register the server after changing the configuration files.

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.28). Thus, C:\apache-tomcat-6.0.28 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:

• With Eclipse
• For manual execution (no IDE)

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

If you use Tomcat with Eclipse, you can skip this step. However, if you compile and deploy manually, 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 older Windows versions, you might put the following line in your C:\autoexec.bat file.

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

On recent Windows versions, it is generally better to use the Control Panel than to use autoexec.bat. 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.

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:

• Use my preconfigured Tomcat version. Apache Tomcat 6.0.28 with all server.xml, context.xml, and web.xml changes, plus the sample HTML, JSP, and Java files. Right-click or shift-click on the link to download the file.
• Download my modified server.xml for Tomcat 6.0. From Apache Tomcat 6.0.28, but should work on most versions of Tomcat 6.0.

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, and you compile/deploy manually, 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. Note that Eclipse takes care of this for you automatically.

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:

• Use my preconfigured Tomcat version. Apache Tomcat 6.0.28 with all server.xml, context.xml, and web.xml changes, plus the sample HTML, JSP, and Java files. Right-click or shift-click on the link to download the file.
• Download my modified context.xml for Tomcat 6.0. From Tomcat 6.0.18, but should work on most versions of Tomcat 6.0.

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 save your servlet (Eclipse) or drop your servlet into WEB-INF/classes (manual deployment) and use the URL http://host/servlet/ServletName (or http://host/webAppName/servlet/packageName.ServletName once you start using your own Web applications and packages). The invoker servlet is extremely convenient when you are learning and testing out various APIs. You probably 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:

• Use my preconfigured Tomcat version. Apache Tomcat 6.0.28 with all server.xml, context.xml, and web.xml changes, plus the sample HTML, JSP, and Java files. Right-click or shift-click on the link to download the file.
• Download my modified web.xml for Tomcat 6.0. From Tomcat 6.0.28, but should work on most versions of Tomcat 6.0.

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 so that when practicing or during the early project development phases they can simply type in a directory and then click on an HTML or JSP page. 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:

• Use my preconfigured Tomcat version. Apache Tomcat 6.0.28 with all server.xml, context.xml, and web.xml changes, plus the sample HTML, JSP, and Java files. Right-click or shift-click on the link to download the file.
• Download my modified web.xml for Tomcat 6.0. From Tomcat 6.0.28, but should work on most versions of Tomcat 6.0.

If you are using Microsoft Windows and do not use Eclipse or another IDE, you can download a .exe Tomcat installer instead of the .zip file discussed in this tutorial. In my opinion, it is not worth the bother to do so, but some non-Eclipse users 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 set up 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).