Tomcat - CATALINA_BASE and CATALINA_HOME variables

Question

I have multiple instances of tomcat 6 running on the same server (Linux) and it works as expected. I am trying to find out what the standard practice is with regards to setting the CATALINA_HOME and CATALINA_BASE variables.

In my tomcat installation, I have setup CATALINA_HOME to point to a "common" folder (say /tomcat6) and the CATALINA_BASE variable varies depending on the instance name (say /tomcat_instance1, /tomcat_instance2)

My question is this:

• Do I really need two variables?
• Or Can I just have one CATALINA_HOME and do away with CATALINA_BASE (or vice-versa) ?

Adorn

The question itself is an answer really. – Nab

The reason you need to do this is to separate maintenance of the Tomcat software (which lives in $CATALINA_HOME) from maintenance of the Tomcat instance configuration and contents (which live in $CATALINA_BASE). – Sudorific

Answer 1

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

See also the documentation of Apache Tomcat 10/Introduction/CATALINA_HOME and CATALINA_BASE.

Josphinejoss

Your second paragraph is incorrect when using the packaged Tomcat on Ubuntu. It properly separates the Tomcat software (in $CATALINA_HOME) from the Tomcat instance (in $CATALINA_BASE). – Sudorific

The information provided here refers to the vanilla Tomcat as provided by the ASF. Different distributors may decide to configure it to their taste, so your mileage may vary. – Syphilology

Answer 2

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

Kahlil

This is a much better answer the the accepted. Very well explained. – Dashboard

Explain please how to start multiple tomcat instances withe different CATALINA_BASE? – Bioecology

CATALINA_BASE and CATALINA_HOME must be set as system variables: Windows: set CATALINA_BASE=path – Bioecology

Answer 3

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 if conf/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.

Manella

nice answer! Especially the bit on how to manually construct/create a CATALINA_BASE – Sharonsharona

Answer 4

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.

Remise

Can you set catalina_home path in \bin\catalina.sh file for both instances of tomcat?? – Baseboard

Answer 5

CATALINA_BASE is optional.

However, in the following scenarios it helps to setup CATALINA_BASE that is separate from CATALINA_HOME.

1. When more than 1 instances of tomcat are running on same host

   • This helps have only 1 runtime of tomcat installation, with multiple CATALINA_BASE server configurations running on separate ports.
   • If any patching, or version upgrade needs be, only 1 installation changes required, or need to be tested/verified/signed-off.

2. Separation of concern (Single responsibility)

   • Tomcat runtime is standard and does not change during every release process. i.e. Tomcat binaries
   • Release process may add more stuff as webapplication (webapps folder), environment configuration (conf directory), logs/temp/work directory

Chavaree

Answer 6

That is the parent folder of bin which contains tomcat.exe file:

CATALINA_HOME='C:\Program Files\Apache Software Foundation\Tomcat 6.0'

CATALINA_BASE is the same as CATALINA_HOME.

Sensual

Your answer is misleading... the correct answer should state If multiple instances are not configured, $CATALINA_BASE is the same as $CATALINA_HOME.` as per the documentation – Rigel

CATALINA_BASE is equal to CATALINA_HOME only when you run root instance. When you have multiple instances it will be different. – Dymoke

I would say that CATALINA_BASE and CATALINA HOME should be different even if you have only one instance. That way your content is separate from your installation. For example, CATALINA_HOME in /usr/share/tomcat and CATALINA_BASE in /var/lib/tomcat – Bollworm

no. It may be the same, but may be not the same, for multi-instance. – Cream