topics/tomcat/generalInstallAdvice/sharedInstall.txt

P. Conrad  for CISC474  01/07/2006


This file describes how to run multiple instances of Tomcat
from a single install.

What do you mean by "multiple instances of Tomcat from a single install"?
==============================================================

An example probably makes this more clear.

For example, on strauss.udel.edu, Tomcat is installed in

   /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12

If you want to run your own tomcat server on strauss, you don't have
to download tomcat yourself; you can use this installation.

However, you still have to do some work yourself, because by default,
the configuration files for Tomcat live inside this directory structure,
and you don't have write access to these files.

What you need is your own set of configuration files, and way to direct
Tomcat to use _those_ configuration files, while using the 
directory /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12 for anything
that can be shared.

This document describes how to do that.


Important environment variables: CATALINA_BASE vs. CATALINA_HOME
================================================================

The way to make a shared install work is to separate two environments:

  CATALINA_BASE      your own personal configuration files
  CATALINA_HOME      the shared directory

CATALINA_BASE points to a directory, e.g. a subdirectory "tomcat" under
your home directory, where you make configuration changes and deploy your
webapps.  You should have read/write access to these files.

CATALINA_HOME points to the place where the shared installation files live
(you have "read only" access to these files.).

In addition, another environment variable is helpful to define:

  CATALINA_PID       a file where the process id of your tomcat server is stored

An example will illustrate how to make this work.

Example setup 
=============

For example, suppose your home directory on strauss is
 /home/usra/98/76543

You might do the following:

 setenv CATALINA_BASE /home/usra/98/76543/tomcat
 setenv CATALINA_PID   $CATALINA_BASE/http.pid
 setenv CATALINA_HOME /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12


You should be able to use $HOME to stand for your home directory, i.e.

 setenv CATALINA_BASE  $HOME/tomcat
 setenv CATALINA_PID   $CATALINA_BASE/http.pid
 setenv CATALINA_HOME  /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12


For example, what I put in my .localenv is:

mkdir -p $HOME/tomcat
if -d $HOME/tomcat then
  setenv CATALINA_BASE $HOME/tomcat
  setenv CATALINA_PID $CATALINA_BASE/http.pid

  if -d /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12 then
    setenv CATALINA_HOME /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12
  endif
endif

One time setup commands
=======================

Then to set things up, you'd do:

> mkdir -p $CATALINA_BASE
> cp -r $CATALINA_HOME/conf $CATALINA_BASE
> cd $CATALINA_BASE
> mkdir -p logs temp webapps work shared/lib shared/classes

Now:
   $CATALINA_BASE/webapps is where you put your webapps
   $CATALINA_BASE/conf/server.xml is where you configure _your_ server


One time configuration
======================

Some things you need to change in $CATALINA_BASE/conf/server.xml

(1) Change the shutdown port

   <Server port="8005" shutdown="SHUTDOWN">

   A Tomcat instance has a port number on which it listens for shutdown
   requests.  You need to change 8005 to some other number that you've 
   been assigned, or that you choose arbitrarily.

   Suppose you pick 8101.  To be sure that number isn't already in use,
   do the command "netstat -an | grep 8101" and make sure that 8101 isn't
   already in the LISTEN state.

(2) Change the port on which the HTTP service is listening.

    By default, Tomcat listens for connections on port 8080.
    That means, you'll use a URL such as the following to connect to
    your server:

     http://strauss.udel.edu:8080 

    The place in the server.xml file that make this work is the following
    XML element:
 
    <Connector port="8080" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               connectionTimeout="20000" disableUploadTimeout="true" />

     You need to choose a different port (see the previous item about
     choosing a port not already in use).   Change 8080 to whatever
     port you decide to use (e.g. 8180).

(3) If you are using SSL to deploy an https:// type service, also 
    change the port 8443.

    By default, the server.xml file has the SSL Connector commented out.

    Note for example, the use of the XML comment brackets: <!--   -->
    around the Connector element below:

    <!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
    <!--
    <Connector port="8443" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" />
    -->

    However, if you "uncomment this" (and note that this is not necessarily
    the _only_ thing you have to do to enable SSL and the https:// thing to work)
    you'll need to change port 8443 to some other port.

If you want the example webapps to be under your tomcat directory, you
need to copy them in.  However, be warned: they take up 8.2MB of space!

   cp -r $CATALINA_HOME/webapps/* $CATALINA_BASE/webapps

   If you don't do this, when you to to http://strauss.udel.edu:8180
   (or whatever _your_ port is) you'll just see a blank screen (unless you
   deployed some webapps of your own.)

Starting and stopping the server
================================

Provided you've set the environment variables CATALINA_HOME,
CATALINA_BASE and CATALINA_PID correctly, to start and stop 
the server, you can still use the scripts from the shared install.

Startup:

    $CATALINA_HOME/bin/startup.sh

Shutdown:

    $CATALINA_HOME/bin/shutdown.sh


If these don't work, check that you followed ALL of the above
steps corrrectly (including avoiding port number conflicts with
other users on your system.)

What you need to do to make this work on the ECL machines,
e.g. porsche.cis.udel.edu and the clients of porsche.cis.udel.edu
=================================================================

The steps are very similar to those listed above for strauss.udel.edu.

Here are some differences:

(1) Instead of a .localenv, on the ECL machines you'll directly
     edit your .cshrc file (or the bash equivalent)
	 
(2) The location of CATALINA_HOME is different.

Here for example, are commands you might use in your .cshrc 
on porsche if you use tcsh as your shell:

if  -d /porsche/cisc474/tomcat/  then

    setenv CATALINA_HOME /porsche/cisc474/tomcat
endif

if  -d $HOME/tomcat  then

    setenv CATALINA_BASE $HOME/tomcat
endif

(3) You have been assigned a specific client of porsche.cis.udel.edu on which
to run your Tomcat server, and three port numbers to use with that server.

That table can be found at:  
    http://www.udel.edu/CIS/474/pconrad/06S/info/portsAndAccounts.html
or at the link "ports and accounts" on the main CISC474 web page.

For example, andersen should run his her server on subaru, 
using ports 8001, 8101, and 8201.

That means you'll need to ssh into strauss.udel.edu first, then
ssh from there into porsche.cis.udel.edu, and then ssh into, for example,
subaru.   

This is necessary because direct connections into porsche.cis.udel.edu
are only permitted from certain systems (for example strauss), and connections
into the clients of porsche are only permitted from porsche.

You'll use the commands below to set up your tomcat CATALINA_BASE
directory (identical to the ones used to set up your server on strauss).
(These commands can be run on porsche.cis.udel.edu OR on the client
machine.)

mkdir -p $CATALINA_BASE
cp -r $CATALINA_HOME/conf $CATALINA_BASE
cd $CATALINA_BASE
mkdir -p logs temp webapps work shared/lib shared/classes

But then, you'll edit the file $CATALINA_BASE/conf/server.xml as
follows:

(3a) Change the shutdown port
   <Server port="8005" shutdown="SHUTDOWN">

to the first port on your list, e.g if your list is 8001, 8101, 8201,
change this line to:

  <Server port="8001" shutdown="SHUTDOWN">


(3b) Change the port on which the HTTP service is listening
to the second port in your list.  e.g if your list is 8001, 8101, 8201,
change this line from:
  
    <Connector port="8080" maxHttpHeaderSize="8192"
to 
    <Connector port="8101" maxHttpHeaderSize="8192"


(3c) Change the port on which the HTTP service is listening
to the THIRD port in your list.  e.g if your list is 8001, 8101, 8201,
change this line from:
  
    <Connector port="8443" maxHttpHeaderSize="8192"
to 
    <Connector port="8201" maxHttpHeaderSize="8192"

(4) To start and stop your Tomcat, use the same commands you did
on strauss.udel.edu.  These commands MUST however, be run on the 
specific client you were assigned---otherwise the port forwarding
will not work correctly.

Startup:
   $CATALINA_HOME/bin/startup.sh  

Shutdown:
   $CATALINA_HOME/bin/shutdown.sh  

To see if your server is up, a few tricks:

If jsample is your username, use:

   ps -fu jsample
   
 to list all processes currently being run by jsample.  You can
 find the tomcat process among these; it starts with "java".
 
 Also, try 
 
    netstat -an | grep xxxx
	
where xxxx is your port number, to see if the port number is
listening.

Finally, note that even though your server may be running on,
say, port xxxx on acura.cis.udel.edu, you must use the following
as your URL:

  http://porsche.cis.udel.edu:xxxx

The following URL will NOT work:

  http://acura.cis.udel.edu:xxxx

because acura is not directly connected to the Internet.

(5) Finally, one of the main reasons we run on the clients of porsche
rather than strauss is that you are permitted here to leave your server
running 24x7 all semester long (as long as you are still enrolled in
CISC474.)   However, from time to time, labstaff may reboot these
machines.    When that happens, you'll have to restart your server.

To avoid that problem, you may want to create a cron job that checks
at periodic intervals (e.g. once per hour) whether the server is running;
if it is not running, you can restart it.

Here is an example script to check whether your server is running,
and restart it when it is down.

#monitorTomcat  P. Conrad Spring 2006 for CISC474

CURL=/usr/local/bin/curl
URL=http://localhost:8106
export CATALINA_HOME=/porsche/cisc474/tomcat
export CATALINA_BASE=$HOME/tomcat
export JAVA_HOME=/usr/java/jre1.5.0_03/

$CURL --fail --retry 3 $URL 1> /dev/null 2> /dev/null

# now test the exit status of that command

ERROR_STATUS=$?

 if [ $ERROR_STATUS -ne 0 ]
 then
    hostname
    echo server is down\; curl status code $ERROR_STATUS
    $CATALINA_HOME/bin/startup.sh
# else
#   hostname
#   echo server on $URL is up
 fi


The "else...echo server is up" command is commented out so that we don't get 
email every time the script runs as a cron job and we find out that
the server is indeed up.  However, it is nice to have this line of
output when running the script interactively, or when first testing
the cron job.

The following line in the crontab will run the script at 28 minutes
after the hour once per hour.  

28 * * * * /usa/pconrad/cisc474/monitorTomcat.sh

Note that the crontab must be run on the machine where you want 
to restart the server (e.g. on suzuki not on porsche)!  

That's why we have to use the URL http://localhost:8106 rather than
http://porsche.cis.udel.edu:8106 ... as it turns out, you can't
connect to porsche.cis.udel.edu (per se) from the clients of porsche.