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 TLS/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 now.

Copy all the JAR files from the unzipped package's tomcat-lib directory to the <CATALINA_HOME>/lib directory. These include:

• jtds.jar
• mail.jar
• mysql.jar
• postgresql.jar
• labkeyBootstrap.jar
• javax.activation.jar

2. Configure your LabKey Home directory

Navigate to the <LABKEY_HOME> directory you created earlier, i.e. the <LABKEY_ROOT>/labkey subdirectory.

• On Windows the default <LABKEY_HOME> is C:\labkey\labkey
• On Unix the default <LABKEY_HOME> is /usr/local/labkey/labkey

sudo chown steveh /usr/local/labkey/labkey

Copy the following directories from the unzipped binaries to the <LABKEY_HOME> subdirectory, i.e. to <LABKEY_ROOT>/labkey.

• /bin (only applicable in Windows distributions)
• /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 (Optional Install).

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. Find it in the unzipped distribution and move this file into the following location. Create the intermediate "Catalina" and "localhost" subdirectories if necessary to make it possible to place it here:

• <CATALINA_HOME>/conf/Catalina/localhost/labkey.xml.

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.

In order to make them easier to find, the parameter values you need to change are surrounded by "@@" in the template we provide. For example, @@appDocBase@@, @@jdbcUser@@, @@jdbcPassword@@, etc. stand in for the actual values you will enter here.

• Replace @@appDocBase@@ with <LABKEY_HOME>/labkeywebapp (use the full path, i.e. C:\labkey\labkey\labkeywebapp
• Replace @@jdbcUser@@ and @@jdbcPassword@@ with administrator credentials for your chosen database (PostgreSQL or SQL Server).

6. Configure Webapp Memory

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

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

You can configure LabKey Server to run under TLS (Transport Layer Security), or it's predecessor, SSL (Secure Socket 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/TLS:

• To create a certificate, follow the instructions at: Creating & Installing SSL/TLS Certificates on Tomcat
• Also follow the instructions in the Tomcat documentation: SSL/TLS Configuration How-To.
• Note that Tomcat's default port is 8443, while the standard port for HTTPS 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 Settings, then under Configuration, click the Site Settings link.
• Check Require SSL connections.
• Enter the SSL/TLS 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 <CATALINA_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

We strongly recommend running on Tomcat 8.5.x or 9.0.x. These versions are configured to support extended characters by default.

If you are running on Tomcat 7.x then you will need to configure it to handle extended characters.

10. Configure Tomcat to Use Gzip (Optional)

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

You can enable gzip in <CATALINA_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 <CATALINA_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. You can call the service.bat script in the <CATALINA_HOME>/bin directory to install or uninstall Tomcat as a service running on Windows.

Navigate to <CATALINA_HOME>/bin and run:

service.bat install

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 <CATALINA_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 Reference: Change settings in the labkey.xml file.