Service File Customizations: /Documentation

Service File Customizations

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 Tomcat Settings in Service File
Common Changes for Environment and Paths

Linux
Windows

Increase Webapp Memory (Recommended)
Check Tomcat Settings

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

Linux

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

/etc/systemd/system/labkey_server.service

Within this file's Environment section, several "JAR_OPTS" 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"

Windows

On Windows, you'll use the distribution's "install_service.bat" file, typically locating it in:

<LABKEY_HOME>/install_service.bat

The list of parameters passed includes these 'Jvm' lines at the end:

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

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:

Run prunsrv.exe //DS//labkeyServer
Edit install_service.bat with the preferred values.
Run the install_service.bat
Start up the service.

Common Changes for Environment and Paths

Linux

On Linux, you will need to customize the following:

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" ^
```

The install_service.bat file and prunsrv.exe program must both be in the same location.

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:
```
--JvmMs 4096 ^
  --JvmMx 4096
```

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.

LabKey Support

LabKey Support