LabKey Server now includes embedded Tomcat. This topic covers how an administrator can customize Tomcat settings and other configuration options by editing the service file used to start the server. The primary example in this topic is configuring memory configurations, but other flags can be set using these methods.

This topic assumes you have completed the installation steps in Install on Linux. (Windows is no longer supported for new installations.) You may also be using this topic during the upgrade of a system on either Linux or Windows. The mechanisms for editing the respective services differs, as noted below.

Contact your Account Manager for additional guidance when you are using a Premium Edition of LabKey Server.

We recommend that you use the service file defaults included with version 24.3.4 or higher. If you used an earlier distribution of 24.3, switch to using the newer default. You may also use the documentation archives for help troubleshooting service issues.

Update Paths and Settings in Service File

Upgrade note: This topic is specifically for setting these properties for LabKey version 24.3 with embedded Tomcat 10. In previous versions, the settings were controlled in CATALINA_OPTS or JAVA_OPTS, or set via utility, depending on your platform.

As a general best practice, review your older configuration files side by side with the new service file to make it easier to selectively migrate necessary settings and values. Note that if you were not using a particular setting previously, you do not need to add it now, even if it appears in our defaults.


The distribution includes an initial "labkey_server.service" file you will use to run your server on Linux, typically from this location:


Customize this file as follows:

  • Update the Environment setting for JAVA_HOME to be the full path to your Java installation. Following our instructions this will be /labkey/apps/jdk-17 or similar.
  • Edit the ExecStart line to replace "<JAVA_HOME>" with the full path to java (i.e. /labkey/apps/jdk-17/bin/java). The service will not make this substitution for you.
  • If you are not using /labkey/labkey as the <LABKEY_HOME>, update that Environment setting.
    • Also update any other places in the default that use that "/labkey/labkey" path to match your <LABKEY_HOME>.
    • For example, if you see an ErrorFile line, update it to read as follows (the substitution will be made for you):
      -XX:ErrorFile=$LABKEY_HOME/logs/error_%p.log \
You will likely need to increase the webapp memory from the service file's default (-Xms and -Xmx values).

If you are using privileged ports, such as 443 for HTTPS, see below for how to grant access to them.


You'll use the distribution's "install_service.bat" file to run the server as a Windows service. The .bat file must be in the same location where you install "prunsrv.exe", typically both will be in:


Customize the following in your install_service.bat file:

  • Path for LABKEY_HOME variable (<LK_ROOT>\labkey)
  • Path for LABKEY_APPS (should be <LK_ROOT>\apps)
  • Path for JAVA_HOME
After editing the batch file, you need to delete the existing service in order to install a fresh version with updates. The procedure for making any updates is:
  1. Run prunsrv.exe //DS//labkeyServer
  2. Edit install_service.bat with the preferred values.
  3. Run the install_service.bat
  4. Start up the service.

Increase Webapp Memory (Recommended)

The Tomcat server is run within a Java Virtual Machine (JVM). This JVM that controls the amount of memory available to LabKey Server. LabKey recommends that the Tomcat web application be configured to have a maximum Java Heap size of at least 2GB for a test server, and at least 4GB for a production server. Distributions include service files setting the heap to 2GB. In both cases the HeapDumpOnOutOfMemoryError setting is preconfigured and should not require adjustment.

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

To increase the memory allocation, set a higher value for both 'Xms/JvmMs' (amount allocated at startup) and 'Xmx/JvmMx' (max allocation).

  • On Linux: Edit these lines:
  • On Windows: Edit these lines (the units are megabytes):
    --JvmMs 2048 ^
    --JvmMx 2048

Linux: Access to Privileged Ports

If the service will need access to privileged ports, such as for using 443 for HTTPS traffic, set the Ambient Capabilities in the [Service] section:


There are other methods for providing access, including using setcap.

Check Tomcat Settings

On a running server, an administrator can confirm intended settings after restarting the server.

  • Select (Admin) > Site > Admin Console.
  • Under Diagnostics, click System Properties to see all the current settings.

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all