Configure Tomcat to Run the LabKey Server Web Application

Follow these steps to run LabKey Server on Tomcat:

1. Move the LabKey Server Libraries
2. Configure your LabKey Server home directory
3. Move the LabKey Server Binary Files and Add a Path Reference
4. Move the LabKey Server Configuration File
5. Replace Values in the LabKey Server Configuration File
6. Configure Webapp Memory
7. Configure LabKey Server to Run Under SSL (Recommended)
8. Configure Tomcat Session Timeout (Optional)
9. Configure Tomcat to Support Extended Characters in URLs (Optional)
10. Configure Tomcat to Use Gzip (Optional)
11. Start the Server

1. Move the LabKey Server Libraries

If you did not download and unzip the LabKey Server binaries in the previous step, do so here.

Copy the following JAR files to the <tomcat-home>/lib directory:

tomcat-lib/ant.jar
tomcat-lib/jtds.jar
tomcat-lib/mail.jar
tomcat-lib/mysql.jar
tomcat-lib/postgresql.jar
tomcat-lib/labkeyBootstrap.jar

2. Configure your LabKey Server home directory

Create a location for your LabKey Server program files. We will refer to this as <labkey_home>:

• On Windows the default is C:/Program Files (x86)/LabKey Server
• On Unix the default is /usr/local/labkey

sudo chown steveh /usr/local/labkey

Copy the following directories to <labkey_home>:

/bin
/labkeywebapp 
/modules 
/pipeline-lib

3. Move the LabKey Server Binary Files and Add a Path Reference

The Windows LabKey Server binary distribution includes a /bin directory that contains a number of pre-built Windows executable files required by LabKey Server. On Windows, you have already moved this directory to <labkey_home> in the previous step. On Unix you must download and either install or build these components for your system, and install them to <labkey_home>/bin. For more information see Third-Party Components and Licenses.

Once the components are in place, add a reference to this directory to the system path of the user account that will start Tomcat.

4. Move the LabKey Server Configuration File

The LabKey Server configuration file, named labkey.xml by default, contains a number of settings required by LabKey Server to run. This file must be moved into the <tomcat-home>/conf/Catalina/localhost directory.

5. Replace Values in the LabKey Server Configuration File

The LabKey Server configuration file contains basic settings for your LabKey Server application. When you install manually, you need to edit this file to provide these settings. The parameters you need to change are surrounded by "@@", for example, @@appDocBase@@, @@jdbcUser@@, @@jdbcPassword@@, etc.

• Replace @@appDocBase@@ with <labkey_home>/labkeywebapp
• Replace @@jdbcUser@@ & @@jdbcPassword@@ with administrator credentials for your chosen database (PostgreSQL or SQL Server).

6. Configure Webapp Memory

Follow the instructions in the following topic: Configure Webapp Memory.

7. Configure LabKey Server to Run Under SSL (Recommended)

You can configure LabKey Server to run under SSL (Secure Sockets Layer). We recommend that you take this step if you are setting up a production server to run over a network or over the Internet, so that your passwords and data are not passed over the network in clear text.

To configure Tomcat to run LabKey Server under SSL:

• Follow the instructions in the Tomcat documentation: SSL Configuration How-To.
• Note that Tomcat's default SSL port is 8443, while the standard port for SSL connections recognized by web browsers is 443. To use the standard port, change this port number in the server.xml file.

• In the LabKey Server Admin Console (Admin > Site > Admin Console), click the Site Settings link.
• Check Require SSL connections.
• Enter the SSL port number that you configured in the previous step in the SSL Port field.

8. Configure Tomcat Session Timeout (Optional)

Tomcat's session timeout specifies how long a user remains logged in after their last session activity, 30 minutes by default. To increase session timeout, edit <tomcat-home>/conf/web.xml . Locate the <session-timeout> tag and set the value to the desired number of minutes.

9. Configure Tomcat to Support Extended Characters in URLs (Optional)

If you originally installed LabKey using the graphical installer, Tomcat is automatically configured to support extended characters.

If you installed Tomcat manually, it does not by default handle extended characters in URLs. To configure Tomcat to handle extended characters:

• Edit the <tomcat-home>/conf/server.xml file.
• Add the following two attributes to the Tomcat connector via which users are connecting to LabKey Server:

useBodyEncodingForURI="true"
URIEncoding="UTF-8"

For example, the modified Tomcat non-SSL HTTP/1.1 connector might appear as follows:

<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector port="8080" maxHttpHeaderSize="8192"
           maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
           enableLookups="false" redirectPort="8443" acceptCount="100"
           connectionTimeout="20000" disableUploadTimeout="true"
           useBodyEncodingForURI="true" URIEncoding="UTF-8"/>

For more information on configuring Tomcat HTTP connectors, see the Tomcat documentation at http://tomcat.apache.org/tomcat-7.0-doc/config/http.html

10. Configure Tomcat to Use Gzip (Optional)

You may be able to improve responsiveness of your sever by configuring Tomcat to use gzip compression when it streams data back to the browser.

You can enable gzip in <tomcat_home>/conf/server.xml by adding a few extra attributes to the active non-SSL <Connector> elements:

compression="on" compressionMinSize="2048"
noCompressionUserAgents="gozilla, traviata"
compressableMimeType="text/html, text/xml, text/javascript, text/plain, text/css, application/json"

Note that there is a comment in the default file that provides basic instructions for enabling gzip. The snippet above improves on the comment's recommendation by enabling compression on a few extra MIME types.

11. Start the Server

Start Tomcat as a Service

If you are using LabKey Server only on your local computer, you can start and stop Tomcat manually using the scripts in <tomcat-home>/bin. In most cases, however, you'll probably want to run Tomcat automatically, so that the operating system manages the server's availability. Running Tomcat as a service is recommended on Windows, and the LabKey Server installer configures Tomcat to start as a service automatically when Windows starts. You can call the service.bat script in the <tomcat-home>/bin directory to install or uninstall Tomcat as a service running on Windows. After Tomcat has been installed as a service, you can use the Windows Services management utility (Control Panel > Administrative Tools > Services) to start, stop, and restart the LabKey Server Apache Tomcat service.

If you are installing on a different operating system, you will probably also want to configure Tomcat to start on system startup.

Start Tomcat with Startup Scripts

You can also start the Tomcat server using the startup scripts in the <tomcat-home>/bin directory.

View the LabKey Server Home Page

After you start the server, point your web browser at http://localhost:8080/labkey/ if you have installed LabKey Server on your local computer, or at http://<server-name>:8080/labkey/ if you have installed LabKey Server on a remote server.

Configure the Tomcat Default Port

Note that in the addresses list above, the port number 8080 is included in the URL. Tomcat uses port 8080 by default, and to load any page served by Tomcat, you must either specify the port number as shown above, or you must configure the Tomcat installation to use a different port number. To configure the Tomcat HTTP connector port, edit the server.xml file in the <tomcat-home>/conf directory. Find the entry that begins with <Connector port="8080" .../> and change the value of the port attribute to the desired port number. In most cases you'll want to change this value to "80", which is the default port number used by web browsers. If you change this value to "80", users will not need to include the port number in the URL to access LabKey Server.

Existing Installations of Tomcat

For detailed version information, see Supported Tomcat Versions.

You can run two web servers on the same machine only if they use different port numbers, so if you have a web server running you may need to reconfigure one to avoid conflicts.

If you have an existing installation of Tomcat, you can configure LabKey Server to run on that installation. Alternately, you can install a separate instance of Tomcat for LabKey Server; in that case you will need to configure each instance of Tomcat to use a different port. If you have another web server running on your computer that uses Tomcat's default port of 8080, you will also need to configure Tomcat to use a different port.

If you receive a JVM_BIND error when you attempt to start Tomcat, it means that the port Tomcat is trying to use is in use by another application. The other application could be another instance of Tomcat, another web server, or some other application. You'll need to configure one of the conflicting applications to use a different port. Note that you may need to reconfigure more than one port setting. For example, in addition to the default HTTP port defined on port 8080, Tomcat also defines a shutdown port at 8005. If you are running more than one instance of Tomcat, you'll need to change the value of the shutdown port for one of them as well.

Next Step in Manual Installation

• labkey.xml Configuration File: Change settings in the labkey.xml file.