Setting up Tomcat

Attention

NOTE: Starting with Camano 3.1, we recommend using Tomcat 7 instead of the customized Tomcat 5.5 described below. Do not use these instructions for Tomcat 7.

Overview

Please note that you cannot use an off-the shelf version of Tomcat 5.5 or another webapp engine like Jetty. You must use the version provided on this website.

Installation and Configuration

We provide a customized version of Tomcat 5.5 with ORCA-specific start/stop scripts which should be customized to the specific site. Download and install our version of Tomcat 5.5: under $ORCA_HOME:

$ cd $ORCA_HOME
$ wget https://geni-orca.renci.org/svn/software/tomcat.tar.gz
$ tar zxvf tomcat.tar.gz
$ cd $ORCA_HOME/tomcat

Edit $ORCA_HOME/tomcat/start.sh and $ORCA_HOME/tomcat/stop.sh to point to correct paths for ORCA_HOME and CATALINA_HOME. Example start.sh

#!/bin/bash

# customize this to your setup
export ORCA_HOME=/opt/orca

# if you are using non-standard java, uncomment and change this
# export JAVA_HOME=/opt/java/jdk-1.6.20
export LD_LIBRARY_PATH=/usr/local/lib

# assuming tomcat is under $ORCA_HOME
export CATALINA_HOME=$ORCA_HOME/tomcat

# if you want to enable debugging, uncomment this line and comment out the following one. Default debug port is 11000
#declare -x CATALINA_OPTS="-ea -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=11000 -Xmx1024m"
declare -x CATALINA_OPTS="-Xmx1024m"

export ANT_HOME=
$CATALINA_HOME/bin/catalina.sh start

Example of stop.sh.

#!/bin/bash

# customize this to your install
export ORCA_HOME=/opt/orca

# uncomment and customize this if you are using non-standard Java install
#export JAVA_HOME=/opt/java/jdk1.6.0_23

# assuming tomcat lives under $ORCA_HOME
export CATALINA_HOME=$ORCA_HOME/tomcat

$CATALINA_HOME/bin/shutdown.sh

Enabling webauth

This step is optional and needed only if using your institution's SSO (not widely tested): edit tomcat/conf/server.xml and tomcat/server/classes/webauth.xml to change references to '/shirako' to the new location of the directory you created (e.g., /opt/orca). Only do this step if you are using webauth authentication. If you are not sure, then you are not. Webauth authentication requires significant setup from your identity provider.

Enabling SSL in Tomcat

For some deployments (particularly SM), it may be necessary to enable SSL support in Tomcat. This step is optional and is explicitly called for when needed in other documents.

  • You must uncomment part of Tomcat server configuration file to enable SSL support. Open $ORCA_HOME/tomcat/conf/server.xml in an editor and locate the Connector definition for port 11443 and uncomment it.
  • You must also create a $ORCA_SRC/tomcat/ssl/tomcat.jks keystore with a password (default password is in the definition of the Connector above).
    $ keytool -genkey -alias tomcat -keyalg RSA -keystore $ORCA_HOME/tomcat/ssl/tomcat.jks
    
  • Restart Tomcat and verify that it works on port 11443 by hitting https://hostname:11443/orca with your browser (you will get a security exception because the certificate is self-signed).

More on this is available here.