BioCoRE - Biological Collaborative Research Environment

Upgrading Tomcat 4.x to 5.x

These instructions assume that you followed the installation instructions for installation, including installing BioCoRE into $BIOCORE_HOME.

This example upgrades from Tomcat 4.1.30 to Tomcat 5.0.28, but the instructions should work, with very minor modifications, for other close versions (anything in the 4.1 tree to anything in the 5.0 tree, at least).

In the packages directory, find a subdirectory called tomcat. In the tomcat directory, uncompress the new Tomcat file that you downloaded from the apache site. Use the GNU version of tar. This will create a directory called jakarta-tomcat-5.0.28 (to go along with the 4.1.30 directory that you already have) At this point, leave the symlink pointing to version 4 until you are told to update it below.

Edit server.xml

You will need to edit the server.xml file in the new Tomcat conf/ directory. We don't recommend simply copying over the old version because a fair amount changed between Tomcat version 4 and Tomcat version 5. First, make a backup of the server.xml file for safety. You will probably want to refer to the server.xml file in your current Tomcat 4 directory for some of the numbers/values you will need for this. Comments in this file start with a <!-- and end with a -->. Anytime that we say to comment something out, you need to place a <!-- before it, and a --> after it.
  • If you aren't running on ports 8080 and 8443 you will need to do a global search and replace on those values in the file.
  • (optional) 15 or 20 lines down in the file there is a section about JMX MBeans support. We want to comment that out. Move the --> to right below the "e.g. descriptors line" down to below the second Listener line (on the line after the debug=0).
  • (optional) 5 or 10 lines down from that, comment out the 
    <Environment name="simpleValue" type="java.lang.Integer" value="30"/>
  • Search for "Define a SSL Coyote HTTP/1.1 Connector on port". This is currently commented out. Uncomment the HTTPS connection by deleting the <!-- that appears right after the line about "Define a SSL Coyote HTTP/1.1 Connector" and delete the --> that appears approx. 6 lines down.

    You now need to add arguments to that Connector. It should (before modifications) look something like: 

        <Connector port="XXXX"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" debug="0" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" />
    You need to add the keystoreFile and keystorePass entries (which should be in your existing Tomcat 4 server.xml file). The end result will look something like the following. Note carefully the placement of the />. 
        <Connector port="XXXX"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" debug="0" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" 
               keystoreFile="/my/safe/place/biocoreKey.crt"
               keystorePass="PASSWORD"     />
    You will, of course, need to use your own values and not the values listed above for keystoreFile and keystorePass. At this point, take a moment to make sure that the path of the keystoreFile points to a valid file. If you have placed the keystore file inside of the Tomcat directory you'll need to copy it over to the new Tomcat directory.
  • In some of the earlier versions of Tomcat 4, we had a Context entry in server.xml. If you have one in your Tomcat 4 server.xml file, you don't need it in the Tomcat 5 version.

BioCoRE Context file

In the conf/Catalina/localhost directory, create a file called biocore.xml with the following contents: 
<Context path="/biocore" docBase="biocore" debug="0" />

Copy files over from older version of Tomcat

If you have modified or added any other files in the conf directory, those will need to be copied in. (If you modified tomcat-users.xml you will need to copy that over. (Check in webapps/ROOT and see if you have put any files in there. Also check to see if you have put the server certificates somewhere in the Tomcat tree) (Note, if you were using the favicon.ico file, be sure to add the following to the web.xml file in the conf directory: 
  <mime-mapping>
    <extension>ico</extension>
    <mime-type>image/x-icon</mime-type>
  </mime-mapping>

A couple of jar files are no longer included in Tomcat 5, so they need to be copied in. Copy mail.jar and activation.jar from your Tomcat 4 directory to the new Tomcat 5 directory. Copy from current/common/lib to the new common/lib.

File Permissions

In the new Tomcat directory make sure that the temp, work, and logs directories are owned by the user that will be running Tomcat. Additionally, make sure that the configuration files in conf/ and the xml files in conf/Catalina/localhost/ are readable by the user that will be running Tomcat.

Shutdown the old Tomcat

Shutdown the old Tomcat server that is running.

Update current symlink

Delete the current symlink the Tomcat directory, and create a new one that points to the 5.0.28 version of Tomcat.

Install BioCoRE files

If you installed via:
  • BioCoRE distribution download:
    In the MySQL installation step you should have unpacked a biocore.war file.

    Change to the $BIOCORE_HOME/packages/tomcat/current/webapps directory and create a subdirectory called biocore. Change to the new directory you just created, and unpack the biocore.war file. 

    $BIOCORE_HOME/java/current/bin/jar xvf /PATH/TO/biocore.war
    This will uncompress the WAR file.

  • Source Distribution:
    do an 'ant deploy'.

Run install script

Run the install.sh script that came in the BioCoRE tar file that you originally downloaded. The script might not be executable. If this is the case you will need to chmod it first.

(optional) Delete unnecessary webapps

You don't need webdav/, tomcat-docs/, jsp-examples, balancer or servlets-examples/ in the webapps directory. You can delete these directories. In addition, you will need to delete the balancer.xml file from conf/Catalina/localhost.

Restart Tomcat

Feedback

The BioCoRE team welcomes any comments, questions, or suggestions that you might have concerning our software! Please email us or fill out our feedback form.