This topic assumes you have completed the installation steps in either Install on Linux: Main Components or Install on Windows: Main Components
, which explain how to install the core LabKey Server components.
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
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:
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:
To require that users connect to LabKey Server using a secure (https) connection:
- 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.
An example server.xml file is available at: https://github.com/LabKey/samples/blob/main/ops/config-examples/server-SSL.xml
Note that if you are using a Load Balancer or Proxy "in front of" LabKey, also enabling SSL/TLS may create conflicts as the proxy is also trying to handle the HTTPS traffic. This is not always problematic, as we have had success using Amazon's Application Load Balancer, but we have observed conflicts with versions from Apache, Nginx, and HA-Proxy. Review also the section about WebSockets
If you configure SSL/TLS and then cannot access the server, you may need to disable it in the database directly in order to resolve the issue. Learn more in this topic:
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:
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
- Install on Linux: Main Components OR Install on Windows: Main Components
- (Current Topic) Installation: Tomcat Configuration
- Installation: SMTP, Encryption, LDAP, and File Roots
- Installation: Third-Party Components