Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Architecture and Install

CATALINA_HOME and CATALINA_BASE

Learn the difference between CATALINA_HOME and CATALINA_BASE, how to run several Tomcat instances from one installation, set up a base folder, and upgrade safely.

Tomcat uses two environment variables that look almost identical and are easy to confuse. CATALINA_HOME points at the Tomcat installation: the program files you unpacked. CATALINA_BASE points at an instance: the configuration, web applications, logs and temporary files of one running server. When you do not set CATALINA_BASE, it defaults to CATALINA_HOME, and you can ignore the difference. The moment you want two Tomcats on one machine, or painless upgrades, the split becomes valuable.

This lesson explains what lives where, builds a base directory by hand, and demonstrates the resolution rule with Java.

What belongs to HOME and what to BASE

Location Lives in Notes
bin/ (scripts, bootstrap.jar, tomcat-juli.jar) CATALINA_HOME Always read from home, never from base (except setenv).
lib/ (Tomcat JARs) CATALINA_HOME Shared by all instances; base may add its own lib/.
conf/ CATALINA_BASE Each instance needs its own copy.
webapps/, work/, temp/, logs/ CATALINA_BASE Per instance.
bin/setenv.sh CATALINA_BASE Instance-specific JVM options.

One install, many instances

CATALINA_HOME Program files, shared and read-only
CATALINA_BASE One instance: conf, webapps, logs
Upgrade Point HOME to the new version

Same HOME, different BASE, different ports.

1 / 2

Creating an instance

A minimal instance needs conf, logs, temp, webapps and work. Copy the configuration from the installation and change the ports, otherwise two instances fight over 8080 and 8005:

Terminal
export CATALINA_HOME=/opt/tomcat
mkdir -p /srv/tomcat/app1/{conf,logs,temp,webapps,work}
cp -r $CATALINA_HOME/conf/* /srv/tomcat/app1/conf/

# edit /srv/tomcat/app1/conf/server.xml: shutdown port 8105, HTTP connector 8180
export CATALINA_BASE=/srv/tomcat/app1
$CATALINA_HOME/bin/catalina.sh start

A second instance /srv/tomcat/app2 gets ports 8205 and 8280 and is started with its own CATALINA_BASE. Both run the same Java classes from CATALINA_HOME/lib, so memory for the code is not shared (each is its own JVM), but disk space is, and upgrading Tomcat becomes: unpack the new version, repoint CATALINA_HOME, restart. Your instance files are untouched.

On Linux packages (for example the Debian tomcat10 package) this is exactly how Tomcat is arranged: program files in /usr/share/tomcat10 (home) and instance data in /var/lib/tomcat10 plus /etc/tomcat10 (base).

How the scripts decide

The launch scripts compute CATALINA_BASE as follows: if the variable is set, use it; otherwise use CATALINA_HOME. Tomcat's Java code then passes both values as system properties catalina.home and catalina.base. You see them in server.xml and context.xml as ${catalina.base} placeholders, and the class loader uses them to locate files: configuration comes from base, libraries from home and base.

The stand-in below models resolving a file path. It prefers the instance (base) and falls back to the installation (home), and shows the second instance using the same home.

Java Resolve a file against BASE then HOME (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Real Tomcat is stricter than this toy: bin and Tomcat's core lib always come from home, and a base without a conf/server.xml fails to start instead of falling back. The stand-in only shows the two-level lookup idea.

Running two instances: a port plan

Port conflicts are the number one problem with multiple instances. Each instance needs a unique value for the shutdown port, every connector port and the AJP port if you use it. The program below checks a plan for collisions the way you would review your own configuration:

Java Check a port plan for collisions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Using the variables in configuration

Both variables can be referenced as ${catalina.home} and ${catalina.base} inside server.xml, context.xml and logging.properties. The standard files use them so that paths follow the instance:

XML
<Valve className="org.apache.catalina.valves.AccessLogValve"
       directory="${catalina.base}/logs" prefix="access_" suffix=".log" />

Relative paths in server.xml attributes such as appBase="webapps" are resolved against CATALINA_BASE.

Common mistakes

  • Setting CATALINA_HOME to the instance folder (and not setting base) so upgrades overwrite your data.
  • Copying only server.xml into a new base and forgetting web.xml and logging.properties, so the server starts without defaults.
  • Two instances sharing one logs or work directory: they overwrite each other's files.
  • Running instances with the same user and the same temp directory without distinct names.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does CATALINA_BASE point to?

    BASE is the instance. HOME is the installation. If BASE is not set it equals HOME.
  2. 2. Why can you upgrade Tomcat painlessly with a separate CATALINA_BASE?

    Program files live in HOME, instance data in BASE, so replacing HOME leaves your files alone (still read the release notes for config changes).
  3. 3. Which values must differ between two instances on one host?

    Each listening socket needs its own port number. Duplicates cause 'Address already in use'.
  4. 4. In server.xml, relative paths like appBase="webapps" are resolved against which directory?

    Tomcat resolves relative paths against catalina.base, so each instance has its own webapps folder.

Summary

  • CATALINA_HOME is the installation; CATALINA_BASE is one instance (defaults to HOME).
  • Instances need their own conf, webapps, logs, temp, work and unique ports.
  • Use ${catalina.base} in configuration so paths follow the instance.
  • Splitting them makes upgrades and multi-instance hosting simple.
  • Review port plans for collisions before starting.

Next: Starting and stopping Tomcat