STAR Electronic Shiftlog (ESL) Administration guide

The STAR (ESL) Electronic Shiftlog is written in JSP (Java server pages) and requires a web server that can render JSP content. Unlike php JSP is compiled into JAVA classes using a method call “Just in Time” this means the page is compiled the first time the page is accessed, then it does not have to be compiled again for the life of the page or until the page is modified. The forbearer of JSP is serverlets these are also used in the shiftlog mostly to stream images. The technology differs in that serverlets need to be compiled in advance of being deployed.

Our JSP server is Apache Tomcat. Documentation and newer versions can be downloaded from http://tomcat.apache.org/. Although tomcat is a fully functional web server unto its self we prefer to allow the Apache web server to serve the HTML content and only require Tomcat to serve the JSP pages that Apache can not. This is accomplished by way of the mod_jk Apache Tomcat Connector using the ajp13 protocol. Tomcat hosts on port 8080. This is blocked from the outside but can be seen on a browser started up on the online web server its self.

The Tomcat server hosting the shiftlog is deployed on the online web server online.star.bnl.gov and run under the tomcat account. In order to log on to the online web server to administrate Tomcat and the ESL you will need keys mapped to the Tomcat user account. Please see Wayne Betts or Jérôme Lauret about getting your keys mapped. There are multiple version of Tomcat residing in /opt.

Conventions relating to install of newer versions of Tomcat on the online web server

All versions of tomcat are placed in the /opt folder, in a sub folder clearly demoting the version number. (When you unzip Tomcat this is usually how it comes.) Examples are:

/opt/apache-tomcat-5.5.20/
/opt/apache-tomcat-6.0.18/

The currently used version of Tomcat is link to /opt/tomcat/. Below is an ls of the tomcat folder:

-bash-3.00$ ls -l /opt/tomcat
lrwxrwxrwx 1 root root 22 Nov 17 11:11 /opt/tomcat -> ./apache-tomcat-6.0.18

Note that this folder is the tomcat’s users home directory. It contains the .ssh folder which holds your keys, so relinking this may cause you to become locked out if you do not transfer this folder in advance.

Configuring Tomcat & The Tomcat Directory Structure

After you install a new version of Tomcat you will want to configure it.

There are some environment variables whose existences you will want to verify, and if they don’t exist you will want to set them, preferably in a start-up script so they will survive a server restart.

$CATALINA_HOME: /opt/tomcat
$JAVA_HOME: /usr/java/default

Inside the Tomcat folder you will find these directories (and some others):

$CATALINA_HOME/bin/
$CATALINA_HOME/logs/
$CATALINA_HOME/webapps/
$CATALINA_HOME/conf/

$CATALINA_HOME/bin/ holds the executables (for linux and windows).

To startup the Tomcat server use:

% $CATALINA_HOME/bin/startup.sh

To shut it down use:

% $CATALINA_HOME/bin/shutdown.sh

You will want to modify the $CATALINA_HOME/bin/catalina.sh this is a script called by startup.sh its function is to invoke the java process which is the Tomcat server.

Directly under the header these lines are added:

# added by Levente Hajdu ##################################### "
export JAVA_OPTS=$JAVA_OPTS" -Xmx512M -Djava.library.path=/usr/lib64 -Djava.awt.headless=true"
############################################################# 

A description of the options used follows

• -Xmx512M sets the memory ceiling on the JAVA VM which runs the server to 512MB this should be sufficient for our needs. Any more consumption over this limit will lead to the Tomcat process being terminated.

• -Djava.library.path this sets the library path for an optional set of native (non-JAVA) libraries which Tomcat can utilize for improved performance. If this is not present you will see suggestions to set it in the tomcat log.

• Djava.awt.headless=true this line prevents a particular type of crash. This server also hosts the SUMS statistics pages. These use libraries (jFreeChart) to render images for display which have a relation to x-server libraries. If Tomcat is started by a user that has X-forwarding enabled but no server running, Tomcat would crash as it tries to execute the JSP without this line present.

You will be spending a lot of time in $CATALINA_HOME/conf/. The file that controls the Tomcat context paths is $CATALINA_HOME/conf/server.xml. This file requires editing when ever software is deployed at a new context path. Before you edit this file always make a backup. Each year of the shiftlog resides on a different context path. Here is the list:

http://online.star.bnl.gov/apps/shiftLog2003/
http://online.star.bnl.gov/apps/shiftLog2004/
http://online.star.bnl.gov/apps/shiftLog2005/
http://online.star.bnl.gov/apps/shiftLog2006/
http://online.star.bnl.gov/apps/shiftLog2007/
http://online.star.bnl.gov/apps/shiftLog2008/
http://online.star.bnl.gov/apps/shiftLog2009/

The current year is always at:

http://online.star.bnl.gov/apps/shiftLog/

If we look inside the $CATALINA_HOME/conf/server.xml file we will see an entry for each one of these paths:

<!--Shiftlog 2007-->
<Context className="org.apache.catalina.core.StandardContext" cachingAllowed="true" 
 charsetMapperClass="org.apache.catalina.util.CharsetMapper" cookies="true" crossContext="false" debug="0" 
 docBase="/var/tomcat/webapps/shiftLog2007.war" mapperClass="org.apache.catalina.core.StandardContextMapper" 
 path="/apps/shiftLog2007" privileged="false" reloadable="true" swallowOutput="false" useNaming="true" 
 wrapperClass="org.apache.catalina.core.StandardWrapper">
<Environment description="" name="year" override="false" type="java.lang.Integer" value="2007"/>
<Environment description="" name="isEditable" override="false" type="java.lang.Boolean" value="false"/>
<Environment description="" name="runLogLink" override="false" type="java.lang.String" 
 value="http://online.star.bnl.gov/RunLog/Summary.php?run="/>
<Environment description="" name="runNumber" override="false" type="java.lang.Integer" value="7"/>
</Context>

This is the block of XML for the shiftlog for 2007. With different versions of Tomcat the syntax of this file can change, however it usually doesn’t change too much. Lets go over the important properties in this block:

docBase – Tomcat supports web archive files (.war). This is basically a zip file with a special internal structure. The explanation of the preparation of one of these files would take a whole Drupal page unto its self.

Path – This is the context path at which the site will appear when you look at it over your web browser. It is the part of the url after the server name.

Environment – The environment sub-tag makes information available to the program. The format if fairly simple, However you have to be careful to set the override="false" or else the .war files ./WEB-INF/web.xml will over write these values with its own values.

The environment properties for the shiftlog are:

year – this is the shiftlog year. Example: “2007”

isEditable – this is a boolean value after the run has completed access to the editor is turned off by setting this to false.

runLogLink – This is the url for the run log. The shiftlog uses this to build links to the run log.

runNumber – this is almost the same as the year it’s just the number. Examples:

run 8 = 2008

run 9 = 2009

run 10 = 2010

The $CATALINA_HOME/webapps/ web apps folder holds the default pages that come pre-packaged with the Tomcat server. This is also the location where Tomcat unpacks the war files. The folder naming conventions can change from Tomcat version to Tomcat version.

The $CATALINA_HOME/logs/ directory, as you may have guessed, holds log files. You will want to look over all files in here even if Tomcat would seem to be functioning correctly. The logs can point out errors you many not be aware of. The file $CATALINA_HOME/webapps/catalina.out holds the stander output stream of your JSPs (not to be confused with the HTML output stream) along with Tomcats own stander output stream, making this a handy file for debugging.

Deploying new war files

To deploy a war file the procedure is as follows:

1. Stop Tomcat:

   $CATALINA_HOME/bin/shutdown.sh

   NOTE: If you deploy the tomcat administrative web interface shutting down the whole server is not strictly required because you could just shut down the context path, but I prefer to shut down the whole server as a matter of habit because time required is so short no one really notices.
    

2. If this is an upgrade of an existing .war file (else move to step 3), back up the old .war file. All war files are located in /var/tomcat/webapps/ here is the listing of the directory, note the convention for the naming of the web archive files:

   -bash-3.00$ ls -1 /var/tomcat/webapps/shiftLog*.war
   /var/tomcat/webapps/shiftLog2003.war
   /var/tomcat/webapps/shiftLog2004.war
   /var/tomcat/webapps/shiftLog2005.war
   /var/tomcat/webapps/shiftLog2006.war
   /var/tomcat/webapps/shiftLog2007.war
   /var/tomcat/webapps/shiftLog2008t.war
   /var/tomcat/webapps/shiftLog2008.war
   /var/tomcat/webapps/shiftLog2009.war

   When removing one of these files I move it to the /var/tomcat/webapps/old/ directory and rename it following the convention here:

   shiftLog2007.Apr03.965628000.war
   shiftLog2007.Apr04.288184000.war
   shiftLog2007.Apr09.200079000.war
   shiftLog2007.Dec03.805483000.war
   shiftLog2007.Feb07.785336000.war
   ...
   shiftLog2007.Mar27.875569000.war
   shiftLog2007.Nov09.134343000.war
   shiftLog2007.Nov28.320967000.war
   shiftLog2007.Nov28.657299000.war

   It is important to retain the backup in case there is something wrong with the new .war file, keeping the old one will allow you to roll back whilst the problem is being corrected.

3. Next copy over the new .war file from the node on which it resides. Scp is the method I use for this. The syntax is:

   % scp [username]@[nodeName]:[Path&File]/var/tomcat/webapps/shiftLog[year].war

4. If this is a new deploy and not an upgrade of an existing .war file you will have to configure a context path in $CATALINA_HOME/conf/server.xml (else move to step 6)
    

5. If this is an upgrade you will have to dump (delete) the expanded .war file in $CATALINA_HOME/webapps/ it should be a directory having a name similar to that of the name of the .war file. You do not have to back this up because you already have the .war file backed up.

6. Startup Tomcat

   % $CATALINA_HOME/bin/startup.sh

7. Open up a web browser and check that the page displays correctly

8. Run the shift log Java web start application to confirm that the developer has signed his or her jar files within the .war file, if not you will need to have the .war file rebuilt.

Tips

Because upgrades are done fairly frequently mostly for request for new features and some bug fixes I keep a script to do the upgrade process listed above, however the script requires modification before running it. The name of the script is $CATALINA_HOME/bin/deploy_year .

If you have done the upgrade but do not notice any change:

1. checked that you dumped $CATALINA_HOME/webapps/ (step 5)

2. also dump your web browsers cache

If you get the “page unavailable” message, check that the tomcat process is running. Use the command

ps –ef | grep tomcat | grep java 

Even if it is running shut it down and try and restart it again, like an old car Tomcat may not start the first time you try to crank it over.