Tomcat: split catalina_home and catalina_base


Catalina_home is the tomcat installation (unzipped archive), catalina_base is the folder of a server instance. By default, catalina_base is set to catalina_home. But when it comes to upgrading Tomcat installation, having the possibility to roll back or to run more than one instance of Tomcat on the same server, it is easier to separate those two folders from each other.

Setup catalina_home

Download and unzip the selected Tomcat version everywhere you want to install Tomcat.

cd /usr/local/java/tomcat

Create a shortcut to be able to switch cataline_home in case of an update

ln -s apache-tomcat-7.0.39 tomcat7

Setup catalina_base

Create a folder for catalina_base with the following substrucutre

mkdir -p /usr/local/java/tomcat/catalina_base/bin
mkdir -p /usr/local/java/tomcat/catalina_base/conf
mkdir -p /usr/local/java/tomcat/catalina_base/logs
mkdir -p /usr/local/java/tomcat/catalina_base/temp
mkdir -p /usr/local/java/tomcat/catalina_base/webapps
mkdir -p /usr/local/java/tomcat/catalina_base/work

This gives you the following structure in /usr/local/java/tomcat/catalina_base.

├── bin
│   ├──
│   └──
├── conf
│   ├── server.xml
│   └── web.xml
├── logs
├── temp
├── webapps
└── work

You have to create the above listed files as follows

The startup script for this server instance. Copy it from catalina_home/bin. It will read for specific setup.

This file contains all environment settings for the server instance – e.g. memory settings etc. Instead of editing make your updates here, will read from here.

cat bin/
## path to java jdk
export JAVA_HOME

 ## path to tomcat installation to use

 ## path to server instance to use


This file contains setup per Tomcat instance – e.g. port setup. Copy this file from catalina_home directory and ajdust the settings if needed.


This file determines default values for all webapplication – application specfic setup will be overwritten / created using the included web.xml in the war files. Also copy this file from catalina_home and adjust if needed.

Starting and stopping the server

catalina_base/bin/ start


catalina_base/bin/ stop


Deploying applications

If you want to deploy a war archive from the file system, simply copy the war file to the catalina_base/webapps directory

Setup logging

Make sure if you configure log4j to make use of ${catalina_base} instead of ${catalina_home} in order to make your application log to the correct folder.

Upgrading tomcat

If you want to upgrade the tomcat version, I prefer to stop the server, update the created sym-link /usr/local/java/tomcat/tomcat7 to the new version and restart the server. If you do not make use of the sym-link, stop the server, update value of CATALINA_HOME in catalina_base/bin/ and restart the server.

Either way you choose there is one main benefit – you do not need to reinstall all web applications as they are hosted in your catalina_base directory