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

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

Upgrade note: This topic is specifically for setting these properties for LabKey with embedded Tomcat 10, i.e. versions 24.3 and higher. 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.

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

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

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.

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:
```
-Xms2g 
-Xmx2g 
```
On Windows: Edit these lines (the units are megabytes):
```
--JvmMs 2048 ^
--JvmMx 2048
```

Linux: Access to Privileged Ports

On Linux, ports 1-1023 are "privileged ports". If the service will need access to any such 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 > Site > Admin Console.
Under Diagnostics, click System Properties to see all the current settings.

LabKey Support

LabKey Support