This topic explains how to install LabKey on Linux systems, along with its prerequisites: Java, Apache Tomcat, and a database.

This topic assumes installation onto a new, clean Linux machine. If you are installing into an established environment, you can skip steps, or adjust them, as required to use any prerequisites already in place. We also assume that you have super user access to the machine, and that you are familiar with Linux commands and utilities. The example Linux commands below are for Ubuntu 18.04. Adapt these commands as appropriate for your Linux implementation.

Installation Steps:

Determine Supported Versions

  • Consult the topic Supported Technologies to identify supported and compatible versions of the prerequisite components. Make a list of the latest version numbers (for Java, Tomcat, and a database) that are supported by the version of LabKey Server you wish to install.

Create Folder Structure

  • For simplicity, we recommend using the directory structure described here, particularly whenever you are creating a new LabKey installation from scratch.
  • Use the following commands to create the directory structure for the installation:
    sudo mkdir -p /usr/local/labkey/apps
    sudo mkdir -p /usr/local/labkey/backups
    sudo mkdir -p /usr/local/labkey/labkey
    sudo mkdir -p /usr/local/labkey/labkey/externalModules
    sudo mkdir -p /usr/local/labkey/src
    sudo mkdir -p /usr/local/labkey/tomcat-tmp
  • These directories have the following purposes:
    • /labkey/apps - This directory holds the deployed third party components: Tomcat, PostgreSQL, JDK.
    • /labkey/backups - This directory stores database and file backups as needed during upgrade.
    • /labkey/labkey - This directory is holds the deployed LabKey Server installation, known as LABKEY_HOME.
    • /labkey/labkey/externalModules - Holds modules not included in the server distribution packages.
    • /labkey/src - This directory and its subfolders stores the downloaded components before deployment.
    • /labkey/tomcat-tmp - A directory for temp files that Tomcat produces while running. The environment variable that tells Tomcat to use this directory (instead of the default) is CATALINA_TMPDIR, set in the service file outlined below.

Install Java

  • Go to the Eclipse Temurin 17 download page (Opens in a new tab.) and install the appropriate 64-bit JDK binary distribution for your OS.
  • Download into the directory /usr/local/labkey/src
  • For example, use the command shown below, where <LINK> is the download link for the JDK binary distribution.
    /usr/local/labkey/src$ sudo wget <LINK>
  • Unzip the .tar.gz file into the directory /usr/local/labkey/apps/ for example:
    sudo tar -xvzf OpenJDK17U-jdk_x64_linux_hotspot_##.#.#_##.tar.gz -C /usr/local/labkey/apps/
  • Creating a symbolic link from /usr/local/java to /usr/local/labkey/apps/jdk-##.#.#. This will make Java easier to update in the future.
    sudo ln -s /usr/local/labkey/apps/jdk-##.#.# /usr/local/java
  • Define JAVA_HOME and add it to the PATH as follows:
  • Edit the file /etc/profile:
    sudo nano /etc/profile
  • Add the following lines to the end of the file:
    export JAVA_HOME="/usr/local/java"
    export PATH=$PATH:$JAVA_HOME/bin
  • Save: Ctrl+O and press the Enter key.
  • Exit: Ctrl+X
  • Apply changes to your current shell:
    source /etc/profile

Install the Apache Tomcat Web Server

  • Identify a compatible version of Apache Tomcat at (Opens in a new tab.)
  • Download the tar.gz binary distribution to /usr/local/labkey/src, for example:
  • Unzip into the /apps directory, for example:
    sudo tar -xvzf apache-tomcat-#.#.##.tar.gz -C /usr/local/labkey/apps
  • Create a symbolic link from /usr/local/tomcat to /usr/local/labkey/apps/apache-tomcat-#.#.##
    sudo ln -s /usr/local/labkey/apps/apache-tomcat-#.#.## /usr/local/tomcat
  • The directory /usr/local/labkey/apps/apache-tomcat-#.#.## is called <CATALINA_HOME>.
  • Confirm the Java and Tomcat installations by runing the Tomcat startup script:
    sudo /usr/local/labkey/apps/apache-tomcat-#.#.##/bin/
  • Enter the following URL in a web browser:
  • For a local test machine, go to:
  • If your Java and Tomcat installations are successful you will see the Tomcat success page.
  • Stop Tomcat before proceeding:
    sudo /usr/local/labkey/apps/apache-tomcat-#.#.##/bin/

Install the Database Server (PostgreSQL)

  • Below we describe how to install PostgreSQL as the database server.
  • Use your native Linux install utility to install PostgreSQL (like apt or yum) or go to and download the PostgreSQL binary packages or source code. Follow the instructions in the downloaded package to install PostgreSQL.
  • Create the database and associated user/owner. Using superuser permissions, do the following:
    • Create an empty database named 'labkey'.
    • Create a PostgreSQL user named 'labkey'.
    • Grant the owner role to the labkey user over the database.
    • Revoke public permissions from the database.
  • See the following example PostgreSQL commands:
  • Connect to the DB server as the Postgres Super User using the psql command:
    sudo -u postgres psql
  • Issue the following commands to create the user, database and revoke public permissions from the database. Use the example below, after substituting your chosen PASSWORD. Retain the single quotes around the password value.
    create user labkey password 'PASSWORD';
    create database labkey with owner labkey;
    revoke all on database labkey from public;
  • The username, password, and db name you choose above will be used to configure Tomcat below.

Download LabKey Server System Components

  • Click Here to Register and Download LabKey Binaries. (Opens in a new tab.)
  • Get the download link to the current binary tar.gz distribution by right-clicking the button Download tar.gz and selecting Copy link address.
  • Download into the /usr/local/labkey/src directory:
    /usr/local/labkey/src$ sudo wget <LINK>
  • Unzip into the same directory:
    sudo tar xfz LabKey#.#.#-#####.#-community-bin.tar.gz
  • After unpacking, the directory contains these files and directories:
    • labkeywebapp - The LabKey Server web application.
    • modules - LabKey Server modules.
    • pipeline-lib- Jars for the data processing pipeline.
    • tomcat-lib - Required server library jars.
    • labkey.xml - LabKey Server configuration file.
    • - Manual upgrade script.
    • README.txt - A file pointing you to this documentation.
    • VERSION - A file containing the release number and build number.
  • For convenience, export the following:
    export LABKEY_DIST=/usr/local/labkey/src/LabKey##.#.#-#####.#-community-bin
    export LABKEY_HOME=/usr/local/labkey/labkey
    export CATALINA_HOME=/usr/local/labkey/apps/apache-tomcat-#.#.##
  • Confirm the paths are correct:
    echo $LABKEY_DIST
    echo $LABKEY_HOME

Deploy Tomcat Libraries

  • Ensure that Tomcat is stopped by running the shutdown script:
    sudo sh $CATALINA_HOME/bin/
  • Copy all the JAR files from the /tomcat-lib directory to the <CATALINA_HOME>/lib directory, namely these three files:
    • javax.activation.jar
    • labkeyBootstrap.jar
    • mail.jar
  • For example:
    sudo cp $LABKEY_DIST/tomcat-lib/javax.activation.jar $CATALINA_HOME/lib
    sudo cp $LABKEY_DIST/tomcat-lib/labkeyBootstrap.jar $CATALINA_HOME/lib
    sudo cp $LABKEY_DIST/tomcat-lib/mail.jar $CATALINA_HOME/lib

Deploy the Main LabKey Binaries

  • Copy the following directories to /usr/local/labkey/labkey (LABKEY_HOME).
    • labkeywebapp
    • modules
    • pipeline-lib
  • For example:
    sudo cp -R $LABKEY_DIST/labkeywebapp $LABKEY_HOME
    sudo cp -R $LABKEY_DIST/modules $LABKEY_HOME
    sudo cp -R $LABKEY_DIST/pipeline-lib $LABKEY_HOME

Deploy the LabKey Server Configuration File

Find the file labkey.xml in the LabKey Server distribution files. This is the main LabKey Server configuration file and contains a number of settings required by LabKey Server to run.

  • Open labkey.xml in a text editor.
    sudo nano $LABKEY_DIST/labkey.xml
  • The parameter values you need to change are bracketed by @@...@@:
    • @@appDocBase@@ - Replace with <LABKEY_HOME>/labkeywebapp. Use the full path: /usr/local/labkey/labkey/labkeywebapp
    • @@jdbcUser@@ - Replace with the database user created above: 'labkey'.
    • @@jdbcPassword@@ - Replace with the password create above.
  • Create the intermediate "Catalina" and "localhost" subdirectories to make the following path:
    sudo mkdir -p $CATALINA_HOME/conf/Catalina/localhost
  • Copy labkey.xml into the new directory path:
    sudo cp $LABKEY_DIST/labkey.xml $CATALINA_HOME/conf/Catalina/localhost

Configure the Tomcat User and Service

To ensure that the server is not running as root, we configure Tomcat and LabKey to run under a new user named 'tomcat'.

We also configure Tomcat to start automatically using a .service unit file, so that the operating system manages the server's availability.

The instructions and .service file below are written for Ubuntu 18.04, but can be adapted to other environments.

  • Create the tomcat user (and associated group):
    sudo useradd -r -m -U -s /bin/false tomcat
  • Give this user ownership over CATALINA_HOME, LABKEY_HOME, and the logging directory. For example:
    sudo chown -R tomcat: $CATALINA_HOME
    sudo chown -R tomcat: $LABKEY_HOME
    sudo chown -R tomcat: /usr/local/labkey/tomcat-tmp
  • Create the tomcat.service file:
    sudo nano /etc/systemd/system/tomcat.service
  • Paste in the file contents. Start with the template below. Substitute any paths, version numbers, and other parameters to fit your environment.
    # Systemd unit file for tomcat_lk

    Description=lk Apache Tomcat Application

    Environment="CATALINA_OPTS=-Djava.library.path=/usr/local/labkey/apps/jdk-13.0.2 -Djava.awt.headless=true -Duser.timezone=America/Los_Angeles -Xms512M -Xmx4096M -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/usr/local/labkey/tomcat-tmp"

    ExecStart=/usr/local/labkey/apps/apache-tomcat-9.0.30/bin/ start
    ExecStop=/usr/local/labkey/apps/apache-tomcat-9.0.30/bin/ stop
    SuccessExitStatus=0 143


    • Note: While it is possible to use CATALINA_OPTS to specify a garbage collector, LabKey does not recommend doing so. LabKey develops, tests, and deploys using the default Java garbage collector. Explicitly specifying an alternative garbage collector is not recommended.
  • Save and close the file.
  • Notify the system of the new unit file:
    sudo systemctl daemon-reload
  • Enable automatic startup on system reboot:
    sudo systemctl enable tomcat

Start the Server

  • Start the server:
    sudo systemctl start tomcat
  • After you start the server, point your web browser at the LabKey webapp:
  • For a local test machine, go to:
  • You will be directed to create the first user account and set properties on your new server.
  • If the server does not start as expected, consult the logs and the troubleshooting docs.

Installation Checklist

  1. (Current Topic) Install on Linux: Main Components
  2. Installation: Tomcat Configuration
  3. Installation: LabKey Configuration File
  4. Installation: Third-Party Components

  Attached Files


Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all