Last year, I attended the Seminar sponsored by . One of the key things I took away is setting up apache tomcat by externalizing the application deployment space with CATALINA_BASE.

First off, a couple of mini-explanations:

CATALINA_HOME

the expanded (unzipped) tomcat installation

CATALINA_BASE

the location for a given instance.

By default, CATALINA_BASE is set to CATALINA_HOME. This is how many use tomcat. So, why would anyone want to break it out? The key reasons are, it makes creating multiple instances much easier and it simplifies upgrading the tomcat install, and upgrade rollback is trivialized.

Setup a Directory for CATALINA_BASE

mkdir -p /usr/local/mywebbase/{bin,conf,logs,temp,webapps,work}

This will give a directory structure that looks like this:

/usr/local/mywebbase/|-- bin|-- conf|-- logs|-- temp|-- webapps`-- work

Next, some files to help set stuff up.

/usr/local/mywebbase/|-- bin|   `-- setenv.sh|-- conf|   |-- server.xml|   `-- web.xml|-- logs|-- temp|-- webapps`-- work

What Are These Files?

_

The setenv.sh is there to allow setting up any environment configuration, memory for java, garbage collection, Terracotta setup, etc. Basically, instead of making edits to catalina.sh, just add whatever is needed to setenv.sh

The server.xml file is there to configure this particular instance. For example, if you needed two tomcat instances running on two different ports, each instance would share the same CATALINA_HOME, they would have their own CATALINA_BASE directories, and the ports would be configured in each on their server.xml files.

web.xml, this file isn't really needed (assuming, your app's web.xml defines everything). However, in the real world, just copy the one out of $CATALINA_HOME/conf to here.

Connecting Everything Together

The final thing to do is, create a startup script in /etc/init.d/ for each instance of tomcat. The first thing the script should do is set both CATALINA_HOME and CATALINA_BASE. CATALINA_HOME will be the same in all of the startup scripts, CATALINA_BASE will be distinct for each instance.

Alternative to Editing the Startup Script

If you don't want to edit the startup script, just set CATALINA_HOME, CATALINA_BASE and JAVA_HOME in the setenv.sh file. Next, copy over catalina.sh from CATALINA_HOME/bin into CATALINA_BASE/bin. The catalina.sh file will read your setenv.sh and start tomcat normally.

Final Notes:

Finally, war files should be deployed to the webapps directory for a given CATALINA_BASE. Also note, if you use variables in your log4j files, be sure to use ${catalina.base} instead of ${catalina.home}. Or, your log files may not show up where you expect.

Upgrading Tomcat

The two basic techniques to use are, either create a from the actual expanded tomcat (CATALINA_HOME)

example: ln -s /usr/local/apache-tomcat-6.0.16 /usr/local/tomcat6

To upgrade/downgrade, stop the server, change the symbolic link, and start the server back up.

The other method is, stop the server, edit the CATALINA_BASE variable in the startup script, and start the server.

Either way you choose, the key is, you don't need to redeploy your application when updating the actual server.