BioCoRE - Biological Collaborative Research Environment

Installing Tomcat

In the last step, you decided where (on your filesystem) to install BioCoRE. We are going to call this location $BIOCORE_HOME. EVERYWHERE YOU SEE $BIOCORE_HOME REPLACE IT WITH YOUR CHOSEN DIRECTORY.

This example installation uses Tomcat 5.0.28. Newer versions (in the 5.0.x series) might be out when you read this, and you should use the newer versions if they are available.

In the packages directory, create a subdirectory called tomcat. In the tomcat directory, uncompress the Tomcat file that you downloaded. Use the GNU version of tar, as some of the file names are too long for other versions of tar (noticeably Solaris' version). This will create a directory called jakarta-tomcat-5.0.28. Create a symlink for current like you have done in previous steps.

Make the server talk securely

Real Certificate

We suggest that you get a real Webserver certificate from Verisign or Thawte. If you have a real certificate, you can jump to the instructions on how to install the official certificate into Tomcat.

Test Certificate

If you don't have a real certificate, you can make a personal certificate (but anyone visiting BioCoRE will be prompted by their browser to confirm that they want to connect).

To make a personal certificate, decide on a secure location on your system where you can put the certificate file. This location needs to be readable by the Unix user you will have running the BioCoRE Tomcat server (usually someone like 'httpd', or 'webserver'). Let's say that our file is going to be at the location: /my/safe/place/biocoreKey.crt

Issue the following command: 

$BIOCORE_HOME/java/current/bin/keytool    \
           -genkey -alias tomcat -keyalg RSA   \
           -validity 365 \
           -keystore /my/safe/place/biocoreKey.crt

(The -validity option gives the number of days that you want the certificate to last before expiring. The default is 90 days, but setting it to 365 insures that you won't have to worry about this for a year. (Disclaimer: shorter times are better for security. Longer times are more convenient for you))

When asked for your first and last name, don't enter your name. Instead, enter the machine name where you will be running the BioCoRE server. For instance, if you are going to be running BioCoRE on the machine biocore.our.site.edu, enter biocore.our.site.edu for the name. When asked for a password, remember what you type (for this example, let's say you make your password PASSWORD) When asked for the second password, just hit <ENTER> to use the same password.

Setting up the Tomcat config file

The global Tomcat configuration directory is at $BIOCORE_HOME/packages/tomcat/current/conf/. There is a server.xml file in that directory that you will need to work with. First, make a backup of the file before you start to edit it, just for safety. Copy server.xml by saying something like cp server.xml server.xml.orig. You then need to modify server.xml.

  • Tomcat defaults to accepting connections on ports 8080/8443. We suggest that you run BioCoRE on the standard http/https ports (which are 80 and 443, respectively) to make it easy on your users (They can go to https://your.machine/biocore/etc instead of https://your.machine:8443/biocore/etc). This does have a few side effects, though. Unix requires all ports below 1024 to be bound by the root user (and only the root user). Using 'root' to run any program that doesn't absolutely have to be run by root is generally considered a bad idea. There isn't any reason other than this port number restriction that Tomcat needs to be run as 'root' and we don't suggest running Tomcat as root. We have tried to make BioCoRE as secure as possible, but we can't guarantee that. If you want users to be able to access BioCoRE via ports 80/443, you could install a program that can redirect connections to port 80 to some other port (let's say port 3298). Then, you can direct Tomcat to accept connections on this "other" port (3298 in this example). Examples of programs that can work for you are IPFilter, reverb, etc. We have included a sample C program in the 'tunnel' directory of the distribution that you are welcome to use. The program isn't supported. We also have experience with a small perl script called 'tunnel' that has worked well enough. You can get more information about it here. (Note: This might seem to be a trivial paragraph, but be prepared to spent a little bit of time getting the port redirection set up properly if you wish to do it. If you don't mind having users accessing BioCoRE having an additional number in the URL (such as 8443, https://your.machine:8443/biocore/etc) then you don't need to bother with port redirection.)

    If you wish to change the default ports from 8080/8443 to something else, do a global search and replace on 8080 and replace it with with the port number you would like to use. Likewise, do a global search and replace on 8443 and replace it with the secure port number you wish to use.

  • (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.

    Now that we have it uncommented, we need to modify it for our situation. It should (before modifications) look something like (where XXXX is whatever port number you have chosen for https connections): 

        <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. 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"     />
    (If you followed the previous instructions to use a real certificate, the keystoreFile will be in $BIOCORE_HOME/packages/tomcat/current/conf/keystore.tomcat)

Check Permissions

Go into the current directory and make sure that the temp/ directory, the work/ directory, and the logs/ directory are owned by whoever 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.

Install mail.jar and activation.jar in the Tomcat directory

In the download step you downloaded JavaMail and Java Activation Framework. Now that you have Tomcat almost set up, you can put the two jar files where they need to be. Copy mail.jar from JavaMail and activation.jar from the Java Activation Framework into $BIOCORE_HOME/packages/tomcat/current/common/lib.

Tomcat is now set up!

Next Step: Test Tomcat.
Back to the installation page

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.