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 tasks continue the installation process by optimizing the performance and behavior of your server. None of the tasks below are strictly required, but some are recommended, especially for production servers.
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 Webapp Memory
Configure the Tomcat Default Port Number (Recommended)
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 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. 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 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
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 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.
WebSockets and Load Balancers or Proxies (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 NGIX, 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."
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