This document is available in several formats.

You may be reading this document right now at http://admc.com/blaine/howtos/tomcat, or in a distribution somewhere else. I hereby call the document distribution from which you are reading this, your current distro.

http://admc.com/blaine/howtos/tomcat hosts the latest versions of all available formats. If you want a different format of the same version of the document you are reading now, then you should try your current distro. If you want the latest version, you should try http://admc.com/blaine/howtos/tomcat.

Sometimes, distributions other than http://admc.com/blaine/howtos/tomcat do not host all available formats. So, if you can't access the format that you want in your current distro, you have no choice but to use the newest version at http://admc.com/blaine/howtos/tomcat.

I'm writing this document because I pity the huge number of people who waste tons of time (1) trying to learn how to use Tomcat effectively without any guide to tell then which of the reams of Tomcat documentation is meaningful for typical use; and (2) trying to find out what is going wrong when they run into any of the many Tomcat bugs and quirks.

It takes a lot of time to assemble a document like this, but, considering that I get asked questions about Tomcat use continuously, I may just end up netting a net savings on my time by writing this.

First off, if you have a running Tomcat instance, install the Tomcat documentation web app if you haven't already. The API specs are great for development. The user and configuration docs will sometimes have what you need, but it seems that they always explain only one narrow example of each issue, and leave all other setups entirely unaddressed.

There are lots of forums out there for Tomcat. Unfortunately, one of the main reasons I'm writing this document is, about 90% of the time when I search for help about a Tomcat bug or quirk, more often than not I find a bund of people who have the same question I have (on mailing lists and forums), and either no answers, evasions by Tomcat developers, or wild guesses by ignorant people trying to be helpful.

If you want my personal help, email me at blaine.simpson@admc.com. If you want hours of my time, I'm available for contractual work. I can set up integrated shared development, staging, and production environments with CVS/Subversion/RCS, database, ant builds, etc., complete with hardcopy and online manuals (similar in format to what you are reading). I also like to give classroom instruction on lots of Java topics, including Tomcat.

I cover the 5.0.x and 5.5.x series of Tomcat, unless otherwise specified. I usually use the 5.0 series if I have to use Java 1.4, because I find that 5.5 is unstable when run with the 1.4 Compatibility add-on (at least with large and/or troublesome web apps). If you're running Tomcat 4.0 (or earlier), I suggest that you spend your time migrating to a better version instead of wasting time working around limitations and bugs that have already been fixed. I have personally experienced the extreme pain involved when trying to limp along with an ancient version of Tomcat many times. Besides the Jakarta community ignoring your support needs, limitations, and bugs, the old Tomcats have dependences upon old versions of third party libraries (like Jakarta commons, log4j, XML, etc.), and this leads, all too often, to the most frustrating kind of library conflicts. If you are are required to use some tool that requires some old version of Tomcat, then your problem is a sucky tool. In that case, I recommend that you ignore the recommendations of the crappy tool vendor and spend a little time installing a new Tomcat distro and maybe packing some legacy libraries in with your tool to make it run.

If you change a minor version, just shut down your instances, set CATALINA_HOME to your new Tomcat installation, and start up your instances.

If you are changing a major version, e.g., changing from a 5.0.x to 5.5.x or 4.x, then you need to convert your configuration files. Start with a fresh set of config files from the new distribution and merge in customizations from your old configuration files.