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.
packages directory, create a subdirectory
tomcat. In the
uncompress the Tomcat file that you downloaded. Use the GNU version
tar, as some of the file names are too long for other
tar (noticeably Solaris' version). This will
create a directory called
jakarta-tomcat-5.0.28. Create a
current like you have done in previous steps.
Make the server talk securely
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.
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:
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
for the name. When asked for a password, remember what you type (for
this example, let's say you make your password
When asked for the second password, just hit <ENTER> to use the
Setting up the Tomcat config file
The global Tomcat configuration directory is at
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
- 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: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
XXXXis 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
keystorePassentries. 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
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
Tomcat is now set up!