Configuring & Using Apache Tomcat

A Tutorial on Installing, Configuring, and Using
Tomcat for JSF or Servlet and JSP Development.
Includes Eclipse integration.

This tutorial is a guide to installing and configuring Apache Tomcat 6 or 7 for use as a standalone Web server (for development) that supports JSF 2 or servlets and JSP. If you find these free tutorials helpful, we would appreciate it if you would link to us. Send corrections or feedback on any tutorial to hall@coreservlets.com.

Quick Start Guide

I strongly recommend that you use Tomcat inside Eclipse instead of trying to manually deploy apps and start/stop Tomcat. The time it takes to download the IDE and learn the bare bones basics of use will be quickly made up for by the simplification in development, debugging, and deployment. A quick summary is given below; for details please see the tutorials on Tomcat 7 with Eclipse or Tomcat 6 with Eclipse.

Tomcat 7 with Eclipse (Details here)
Recommended for Most Developers		 Tomcat 6 with Eclipse (Details here)
Old! Only if Servlet 2.5/2.4 Compatibility Needed		 Manual Tomcat 6 Execution (Details here)
Not recommended
  1. Install Java. Make sure you have Java 7 or Java 6 installed.
  2. Unzip Tomcat. Unzip tomcat-7.0.34-preconfigured.zip.
  3. Download Eclipse 3.8 (Juno). Install the Java EE version of Eclipse 3.8.
  4. Tell Eclipse about Tomcat. Start Eclipse and go to the Workbench. Click on Servers tab at bottom. R-click, New, Server, Apache, Tomcat v7.0, navigate to Tomcat installation folder (e.g., C:\apache-tomcat-7.0.34), OK.
  5. Test the server. Test Tomcat within Eclipse. Details here.
  6. Adjust Eclipse preferences. Point at your JDK: Window, Preferences, Java, Installed JREs, make sure a JDK (not JRE) is selected. If not, click Add and point at the install location of your JDK. Suppress unnecessary warnings about serialized classes: Window, Preferences, Java, Compiler, Errors/Warnings, change "Serializable class without ..." to "Ignore". Many other personal preferences re font size, indentation style, etc.
  1. Install Java. Make sure you have Java installed.
  2. Unzip Tomcat. Unzip tomcat-6.0.28-preconfigured.zip.
  3. Download Eclipse. Install the Java EE version of Eclipse.
  4. Tell Eclipse about Tomcat. Start Eclipse and go to the Workbench. Click on Servers tab at bottom. R-click, New, Server, Apache, Tomcat v6.0, navigate to Tomcat installation folder (e.g., C:\apache-tomcat-6.0.28), OK.
  5. Test the server. Test Tomcat within Eclipse. Details here.
  6. Adjust Eclipse preferences. Point at your JDK: Window, Preferences, Java, Installed JREs, make sure a JDK (not JRE) is selected. If not, click Add and point at the install location of your JDK. Suppress unnecessary warnings about serialized classes: Window, Preferences, Java, Compiler, Errors/Warnings, change "Serializable class without ..." to "Ignore". Many other personal preferences re font size, indentation style, etc.
  1. Install Java. Make sure you have Java installed. Details here.
  2. Unzip Tomcat. Unzip tomcat-6.0.28-preconfigured.zip into the top level of the C drive. Details here.
  3. Set JAVA_HOME. Set this environment variable to point at the top-level of your Java installation directory (e.g., C:\Program Files\Java\jdk1.6.0_21). Use the Control Panel or see this sample autoexec.bat file. Details here.
  4. Set CLASSPATH. Set this environment variable to include ".", C:\Servlets+JSP, and the servlet/JSP JAR files. Use the Control Panel or see this sample autoexec.bat file. Details here.
  5. Test the server. Make sure you can start/stop the server. Test some sample HTML files, JSP pages, and servlets. Details here.
You can find details on customizing the Tomcat configuration here. For information on commercial Web hosting providers that support Tomcat, see the JSP hosting page.

Overview

Using Tomcat as a deployment server or integrating Tomcat as a plugin within the regular Apache server or a commercial Web server is more complicated than what is described in this tutorial. Although such integration is valuable for a deployment scenario (see http://tomcat.apache.org/tomcat-7.0-doc/), my goal here is to show how to use Tomcat as a development server on your desktop to use for testing when building applications that use JSF 2, servlets/JSP, or other Java-based dynamic Web technologies. Regardless of what deployment server you use, you'll want a standalone server on your desktop to use for development. By far the best way to use Tomcat for development purposes is from inside Eclipse or another IDE. For that, please see the Eclipse and Tomcat 7 integration tutorial or the Eclipse and Tomcat 6 integration tutorial. For using Tomcat manually (not recommended), see the section below.

The examples here assume you are using Windows, but they can be easily adapted for MacOS, Linux, Solaris, and other versions of Unix. Except when I refer to specific Windows paths (e.g., C:\blah\blah), I use URL-style forward slashes for path separators (e.g., install_dir/webapps/ROOT). Adapt as necessary.

To report errors or omissions in this writeup or to inquire about customized on-site training courses on JSF 2, Ajax, jQuery, Android development, Java 7 or 8 programming, Hadoop, Spring, Hibernate, GWT, HTML5, RESTful Web Services and other Java-related technologies, please contact Marty Hall at hall@coreservlets.com.

If you find these free tutorials helpful, we would appreciate it if you would link to us.

Manual Tomcat 6 Execution: Details

Here are more details on using the preconfigured Tomcat 6 version for direct (manual) execution. Please note that I strongly recommend that you use Tomcat within Eclipse instead of executing Tomcat by hand as described here. Whether you run Tomcat within Eclipse or do it manually, you can also customize the Tomcat configuration.
  1. Unzip Tomcat. Unzip tomcat-6.0.28-preconfigured.zip into the top level of the C drive. This should result in C:\apache-tomcat-6.0.28\. This preconfigured version of Tomcat has the following settings already in place. For details on customizing this configuration, please see the detailed configuration guide.
    • The port is changed from 8080 to 80. This lets you enter URLs of the form http://localhost/... instead of http://localhost:8080/....
      • When you download Tomcat from the Apache site, the port is 8080 in case you have another server running on port 80.
    • Servlet reloading is enabled. This lets you deploy a modified servlet .class file without restarting the server.
      • When you download Tomcat from the Apache site, servlet reloading is disabled for performance reasons. You might want it disabled on a server used for a deployed application, but you definitely want it enabled during development.
    • The invoker servlet is enabled. This lets you drop a servlet .class file into webapps/appName/WEB-INF/classes/packageName and immediately run it with a URL of the form http://localhost/appName/servlet/packageName.ServletName. That is, the invoker servlet saves you from editing web.xml to give a servlet-mapping to your servlet.
      • When you download Tomcat from the Apache site, the invoker servlet is disabled. You DEFINITELY want the invoker servlet disabled on a server used for a deployed application, but having it enabled on your development server is very convenient for quick testing.
    • Tomcat monitors struts-config.xml and faces-config.xml. Whenever either of these files changes, Tomcat automatically reloads the Web application. This saves you from restarting the server when you change these files.
      • If you do not use Struts or JSF, this change will not be beneficial to you. But it does not hurt either way.
    • Directory listings are turned on. If you type a URL ending in / and there is no welcome file in that folder, Tomcat shows a directory listing.
      • Directory listings were on by default in previous Tomcat versions. They are not required but are convenient during development.
  2. Set JAVA_HOME. Set this environment variable to point at the top-level of your Java installation directory (e.g., C:\Program Files\Java\jdk1.6.0_21.) Use the Control Panel, see the sample autoexec.bat file, or read this section of the page on configuring your development environment.
  3. Set CLASSPATH. Set this environment variable to include ".", C:\Servlets+JSP, and the servlet/JSP JAR files. For details, see the sample autoexec.bat file or this section of the page on configuring your development environment.

For a very quick test, open C:\Servlets+JSP, double click on the shortcut to startup.bat, and open http://localhost/ in your browser. If you see something about Tomcat, the setup was successful. But be sure to do the more complete server tests to verify that you have your development and deployment environment also set up properly.

More Information

Java

JSF (JavaServer Faces)

Servlets & JSP
Ajax, GWT, & JavaScript

Spring, Hibernate, & JPA

Struts