This topic provides instructions for setting the Java Virtual Machine (JVM) memory configuration on Windows, Linux, and OSX operating systems.
What do the JVM memory settings do? LabKey Server is Java web application that runs on Tomcat. The Tomcat server is run within a Java Virtual Machinex (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.
Definitions
- <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.
Change the JVM Memory Configuration on Linux and OSX
Method 1: If Tomcat is running as a service
- Locate the tomcat.service file, typically located at /etc/systemd/system/tomcat.service
- Open the file and edit the CATALINA_OPTS parameter.
- For a production server, use:
-Xms4g -Xmx4g -XX:-HeapDumpOnOutOfMemoryError
- For a test server, use:
-Xms2g -Xmx2g -XX:-HeapDumpOnOutOfMemoryError
Method 2: 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
- Find the line for setting CATALINA_OPTS and add one of the following settings inside the double quotes.
- For a production server, use:
-Xms4g -Xmx4g -XX:-HeapDumpOnOutOfMemoryError
- For a test server, use:
-Xms2g -Xmx2g -XX:-HeapDumpOnOutOfMemoryError
- Save the file
- Restart LabKey Server
Method 3: If you use startup.sh and shutdown.sh to start/stop LabKey Server
The start script is located in
<CATALINA_HOME>/bin/catalina.sh
- Open the Start script using your favorite text editor
- 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 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:
You will need to use this method if you customized the name of the LabKey Windows Service.
- 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
NOTE: The text after the //ES// must exactly match the name of the Windows Service that is being used to start/stop your LabKey Server. You can determine the name of your Windows Service by taking the following actions:
- Open the Windows Services panel. (Click Start, type "Services", and press the Enter key.)
- In the Services panel, find the entry for LabKey Server. It might be called something like Apache Tomcat or LabKey
- Double-click on the service to open the properties dialog.
In the command above, replace the text "LabKeyTomcat#" with the text shown next to ServiceName in the Properties dialog.
Related Topics
Back to
Installation: Tomcat Configuration