• Tomcat Settings (JAVA_OPTS and CATALINA_OPTS)
• Locate Tomcat and the Settings File
• Change the JVM Memory Configuration on Linux and OSX
• Change the JVM Memory Configuration on Windows
• Check Tomcat Settings

Tomcat Settings (JAVA_OPTS and CATALINA_OPTS)

LabKey Server is Java web application that runs on Tomcat. Many important Tomcat configuration settings can be defined using properties defined in CATALINA_OPTS or JAVA_OPTS, or set via utility, depending on your platform. The primary example in this topic is configuring memory configurations, but other flags can also be set using these methods.

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.

Locate Tomcat and the Settings File

• <CATALINA_HOME>: Installation location of the Apache Tomcat Web Server. If you are following our recommended folder configuration, the location will be (where #.#.## is the specific version installed):

  <LABKEY_ROOT>/apps/apache-tomcat-#.#.##

• On Linux or OSX, you may also have created a symbolic link /usr/local/tomcat to this location.

Method 1: If Tomcat is Running as a Service (Most common)

• Locate the tomcat.service file. For example, it might be /etc/systemd/system/tomcat.service (or tomcat_lk.service)
• Open the file and look for the CATALINA_OPTS parameter.
• If you don't see this in the file for a running server, proceed to check via another method.
• Edit memory settings as described below.

Method 2: If Tomcat is not Running as a Service

Identify where your CATALINA_OPTS (or JAVA_OPTS) are defined, often in a directory with other tomcat scripts. Depending on your platform and configuration, it could be in several locations including (but not limited to):

• /etc/systemd/system
• /etc/default
• /usr/local/jsvc/
• <CATALINA_HOME>/bin/

• tomcat.service
• tomcat_lk.service
• Tomcat#.sh
• tomcat
• setenv.sh

Method 3: If you use JSVC to start/stop LabKey Server

• Find the JSVC service script.
• On Linux servers, this is usually in the /etc/init.d directory and named either "tomcat" or "tomcat#"
• On OSX servers this might be in /usr/local/jsvc/Tomcat#.sh
• Open the JSVC service script using your favorite editor and check that it contains the CATALINA_OPTS setting.
• Edit memory settings as described below.

Method 4: If you use startup.sh and shutdown.sh to start/stop LabKey Server (Legacy method)

The start script might be located in <CATALINA_HOME>/bin/catalina.sh. Note that directly hardcoding JAVA_OPTS in this file is not recommended, but if you cannot find these options in any location mentioned above, it might have previously been defined here.

• Open the catalina.sh script
• Above the line reading "# OS specific support. $var _must_ be set to either true or false.: add one of the following:
• For a production server, use:

  JAVA_OPTS="$JAVA_OPTS -Xms4g -Xmx4g -XX:-HeapDumpOnOutOfMemoryError"

• For a test server, use:

  JAVA_OPTS="$JAVA_OPTS -Xms2g -Xmx2g -XX:-HeapDumpOnOutOfMemoryError"

• Save the file
• Restart LabKey Server

Change the JVM Memory Configuration on Linux and OSX

Once you've located your Tomcat settings file, find the line for setting CATALINA_OPTS and add one of the following settings inside the double quotes.

• Stop Tomcat.
• For a production server, use:

  -Xms4g -Xmx4g -XX:-HeapDumpOnOutOfMemoryError

• For a test server, use:

  -Xms2g -Xmx2g -XX:-HeapDumpOnOutOfMemoryError

• Save the file.
• Restart LabKey Server.

Change the JVM Memory Configuration on Windows

Tomcat is usually started as a service on Windows, and it includes a dialog for configuring the JVM. The maximum total memory allocation is configured in its own text box, but other settings are configured in the general JVM options box using the Java command line parameter syntax.

If you changed the name of the LabKey Windows Service, you must use Method 2.

Method 1:

• Open Windows Explorer.
• Go to the <CATALINA_HOME>/bin directory.
• Locate and run the file tomcat#w.exe (where # is the Tomcat version number). Run this as an administrator by right-clicking the .exe file and selecting Run as administrator.
• The command will open a program window.
• If this produces an error that says "The specified service does not exist on the server", then please go to Method 2.
• Go to the Java tab in the new window.
• In the Java Options box, scroll to the bottom of the properties, and set the following property:

  -XX:-HeapDumpOnOutOfMemoryError

• Change the Initial memory pool to 2000 MB for a test server or 4000 MB for a production server.
• Change the Maximum memory pool to the same value.
• Click OK
• Restart LabKey Server.

Method 2:

• Open a Command Prompt. (Click Start, type "cmd", and press the Enter key.)
• Navigate to the <CATALINA_HOME>bin directory.
• Execute the following command, making appropriate changes if you are running a different version of Tomcat. This example is for Tomcat 9:

tomcat9w.exe //ES//LabKeyTomcat9

• The command will open a program window.
• If this produces an error that says "The specified service does not exist on the server", then see the note below.
• Go to the Java tab in the new window.
• In the Java Options box, scroll to the bottom of the properties, and set the following property:

  -XX:-HeapDumpOnOutOfMemoryError

• Change the Initial memory pool to 2GB for a test server or 4GB for a production server.
• Change the Maximum memory pool to the same value.
• Click the OK button
• Restart LabKey Server

Check Tomcat Settings

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

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

Related Topics

Back to Installation: Tomcat Configuration