The following recommendations and considerations continue the installation process by optimizing the performance and behavior of your server. We recommend that you review and consider your specific server needs and decide how to best configure your system, especially for production servers. Contact your Account Manager for additional guidance when you are using a Premium Edition of LabKey Server.

• Configure the Tomcat Port Number
• Existing Installations of Tomcat
• Security Settings and Considerations
• Configure LabKey Server to Run Under TLS/SSL
• WebSockets
• Set a Content Security Policy
• Recommended Tomcat Settings
• Increase Webapp Memory
• Configure Access Logging
• Configure Tomcat Error Page Handling
• Optional Tomcat Settings
• Configure Tomcat Session Timeout
• Configure Tomcat to Use Gzip

Configure the Tomcat Port Number

Tomcat uses port 8080 by default. To load any page served by Tomcat, you must either specify the port number, or configure the Tomcat installation to use a different port. To configure the Tomcat HTTP connector port, edit the server.xml file at:

<CATALINA_HOME>/conf/server.xml

Find the entry that begins with <Connector port="8080" .../> and change the value of the port attribute to the desired 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

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, OR install a separate instance of Tomcat for LabKey Server. In either case, you will need to configure LabKey to use a port that is not in use by another application.

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.

Security Settings and Considerations

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:

• Create a certificate, following the instructions here: 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.

• Select (Admin) > Site > Admin Console.
• Under Configuration, click Site Settings.
• Check Require SSL connections.
• Enter the SSL/TLS port number that you configured in the previous step in the SSL Port field.

WebSockets (Recommended)

LabKey Server uses WebSockets to push notifications to browsers. This includes a dialog telling the user they have been logged out (either due to an active logout request, or a session timeout). As WebSockets use the same port as HTTP and HTTPS, there is no additional configuration required if you are using Tomcat directly.

If you have a load balancer or proxy in front of Tomcat, like Apache or NGINX, be sure that it is configured in a way that supports WebSockets. LabKey Server uses a "/_websocket" URL prefix for these connections.

Note that while this is recommended for all LabKey Server installations, it is required for full functionality of the Sample Manager and Biologics products.

When WebSockets are not configured, or improperly configured, you will see a variety of errors related to the inability to connect and to trigger notifications and alerts. LabKey Server administrators will see a banner reading "The WebSocket connection failed. LabKey Server uses WebSockets to send notifications and alert users when their session ends."

Set a Content Security Policy

Content-Security-Policy HTTP headers are a powerful security tool, successor to several previous mechanisms such as X-Frame-Option and X-XSS-Protection. Unlike previous HTTP header options, Content-Security-Policy is set at the tomcat level and should not be set only for a single application like LabKey Server.

To facilitate setting a Content-Security-Policy, you can make use of the ContentSecurityPolicy filter in the bootstrap jar. This means you'll add a <filter> section specifying your policy to your web.xml file.

Documentation and examples are available in the source code on GitHub here.

Recommended Tomcat Settings

Increase Webapp Memory (Recommended)

Administrators will see a banner alerting them if the memory allocation for the server is too low.

To increase the memory allocation, follow these instructions: Configure Tomcat Settings.

Configure Access Logging (Recommended)

Tomcat can be configured to log every HTTP access request sent to the server and store it in the filesystem, providing a comprehensive audit trail of actions including file downloads, API calls, guest user actions, etc. To enable this detailed level of logging, edit the server.xml file to include a Valve component defining the format for the log entries.

Learn more and find examples in this topic: Site Access Logs

Configure Tomcat Error Page Handling (Recommended)

Tomcat automatically intercepts some invalid requests and rejects them, including malformed URLs. By default, Tomcat raises an error page with a Java exception and stack trace. These stack traces are sometimes flagged by security scanners as potential vulnerabilities, though they are not. To configure Tomcat to more quietly respond to such errors, add the following to your server.xml's <Host> section:

<Valve className="org.apache.catalina.valves.ErrorReportValve" showReport="false" showServerInfo="false"/>

Learn more in the Tomcat documentation here.

Optional Tomcat Settings

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

Installation Checklist Topics

1. Install on Linux: Main Components OR Install on Windows: Main Components
2. (Current Topic) Installation: Tomcat Configuration
3. Installation: SMTP, Encryption, LDAP, and File Roots
4. Installation: Third-Party Components