Installing Apache Tomcat 5.5/6/7 with a multi-instance layout on Linux

Purpose

Apache Tomcat is designed to provide a single instance of a server. However, it is easy to configure multiple instances based on a single installation, which provides the following benefits: 

• Ability to quickly deploy multiple instances from one shared Tomcat distribution version.
• Ability to upgrade all Tomcat instances by just upgrading a single installed Tomcat distribution version.
• Instance configuration separate from the installation, and without multiple copies of the same Tomcat version on a single platform, offering greater flexibility and  manageability.

This article provides information on instance configuration with Tomcat 6.0.35. Other versions can be used similarly.

Resolution

Downloading and installing Tomcat

1. Download the ASF Tomcat tarball binary distribution.
2. Extract the archive files to your installation path. You may use any path you prefer. However, in this instance we have chosen /opt/tomcat6. 
   
   > cd /opt
   > tar xvzf apache-tomcat-6.0.35.tar.gz
   > mv apache-tomcat-6.0.35 tomcat6
   
   This regular Tomcat installation serves as the reference (CATALINA_HOME) for our multiple instances.
   
   
3. Install a supported Java JDK or JRE in order to run Tomcat.
   
   Note: See the RUNNING.txt file from your Tomcat download for details.

 

Configuring an instance of Tomcat

An instance of Tomcat has its own directory, referred to as CATALINA_BASE, separate from the Tomcat install in CATALINA_HOME.

1.  Define your chosen CATALINA_HOME and CATALINA_BASE paths as shell variables:
   
   > CATALINA_HOME=/opt/tomcat6
   > CATALINA_BASE=/opt/tc6-instances/example1
   
   
2. Create your Tomcat instance base path:
   
   > mkdir -p $CATALINA_BASE
   
   
3. Copy some default Tomcat content to the instance base path:
   
   > cp -r $CATALINA_HOME/conf $CATALINA_BASE
   > mkdir $CATALINA_BASE/bin
   > cp $CATALINA_HOME/bin/*.sh $CATALINA_BASE/bin
   
   
4. Create empty folders for the instance to use:
   
   > mkdir $CATALINA_BASE/{webapps,logs,temp,work,lib}
   
   
5. Copy setenv.sh (attached at the bottom of this article; or create your own) to $CATALINA_BASE/bin. This script is sourced by the Tomcat scripts and can be used to specify instance-specific environment variable settings. If you do not define these environment variables in setenv.sh, the shell environment variables or script defaults are used instead.
   
6. Modify variables in setenv.sh to match your Tomcat deployment instance environment:
   
   CATALINA_HOME=/opt/tomcat6            
   CATALINA_BASE=/opt/tc6-instances/example1
   CATALINA_PID=$CATALINA_BASE/temp/tomcat.pid
   JAVA_HOME=/path/to/your/JDK  or JRE_HOME=/path/to/your/JRE     (If not set, the startup script may find one in your environment)
   
   Note: Set any other custom JVM options in setenv.sh if necessary.
   
   
7. Edit your $CATALINA_BASE/conf/server.xml to specify connector ports and shutdown port that do not conflict with ports already in use by other server instances.
   

Your instance is now ready to use. You can start and stop your Tomcat instance with the instance $CATALINA_BASE/bin/{catalina.sh,startup.sh,shutdown.sh} scripts as usual. 

You can repeat these steps with a different CATALINA_BASE each time to create as many Tomcat instances as your platform can handle. You must customize at least the conf/setenv.sh and conf/server.xml files for each instance.

Additional Information

• For information on a cross-platform Java Service Wrapper for running Tomcat and YAJSW as an option, see http://yajsw.sourceforge.net/.
• Apache Tomcat 6 documentation.

See Also

• Deploying ASF Tomcat 6.0 using multi instances layout on Windows OS
• Running Apache Tomcat instance as a daemon on Linux

Attachments

• setenv.sh