Configuring Tomcat

The focus of this blog is on configuring Tomcat 6 on 64-bit Linux. However, the approach can be adopted to other versions of Tomcat as well.

Installing JRE

Tomcat 6.0 requires JSE 5.0 and later. We will be using Java 6 Update 29 for Linux 64-bit in this blog. A dedicated JRE for Tomcat is preferred over a shared a JRE. The main advantage is that it isolates from changes to the global JRE. This approach is common with major application severs such as WebLogic, webMethods (both IS and Portal servers) where a dedicated JRE is bundled with the application. This dedicated JRE will installed under the tomcat directory, e.g. tomcat/java/jre1.6.0_29

To install the Linux (self-extracting) file, change to the directory in which you want to install and run the installer, for example:

sh jre-6u29-linux-x64.bin

and follow the instructions on screen

The next step is to create a soft link as shown below:

ln -s ./jre1.6.0_29 ./jre6

Set up an environment variable for Catalina JRE home in .bashrc:

# This is the java used by Tomcat
export CATALINA_JRE_HOME=/apps/qat/tomcat/java/jre6

Soft link permits minor changes to JRE without changing CATALINA_JRE_HOME environment variable

Tomcat Installation

Unzip the Tomcat (self-extracting) file from tomcat directory. As with JRE, create a soft link to the Tomcat installation, e.g. ln -s ./apache-tomcat-6.0.33/ ./tomcat6

Directory Structure

The tomcat contains the following directories:

Directory	Description
apache-tomcat-version	Tomcat installation, e.g. apache-tomcat-6.0.33
java	Java run time. JRE is installed under this folder. e.g jre1.6.0_29
instances	Tomcat instances, see below for Tomcat instances

Tomcat Instances

We will configure Tomcat to run multiple instances on a single server. The main benefit of this approach is that it makes the Tomcat upgrade task easier without concerns over overwriting existing applications and configurations.

Instances are named as webbasenn under tomcat/instances folder where nn starts from 01, for example: webbase01. Instances are named independent of their purposes to allow flexibility.

Directory Structure

The directory structure for an instance:

Directory	Description
bin	Contains setenv.sh and other utility scripts. The setenv.sh file contains environment variables expected by catalina.sh and at minimum, it should contain an entry for JRE_HOME; see Scripts section for an example. The other scripts in this folder include scripts to start/shutdown an instance
conf	various configuration files; very similar to conf directory of Tomcat installation
deploy	war files along with their context will go in here
logs	Tomcat logs for this instance will go into this directory
temp	temporary directory for the instance
webapps	web applications shipped with Tomcat will go in here. Application war files shouldn’t go in here!
work	Tomcat work directory, used internally by Tomcat

Steps to create an instance:

1. Create the above directories apart for conf directory, for example:
   cd instances/webbase01/;mkdir {bin,deploy,logs,temp,webapps,work}
2. Copy conf directory in the Tomcat installation into the instance folder.
   1. Change port numbers in server.xml. For the first instance, this step is not required if default ports are adequate. However, for subsequent instances, port numbers in server.xml must be changed accordingly to avoid network port conflicts. Port numbers to change are: shutdown, connector and redirect
   2. Disable unpacking WAR files and auto deploy function on STG and PRD servers (this step is not required for lower environments). Create a default context file:
      1. Create conf/Catalina/localhost/context.xml.default
      2. Add the following entry in context.xml.default: <Context unpackWAR="false" autoDeploy="false"/>
   3. Edit conf/tomcat-users.xml. Add the gui role and manager user: The password tomcat is for illustration purposes only
   4. Copy the web applications ROOT, manager and host-manager from Tomcat installation to webapps directory of the instance. You may copy the whole webapps directory from the installation and then remove unwanted applications such as docs and examples using Tomcat manger application. docs and examples are optional for lower environments but ideally shouldn’t exist on STG or PRD environments (depending on organization policies)
   5. Add environment details to webapps/ROOT/index.html as shown below:
      1. Title change: Apache Tomcat – QAT
         
      2. Banner change
         

   Deployment

   Copy the war file to the deploy folder and create a context file under conf folder. For example, the context file (MySample-1.0.xml) for MySample application is:
   
<Context docBase="/apps/prd/tomcat/instances/webbase01/deploy/MySample-1.0(B-14).war"/>


   Scripts

   Scripts for an instance are under tomcat/instances/webbase/bin/ directory

   Script	Description
   catalina_env.sh	contains environment variables common to other scripts; at minimum, there should be 2 environment variables for CATALINA_HOME and CATALINA_BASE
   start.sh	wrapper for Tomcat start up script; should run from the bin directory
   shutdown.sh	wrapper for Tomcat shut down script; should run from the bin directory
   version.sh	wrapper for Tomcat version script; should run from the bin directory
   setenv.sh	sets environment entries for use by catalina.sh; at minimum, there should be an entry for JRE_HOME; see below for setting other variables: #!/bin/sh export JRE_HOME=$CATALINA_JRE_HOME export JAVA_OPTS=-XX:MaxPermSize=128m export CATALINA_OPTS='-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=4080 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false'