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 2GB for a test server, and 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.
  • Tomcat Version: Find the current recommended version of tomcat in this topic: Supported Technologies. This topic uses # to stand in for the version number.

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.
  • Run tomcat#w.exe (replacing the # with the major version number). On some operating systems, you may have to run this as an administrator; if so, right-click the .exe file and select 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 2GB for a test server or 4GB 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.

Change the JVM Heap Size on Linux and OSX

Method 1: 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 2: 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

Related Topics

See Wikipedia for more information about the JVM heap memory.

Discussion

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand all collapse all