Overview

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
    • On Linux or OSX, this location is most likely
      • /usr/local/tomcat
    • On Windows, this location is most likely (where x.x.xx is the version number of Tomcat)
      • C:\Program Files (x86)\LabKey Server\apache-tomcat-x.x.xx or
      • C:\Program Files\LabKey Server\apache-tomcat-x.x.xx

Instructions for changing the JVM memory configuration on Windows Computers

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.

Method 1:

  1. Open Windows Explorer
  2. Go to the CATALINA_HOME directory
  3. Double-click on the bin directory
  4. Double-click on tomcat9w.exe or tomcat9w.exe. 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.
  5. Go to the Java tab in the new window.
  6. In the Java Options box, scroll to the bottom of the properties, and set the following property:
    -XX:-HeapDumpOnOutOfMemoryError
  7. Change the Initial memory pool to 2GB for a test server or 4GB for a production server.
  8. Change the Maximum memory pool to the same value.
  9. Click the OK button
  10. Restart LabKey Server

Method 2:

You will need to use this method if you customized the name of the LabKey Windows Service.

  1. Open a Command Prompt. (Click Start, type "cmd", and press the Enter key.)
  2. Change to the CATALINA_HOME\bindirectory. For example:
    cd "C:\Program Files\LabKey Server\apache-tomcat-x.x.xx\bin"
  3. Execute the following for Tomcat 9. Make appropriate changes if you are running a different version of Tomcat. 

    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.
  4. Go to the Java tab in the new window.
  5. In the Java Options box, scroll to the bottom of the properties, and set the following property:
    -XX:-HeapDumpOnOutOfMemoryError
  6. Change the Initial memory pool to 2GB for a test server or 4GB for a production server.
  7. Change the Maximum memory pool to the same value.
  8. Click the OK button
  9. 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:

  1. Open the Windows Services panel. (Click Start, type "Services", and press the Enter key.) 
  2. In the Service panel, find the entry for LabKey Server. It might be called something like Apache Tomcat or LabKey
  3. Double-click on the service.
  4. In the command above, replace the text LabKeyTomcatX with the text shown next to ServiceName in the Properties dialog.

Instructions for changing the JVM Heap Size on Linux and OSX

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

  1. Find the JSVC service script.
    • On Linux servers, this is usually in the /etc/init.d directory and named either tomcat or tomcat9
    • On OSX servers this might be in /usr/local/jsvc/Tomcat9.sh
  2. Open the JSVC service script using your favorite editor
  3. Find the line for setting CATALINA_OPTS and add 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
    
  4. Save the file
  5. Restart LabKey Server

Method 2: If you use startup.sh and shutdown.sh to start/stop LabKey Server

  1. The start script is located at CATALINA_HOME/bin/catalina.sh
  2. Open the Start script using your favorite editor
  3. Review the file
  4. Above the line with "# OS specific support. $var _must_ be set to either true or false." add the following line.

    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"
  5. Save the file
  6. Restart LabKey Server

Related Topics

  • See Wikipedia for more information the JVM heap memory.

Discussion

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand all collapse all