Before you do anything, you need to decide what version of Tomcat you want to run. Consider the following factorys.

If your OS distribution comes with a Tomcat distro of a version that you're satisfied with (or if your organization provides one), then you could simplify your life by using that... or not. Otherwise, go to http://jakarta.apache.org and download the latest stable (non-alpha and non-beta) core binary of desired major version. Just get the one Core file in the file format that you want (For UNIX users, I recommend using that tar.gz format intead of the zip. Otherwise you will need to make the script files executable). For version 5.0.x, get just the core download, which contains the Manager and Admin web apps, and documentation. For version 5.5.x, get the core download, which contains the Manager web app and docs; plus the Admin download if you want to run the Admin web app; and the JDK 1.4 Compat download if you plan to use Java version 1.4. (If you don't run the Admin web app, you will need to edit the server.xml file manually for every configuration change to the Tomcat server).

The Deployer download is not needed for a server install. This is not the Manager webapp, but a Java client for the Manager webapp. You install this on a workstation or server where you will run ant to deploy to the remote Tomcat server. (Not that you necessarily want to do that. It's overkill if you will only be deploying locally, and there are other ways to deploy remotely).

If you're using preconfigured packages, install them. Besides the base package, install packages for standalone docs, admin and manager webapps, samples webapp and docs webapp if you want them. It's a hard call whether to use OS-supplied Tomcat packages. The benefit is, upgrades are a snap, and can be automated, and, best of all, if your OS has packages for Apache HTTPD and a Tomcat plugin, 99% of the plugin setup is done for you.

You won't understand much of this document if you don't have a clear understanding of installation and instance.

A Tomcat installation is one set of all the stuff that you extract from a Tomcat distribution (or packages, rpms, etc.). You could very well have multiple installations on the same server, for example, a Tomcat 5.5.9 installation and a Tomcat 5.0.28 installation. There is no good reason to have multiple installations of the exact same Tomcat distribution, since you can run as many Tomcat instances as you want using one Tomcat installation. The env variable CATALINA_HOME identifies the tomcat installation root directory for the current environment.

A tomcast instance is a single Tomcat JVM (and also the set of files specific to this tomcat instance). People often use the word server for the same purpose. I try to use the word instance to avoid any ambiguity with the other uses of server. The env variable CATALINA_BASE identifies the tomcat instance's root directory for the current environment.

The file conf/server.xml for each CATALINA_BASE is where most of your instance-based configurations are persisted, for example what port to run on, where to write log files, etc. The primary goal of the Admin webapp is to manage this file (but most people edit it it manually instead). Because of its importantce, you should take some time to study it. The Tomcat documentation explains about half of it well. The XML tags and attributes are named pretty intuitively. One question that most people have when they look at it is, What are all of those ports for?. There is the main http port that will server your webapps to browsers, SOAP clients, etc. There is the Coyote port that will service plugin clients. The AJP protocol is used between plugins and Tomcat, so you can't use it for any other purpose. There's also the shutdown port. You can telnet to this port on localhost, type SHUTDOWN and hit ENTER to shut down the instance. Then there are SSL versions of these three ports (all of which care commented out by default).

I recommend that you install the distro as the super-user, and leave everything from the distributions writable only to the superuser. After that you copy the small set of read-write files and open up write privileges for this set. This directory branch of instance-specific, writable, files is called the CATALINA_BASE for the instance. This is useful for a single-user system because when Tomcat gets screwed up (as it eventually will), it is very easy to start a new instance up (with its own CATALINA_BASE), or just wipe out your hosed CATALINA_BASE with a new copy from the distro. If you plan to run multiple Tomcat instances (for yourself or to be shared), then you definitely should use CATALINA_BASEs.

If you have superuser privileges, I recommend that you run your Tomcat instance as a dedicated non-privileged user. Unless you already have a tomcat account, create a user and group with name "tomcat".

cd to the parent directory of where you want your Tomcat installation to live (parent directory because the extraction will create one subdirectory which will contain everything). Extraction will create a new subdirectory with name like jakarta-tomcat-5.0.28. If you are installing 5.5.x, extract the Admin distro file from the same place (if you want the Admin web app). After you extract everything, you can shorten the installation root directory name if you like (I get along just fine without the "jakarta-" part). A common practice on UNIX is to make a peer sym-link to the "current" version with no version number in it, like

    mv jakarta-tomcat-5.0.28 tomcat-5.0.28
    ln -s tomcat-5.0.28 tomcat

Your CATALINA_HOME contains the following subdirectories.

Users installing the 5.5.x JDK 1.4 Compatibility distro should be aware that (at least for the versions I have installed), they use a different root directory name for the Compat bunlde, so you can't just overlay it on top of your core installation (like you can with the Admin distro). You'll need to extract the JDK Compat distro to a temporary location then copy it like so.

    mkdir /tmp/tctemp
    cd /tmp/tctemp
    tar -xzvf /path/to/jakarta-tomcat-5.5.28-admin.tar.gz
    ...
    cd jakarta-tomcat-5.5.28-admin
    cp -a * $CATALINA_HOME
    ...
    cd
    rm -rf /tmp/tctemp

I recommend that you edit the web.xml for the bundled default ROOT web app. to make your site home page editable. If you will always install your own ROOT web app (i.e., a web app with context root of "/"), or will otherwise never use Tomcat's default ROOT web app, just skip this paragraph. Tomcat comes with a great default web app, with a great home page with links to the bundled web apps and documentation. It just makes sense to add your own links to this home page-- at least to the web apps that you install, but also perhaps to application log file or external documentation. Unfortunately, recent versions of Tomcat precompile the home page JSP so that you editing the home page will have no effect. The easy work-around for this is to edit the file CATALINA_HOME/webapps/ROOT/WEB-INF/web.xml and just comment out the <servlet> and <servlet-mapping> stanzas at the bottom. This is a one-time customization. Whenever you set up a CATALINA_BASE from now on (as described below), the home page for the instance will be editable.

As described above, CATALINA_HOME is where you installed the Tomcat distribution to. CATALINA_BASE will be the root directory of your new instance. Now make the CATALINA_BASE for your first (or only) Tomcat instance by making a new CATALINA_BASE directory anywhere. If you anticipate running multiple Tomcat instances, you may want to make a new directory to be the parent to all of the instances, then make the CATALINA_BASE within that. For example .../tomcat-intances/balder1. For the purposes of my examples, I'll assume that you set the variable CATALINA_BASE to the absolute path of this directory. Copy the five starred CATALINA_HOME subdirectories above to there. Then set ownership to your instance owner and group. Assuming that you've set variables CATALINA_HOME and CATALINA_BASE, you can do it like this on UNIX.

    mkdir $CATALINA_BASE
    cd $CATALINA_HOME
    cp -a conf logs temp webapps work $CATALINA_BASE
    chown -R tomcat.tomcat $CATALINA_BASE

    mkdir %CATALINA_BASE%
    cd %CATALINA_HOME%
    xcopy /e /i /q conf %CATALINA_BASE%\conf
    xcopy /e /i /q logs %CATALINA_BASE%\logs
    xcopy /e /i /q temp %CATALINA_BASE%\temp
    xcopy /e /i /q webapps %CATALINA_BASE%\webapps
    xcopy /e /i /q work %CATALINA_BASE%\work

One difficulty you will have to live with if you're using Linux Tomcat packages is, the actual instance files are spread out all over the place, with sym-links from the CATALINA_BASE. It's not all that difficult if you leave the default CATALINA_BASE alone to use as a model. For example, on Suse, it sets up a CATALINA_BASE named base with CATALINA_BASE of /srv/www/tomcat5/base. This CATALINA_BASE has sym-links to a config file under /etc, log, temp, and work directories under /var, but a real webapps directory. Duplicate the same exact setup for your own instance, like /srv/www/tomcat5/yourinstance.

Make the webapps directory writable to whoever you want to permit to deploy by copying files into there.

    chown -R deployer $CATALINA_BASE/webapps
    chmod gw+s $CATALINA_BASE/webapps

If you followed my advice above, then you just repeat the CATALINA_BASE creation step above for each instance, then edit the server.xml file as described in the following subsection.

The Tomcat documentation says that you must edit the descriptors for the bundled webapps. That documentation is wrong, because the settings use filepaths relative to CATALINA_BASE, which works exactly as needed.

Dear reader, please make a detour now and read the introductory and Initial Instance Configuration sections of the Configuring Tomcat chapter. You really need to understand that material before consuming the remainder of this chapter.

Generally, you want to bundle needed jar files in your web app. That will avoid most dependency conflicts with other web apps, and reduces dependencies on things outside of the war file. For example, it won't matter if Tomcat or other web apps have the right version of a lib, because you have it yourself. It also means that your war will be more likely to run as-is on some other application server. The trade off is inefficiency of disk space and memory, when multiple wars bundle equivalent jar files. The inefficiency problems are trivial compared to the alternative.

Exceptions to the general rule are for the mail api and JDBC drivers. In both cases, the exceptions are justified only so that you can manage the mail and data source services as the app server level as shared resources. With Tomcat 5.5.x only, Tomcat doesn't bundle the email libraries because of copyright laws. (Ignore the rest of this paragraph if you're running a version an earlier version, since it will include these two jar files). Therefore, obtain the JavaMail and Activation Framework jars and copy them into CATALINA_HOME/common/lib. These jar files are often named mail.jar or mailapi.jar and activation.jar or jaf.jar correspondingly (or the same with version numbers).

The other exception is JDBC drivers. In the J2EE world, application servers have the responsibility of managing data sources which apps look up via JNDI. Therefore, if you are going to get your data sources by the traditional J2EE method, you need to put your JDBC driver jar files for your target database servers into CATALINA_HOME/common/lib. If you are not getting your datasources from a JNDI lookup (regardless of whether there is an ORM, Spring, or any other lay in between), then I recommend that you bundle your JDBC libraries with your app (for the reasons given above) and purposefully do not put them in any shared directory.

(If Tomcat is running when you change any files under CATALINA_HOME/common/lib, you will need to restart Tomcat for it to see the changes).

At least with Tomcat 4.x, Tomcat does not recognize zip files in the the global lib directories, only .jar files. This isn't much of an issue nowadays since Oracle, the last holdout, has finally stopped using zip files when they should be using jar files.

I assume you're using an Apache HTTPD server (including branded Apache HTTPD servers, such as those by IBM and Oracle). If you're using some other web server, like IIS, you're on your own. I'm only documenting use of jk. Setup of other plugins is similar, but jk has the widest user base (by far), and is actively supported. The Apache HTTPD server is often just called the Apache server, even though Apache also makes the Tomcat server. To try to avoid this ambiguity without being too verbose, when I say httpd server in this section, I mean the Apache HTTPD server.

Use pre-packaged binary distributions if at all possible, due to dependency requirements, which are detailed below.

Tomcat calls a network listener which connects clients to the Tomcat engine a Connector. (They probably want to avoid possible confusion with lifecycle listeners, which are defined with <Listener> tags in the server.xml> file).

To get a possible point of confusion out of the way, be aware that all of the modern Tomcat connectors are Coyote connectors. All of the connectors you use will be Coyote connectors. (The SHUTDOWN network listener is not a Connector, since it does not connect to any Tomcat engine). Most significantly, when I speak of an HTTP connector or an AJP connector, I mean the Coyote HTTP or Coyote AJP connector, not some other, deprecated implementation. I point this out because this was apparently not the case in the past, since Tomcat documentation and config file comments imply some significance to "Coyote".

Use of a Webapp Staging Directory avoids polling race condition problems if you deploy webapps by manually copying or moving files into the Tomcat webapps directory.

The problem occurs because Tomcat monitors the webapps directory and the first time it sees a new entry, it decides right then whether it will henceforth consider this entry a war file, a web app directory, or ignore it.

If it looks at the directory or war file before it contains the web.xml file (because the copy has not reached that point yet), then it won't attempt to deploy it at all and will ignore the whole thing from this point forward.

If it sees the web.xml, then it will attempt to deploy. If your copy has not finished, it will deploy only a portion of your webapp and will never finish it.

The solution to this problem is to not copy anything into the webapps directory, but to move to there from the same filesystem partition. From Tomcat's perspective, the move is an atomic operation. Before the move completes, it won't see the new item at all. After the move completes, the entire webapp is available for deployment.

The only real requirement for this to work is that you move the webapps/war from another directory in the same filesystem partition. If you work with multiple servers, then I highly recommend that you make a staging directory right under webapps specificaly for this purpose. For purposes of this document, I'll assume it is $CATALINA_BASE/webapps/stage. No matter what server you're on, you'll know that the staging directory is in the same partition as webapps, and it's really convenient to be able to cd to webapps and deploy and undeploy web applications with short commands like

    cd $CATALINA_BASE/webapps
    mv appToUndeploy stage
    mv warToUndeploy stage
    mv stage/appToDeploy