CATALINA_HOME vs. CATALINA_BASE

I can't find a definitive answer to why Ubuntu would set the CATALINA_BASE environment variable, making it different from CATALINA_HOME. I found this document which suggests that not setting CATALINA_BASE would make it equivalent to CATALINA_HOME. That document also suggests that setting CATALINA_BASE would be done to make multiple instances available.

However, I don't seem to be able to find anything that explains this. Presumably, running with a single CATALINA_HOME has been good for a long time, but Ubuntu switched.

I found this question with an illuminating answer on AskUbuntu but there isn't much specifically on CATALINA_HOME vs. CATALINA_BASE. That question does allude to the "appBase" parameter, which is documented in the Tomcat6 documentation for the Host container in the configuration file.

Here's the questions: Why are these two variables separated? When should they be separated? What does this allow the administrator to do? What do you then place into each directory? When should these two variables be the same? What does ASF recommend for standard practice?

Why are these two variables separated?

catalina.home points to the location of the common information.
catalina.base points to the directory where all the instance specific information are held.

So you have 1 home and can have more than 1 base.

When should they be separated? When should these two variables be the same?

If you have 1 tomcat you can set them to the same value but good practice would suggest you plan ahead and keep them separate: you never know if you need more than one tomcat. Ubuntu started following this way of thinking due to it being more logical: it makes it easier to run 2+ tomcats but does not disable running 1 tomcat where setting them both to the same value would require everyone to edit the base value. Makes more sense to keep them different.

What does this allow the administrator to do?

Allow for more than 1 tomcat to run at the same time where each tomcat instance can have their own apps.

What do you then place into each directory?

Home contains the binairy.
Base contains conf, logs, webapps, work and temp. 1 for every tomcat instance.

CATALINA_HOME vs CATALINA_BASE

If you're running multiple instances, then you need both variables, otherwise only CATALINA_HOME.

In other words: CATALINA_HOME is required and CATALINA_BASE is optional.

CATALINA_HOME represents the root of your Tomcat installation.

Optionally, Tomcat may be configured for multiple instances by defining $CATALINA_BASE for each instance. If multiple instances are not configured, $CATALINA_BASE is the same as $CATALINA_HOME.

See: Apache Tomcat 7 - Introduction

Running with separate CATALINA_HOME and CATALINA_BASE is documented in RUNNING.txt which say:

The CATALINA_HOME and CATALINA_BASE environment variables are used to specify the location of Apache Tomcat and the location of its active configuration, respectively.

You cannot configure CATALINA_HOME and CATALINA_BASE variables in the setenv script, because they are used to find that file.

For example:

(4.1) Tomcat can be started by executing one of the following commands:

  %CATALINA_HOME%\bin\startup.bat         (Windows)

  $CATALINA_HOME/bin/startup.sh           (Unix)

or

  %CATALINA_HOME%\bin\catalina.bat start  (Windows)

  $CATALINA_HOME/bin/catalina.sh start    (Unix)

Multiple Tomcat Instances

In many circumstances, it is desirable to have a single copy of a Tomcat binary distribution shared among multiple users on the same server. To make this possible, you can set the CATALINA_BASE environment variable to the directory that contains the files for your 'personal' Tomcat instance.

When running with a separate CATALINA_HOME and CATALINA_BASE, the files and directories are split as following:

In CATALINA_BASE:

• bin - Only: setenv.sh (*nix) or setenv.bat (Windows), tomcat-juli.jar
• conf - Server configuration files (including server.xml)
• lib - Libraries and classes, as explained below
• logs - Log and output files
• webapps - Automatically loaded web applications
• work - Temporary working directories for web applications
• temp - Directory used by the JVM for temporary files>

In CATALINA_HOME:

• bin - Startup and shutdown scripts
• lib - Libraries and classes, as explained below
• endorsed - Libraries that override standard "Endorsed Standards". By default it's absent.

How to check

The easiest way to check what's your CATALINA_BASE and CATALINA_HOME is by running startup.sh, for example:

$ /usr/share/tomcat7/bin/startup.sh
Using CATALINA_BASE:   /usr/share/tomcat7
Using CATALINA_HOME:   /usr/share/tomcat7

You may also check where the Tomcat files are installed, by dpkg tool as below (Debian/Ubuntu):

dpkg -L tomcat7-common