Overview

LabKey recommends that the Tomcat web application be configured to have a maximum JVM Heap size of 1024MB for a workstation or small test server, and 2048MB for a dedicated server machine. This page includes instructions for changing the Tomcat memory configuration on both Windows and Unix (Linux, MacOSX and Solaris) operating systems.

What do these settings do? As you probably know, LabKey Server is Java web application that runs on Tomcat. The Tomcat server is run within a Java Virtual Machine. It is this Java Virtual Machine (JVM) that controls the amount of memory available to LabKey Server. (See Wikipedia for more information the JVM Heap.)

Definitions

  • CATALINA_HOME: Installation location of the Apache Tomcat Web Server
    • If you performed a Manual Installation and followed these steps, then this is most likely
      • /usr/local/tomcat
    • If you used the LabKey Windows installer, then this is most likely
      • C:\Program Files (x86)\LabKey Server\apache-tomcat-7.0.xx or
      • C:\Program Files\LabKey Server\apache-tomcat-7.0.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 tomcat7w.exe or the tomcat7w program (On some operating systems, you may have to sign on as an administrator to open this program successfully.)
    • 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 be 128
  8. Change the Maximum memory pool to be 1024 for non-servers, 2048 for servers.
  9. Click the OK button
  10. Restart LabKey Server

Method 2:

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

  1. Open a Command Prompt
    • Start —> Programs —> Accessories —> Command Prompt
  2. Change to the CATALINA_HOME\bin directory. For example, if your CATALINA_HOME directory is located at C:\Program Files (x86)\LabKey Server\apache-tomcat-7.0.xx, then the command will be:
    cd "C:\Program Files (x86)\LabKey Server\apache-tomcat-7.0.xx\bin"
  3. Execute the tomcat7w.exe program

    tomcat7w.exe //ES//LabKeyTomcat7
    • 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 be 128
  7. Change the Maximum memory pool: to be 1024 for non-servers, 2048 for servers.
  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. Double-click on the Administrative Tools icon in the Control Panel
  2. Double-click on the Services icon
  3. Find the Service which is being used to start to start LabKey Server. It might be called something like Apache Tomcat or LabKey
  4. Double-click on the service
  5. In the command above, replace the text LabKeyTomcat6 with the text in shown next to ServiceName in the Properties dialog.

Instructions for changing the JVM Heap Size on Unix Computers (Linux, MacOSX and Solaris)

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

  1. Find the JSVC service script.
    • On Linux or Solaris servers, this is usually in the /etc/init.d directory and named either tomcat or tomcat7
    • On MacOSX servers this might be in /usr/local/jsvc/Tomcat7.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 server machine, use:
    -Xms128m -Xmx2048m -XX:-HeapDumpOnOutOfMemoryError
    
    For a workstation or small test server, use:
    -Xms128m -Xmx1024m -XX:-HeapDumpOnOutOfMemoryError
    
  4. Save the file
  5. Restart LabKey Server

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

  1. Change directory to CATALINA_HOME
    • If you have followed our Manual Installation instructions, then this is usually /usr/local/tomcat
  2. The start script is located at bin/catalina.sh
  3. Open the Start script using your favorite editor
  4. Review the file
  5. Above the line with "# OS specific support. $var _must_ be set to either true or false." add the following line.

    For a server machine, use:
    JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx2048m -XX:-HeapDumpOnOutOfMemoryError"
    For a workstation or small test server, use:
    JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx1024m -XX:-HeapDumpOnOutOfMemoryError"
  6. Save the file
  7. Restart LabKey Server

Discussion

previousnext
 
expand all collapse all