Splitting your Tomcat installation for more power

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 called “Advanced Configuration - Multiple Tomcat Instances”. This describes how to split your Tomcat installation into two directories, the $CATALINA_HOME directory for the Tomcat installation files, and the $CATALINA_BASE directory with the runtime files. Setting these two environment variables when you start up Tomcat controls where the server will look for its files.

The basic idea behind this is that to allow multiple Tomcat server instances to run on the same machine, using a single copy of the Tomcat installation files. There is a single $CATALINA_HOME directory with the installation files, and 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.