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 either Install on Linux or Install on 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.

• Update Paths and Settings in Service File
• Linux
• Windows
• Increase Webapp Memory (Recommended)
• Linux: Access to Privileged Ports
• Check Tomcat Settings

Update Paths and Settings in Service File

Linux

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

/etc/systemd/system/labkey_server.service

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 this line to read as follows - this substitution will be made for you, or you may use the full path if desired:

  -XX:ErrorFile=$LABKEY_HOME/logs/error_%p.log \

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

Windows

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:

<LABKEY_HOME>/install_service.bat
<LABKEY_HOME>/prunsrv.exe

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

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 'ms' (amount allocated at startup) and 'mx' (max allocation). In this example, we set them both to 4GB.

• On Linux: Edit these settings on the JAVA_PRE_JAR_OPS line:

  -Xms4g -Xmx4g

• On Windows: Edit these two lines at the bottom of the argument list (the default units are megabytes):

  --JvmMs 4096 ^
  --JvmMx 4096

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:

[Service]
Type=simple
AmbientCapabilities=CAP_NET_BIND_SERVICE
...

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.

Customizations for Previous Service File Defaults in Versions 24.3.0-24.3.3

This section is provided for reference and troubleshooting purposes. We recommend that you obtain and use the service file defaults included in version 24.3.4 or higher.

Linux

On Linux, you will need to customize the following:

Within this file's Environment section, several "*_JAR_OPS" lines are included related to server operations with default settings shown here:

Environment="JAVA_PRE_JAR_OPS=-Duser.timezone=America/Los_Angeles -Djava.library.path=/usr/lib/x86_64-linux-gnu -Djava.awt.headless=true -Xms1932M -Xmx1932M -Djava.security.egd=file:/dev/./urandom"
Environment="JAVA_MID_JAR_OPS=-XX:+HeapDumpOnOutOfMemoryError -XX:+UseContainerSupport -XX:HeapDumpPath=/labkey/labkey/labkey-tmp -Djava.net.preferIPv4Stack=true"
Environment="LABKEY_JAR_OPS=-Dlabkey.home=/labkey/labkey -Dlabkey.log.home=/labkey/labkey/logs -Djava.io.tmpdir=/labkey/labkey/labkey-tmp"

• Update the setting of JAVA_HOME to be the full path to your Java installation.
• You may also need to update the setting for java.library.path (in the JAVA_PRE_JAR_OPS).
• Edit the ExecStart line to replace "$JAVA_HOME" with the full path to java you set as JAVA_HOME in the section above. The service will not make this substitution for you.
• You will likely need to increase the webapp memory from the service file's default (-Xms and -Xmx values).
• If you are not using /labkey/labkey as the <LABKEY_HOME>, there are several places to update this path in the file.
• The line setting the the java.io.tmpdir should be <LABKEY_HOME>/labkey-tmp.

Windows

On Windows, you will generally need to customize the following:

• Path for LABKEY_HOME variable (<LK_ROOT>\labkey)
• Path for LABKEY_APPS (should be <LK_ROOT>\apps)
• Path for JAVA_HOME
• The line for prunsrv.exe should be changed to read:

  --Install "%LABKEY_HOME%\prunsrv.exe" ^

--JvmOptions "-Djava.io.tmpdir=%LABKEY_HOME%labkey-tmp;-XX:+HeapDumpOnOutOfMemoryError;-XX:HeapDumpPath=%LABKEY_HOME%labkey-tmp;-DterminateOnStartupFailure=true;%JvmArgs%" ^
    --JvmOptions9 "--add-opens=java.base/java.lang=ALL-UNNAMED#--add-opens=java.base/java.io=ALL-UNNAMED#--add-opens=java.base/java.util=ALL-UNNAMED#--add-opens=java.base/java.util.concurrent=ALL-UNNAMED#--add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED" ^
    --JvmMs 2048 ^
    --JvmMx 2048

Related Topics

• Troubleshoot Service Issues
• Set Application Properties
• Configure Access Logging