Windows Install Part 2: Configure the LabKey Web Application

This topic assumes you have completed the topic Windows Install Part 1: Install Required Components which explains how to install the core LabKey Server components

Once you have installed the core components, use the following installation tasks to optimize the performance and behavior of your server. None of the tasks below are strictly required, but some are recommended, especially for production servers.

Increase Java Heap Size (Recommended)

You can clear the Java heap memory warning banner by increasing the memory available to the server.

  • Open Windows Explorer.
  • Go to the <CATALINA_HOME>\bin directory.
  • Run tomcat#w.exe (replacing the # with the major version number). On some operating systems, you may have to run this as an administrator; if so, right-click the .exe file and select Run as administrator.
  • The command will open a program window.
  • Click the Java tab in the new window.
  • In the Java Options box, scroll to the bottom of the properties, and set the following property:
  • Change the Initial memory pool to 2000MB for a test server or 4000MB for a production server.
  • Change the Maximum memory pool to the same value.
  • Click OK
  • On the Services panel, restart Tomcat.

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 require that users connect to LabKey Server using a secure (https) connection:
  • In the LabKey Server Admin Console ( (Admin) > Site > Admin Console), click Settings, then 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.
An example server.xml file is available at:

Configure the Tomcat Default Port (Optional)

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 CATALINA_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.

Working with Multiple Installations of Tomcat

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.

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.

Configure Tomcat to Use Gzip (Optional)

You may be able to improve the 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.

Configure Tomcat to Support Extended Characters in URLs (Optional)

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.

Windows Install Part 1: Install Required Components


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all