tomcat - CATALINA_BASE and CATALINA_HOME variables
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
andCATALINA_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
andCATALINA_BASE
variables in thesetenv
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
andCATALINA_BASE
, the files and directories are split as following:In
CATALINA_BASE
:
bin
- Only: setenv.sh (*nix) or setenv.bat (Windows), tomcat-juli.jarconf
- Server configuration files (including server.xml)lib
- Libraries and classes, as explained belowlogs
- Log and output fileswebapps
- Automatically loaded web applicationswork
- Temporary working directories for web applicationstemp
- Directory used by the JVM for temporary files>In
CATALINA_HOME
:
bin
- Startup and shutdown scriptslib
- Libraries and classes, as explained belowendorsed
- 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
If you are running multiple instances of Tomcat on a single host you should set CATALINA_BASE
to be equal to the .../tomcat_instance1
or .../tomcat_instance2
directory as appropriate for each instance and the CATALINA_HOME
environment variable to the common Tomcat installation whose files will be shared between the two instances.
The CATALINA_BASE
environment is optional if you are running a single Tomcat instance on the host and will default to CATALINA_HOME
in that case. If you are running multiple instances as you are it should be provided.
There is a pretty good description of this setup in the RUNNING.txt
file in the root of the Apache Tomcat distribution under the heading Advanced Configuration - Multiple Tomcat Instances
I can't say I know the best practice, but here's my perspective.
Are you using these variables for anything?
Personally, I haven't needed to change neither, on Linux nor Windows, in environments varying from development to production. Unless you are doing something particular that relies on them, chances are you could leave them alone.
catalina.sh
sets the variables that Tomcat needs to work out of the box. It also says that CATALINA_BASE
is optional:
# CATALINA_HOME May point at your Catalina "build" directory.
#
# CATALINA_BASE (Optional) Base directory for resolving dynamic portions
# of a Catalina installation. If not present, resolves to
# the same directory that CATALINA_HOME points to.
I'm pretty sure you'll find out whether or not your setup works when you start your server.
Pointing CATALINA_BASE
to a different directory from CATALINA_HOME
allows you to separate the configuration directory from the binaries directory.
By default, CATALINA_BASE
(configurations) and CATALINA_HOME
(binaries) point to the same folder, but separating the configurations from the binaries can help you to run multiple instances of Tomcat side by side without duplicating the binaries.
It is also useful when you want to update the binaries, without modifying, or needing to backup/restore your configuration files for Tomcat.
Update 2018
There is an easier way to set CATALINA_BASE now with the makebase
utility. I have posted a tutorial that covers this subject at http://blog.rasia.io/blog/how-to-easily-setup-lucee-in-tomcat.html along with a video tutorial at
https://youtu.be/nuugoG5c-7M
Original answer continued below
To take advantage of this feature, simply create the config directory and point to it with the CATALINA_BASE
environment variable. You will have to put some files in that directory:
- Copy the
conf
directory from the original Tomcat installation directory, including its contents, and ensure that Tomcat has read permissions to it. Edit the configuration files according to your needs. - Create a
logs
directory ifconf/logging.properties
points to${catalina.base}/logs
, and ensure that Tomcat has read/write permissions to it. - Create a
temp
directory if you are not overriding the default of$CATALINA_TMPDIR
which points to${CATALINA_BASE}/temp
, and ensure that Tomcat has write permissions to it. - Create a
work
directory which defaults to${CATALINA_BASE}/work
, and ensure that Tomcat has write permissions to it.