After you've installed all of the required components, you need to follow some additional steps to configure LabKey Server to run on Tomcat. These steps apply to either a new or an existing Tomcat installation.
Configure Tomcat to Run the LabKey Server Web Application
Follow these steps to run LabKey Server on Tomcat:
- Move the LabKey Server Libraries
- Configure your LabKey Server home directory
- Move the LabKey Server Binary Files and Add a Path Reference
- Move the LabKey Server Configuration File
- Replace Values in the LabKey Server Configuration File
- Configure Webapp Memory
- Configure LabKey Server to Run Under SSL (Recommended)
- Configure Tomcat Session Timeout (Optional)
- Configure Tomcat to Support Extended Characters in URLs (Optional)
- Configure Tomcat to Use Gzip (Optional)
- 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
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
On Unix systems, ensure that you have ownership over <labkey_home> by calling "sudo chown". (Failing to do this can cause problems with the pipeline file root.) For example, the user "steve" assumes ownership of <labkey_home> using the following command:
sudo chown steveh /usr/local/labkey
Copy the following directories to <labkey_home>
/bin (only in Windows distributions)
- Make sure that you do not move the /labkeywebapp directory to the <tomcat-home>/webapps folder.
- The user who is executing the Tomcat process must have write permissions for the /labkeywebapp and /modules directories.
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. This file must be moved into the <tomcat-home>/conf/Catalina/localhost
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@@
- Replace @@appDocBase@@ with <labkey_home>/labkeywebapp
- Replace @@jdbcUser@@ & @@jdbcPassword@@ with administrator credentials for your chosen database (PostgreSQL or SQL Server).
For more information on replacing values in labkey.xml, see labkey.xml Configuration File
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:
- To create an SSL certificate, follow the instructions at: Creating & Installing SSL Certificate on Tomcat
- Also 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.
To require that users connect to LabKey Server using a secure (https) connection:
- 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.
An example server.xml file is available at: https://github.com/LabKey/samples/blob/master/ops/config-examples/server-SSL.xml
Also see LabKey's Recommended SSL configuration for LabKey Servers
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
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 <tomcat_home>/conf/server.xml by adding a few extra attributes to the active non-SSL <Connector> elements:
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
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