The most basic setup of Tomcat involves unzipping the distribution files somewhere on your system, dropping your application into the webapps directory, and firing the server up. This is a fine quick start to run a single app on your own machine, but Tomcat offers a much more powerful way to organize production servers and complex developer setups.

If you read down a ways in the RUNNING.txt file in the tomcat installation bundle, you’ll find a section titled “Advanced Configuration - Multiple Tomcat Instances”. This describes how to split your Tomcat installation into two directories. The $CATALINA_HOME directory holds the unpacked Tomcat binaries downloaded from the Tomcat website. The $CATALINA_BASE directory has the data files for your specific instance of Tomcat. Setting these two environment variables - $CATALINA_HOME and $CATALINA_BASE - when you start up Tomcat controls where the server will look for its various files.

The idea behind this is to split the binary files for a specific version of Tomcat from the data files. This simplifies upgrading the version of Tomcat. It also makes it easy to run multiple Tomcat server instances to run on the same machine, each in their own JVM process, using a single copy of the Tomcat installation files.

Each server instance has its own $CATALINA_BASE directory, with its own set of webapps, configuration files, libraries, and logs. When you upgrade to a newer version of Tomcat, you simply install the files into a new directory and change the $CATALINA_HOME variable to point there when you restart each of your Tomcat servers. You don’t need to touch the server instance files in $CATALINA_BASE.

But this has additional advantages beyond multiple server instances. For one thing, you can have multiple versions of Tomcat installed on the same machine, and then easily switch which version is being used by a particular server instance by changing the $CATALINA_HOME variable for the instance. This is helpful in development, because you can test your application on different versions of Tomcat to ensure compatibility. It helps in production when different applications need different versions of Tomcat, and also for upgrades. When you upgrade to a newer version of Tomcat, you can switch over applications one by one, and if there is a problem, easily switch back.