Install on Linux

2024-03-28

This topic explains how to install LabKey on Linux systems, along with its prerequisites: Java and a database. Tomcat is now embedded in the distribution.

This topic describes installation onto a new, clean Linux machine that has not previously run a LabKey Server. If you are installing into an established environment, you may need to adjust or skip some of these steps. We assume that you have root access to the machine, and that you are familiar with Linux commands and utilities. Adapt the example commands we show to be appropriate for your Linux implementation.

Installation Steps:

Determine Supported Versions

Before beginning, identify the versions of Java and your database that will be compatible with the version of LabKey you are installing. Learn more in this topic:

Create Folder Structure

We recommend using the directory structure described here, which will make our documentation and any support needed much easier to follow. Create this folder hierarchy:

DirectoryDescription
/labkeyThis is the top level, referred to in the documentation as <LABKEY_ROOT>
/labkey/labkeyThis is where LabKey Server gets installed, known as <LABKEY_HOME> in the documentation.
/labkey/srcThis is where the downloaded distribution files go before installing.
/labkey/appsThis holds the prerequisite apps and other utilities.
/labkey/backupArchiveUse this to hold backups as needed. Do NOT use /labkey/labkey/backup as that location will be overwritten.
/labkey/labkey/labkey-tmpA directory for temp files that LabKey's embedded Tomcat produces while running.

Install Java

Download the latest supported version of Java for your platform to the <LABKEY_ROOT>/src directory, i.e. /labkey/src. Be sure to choose the appropriate 64-bit JDK binary distribution for your OS.

  • For example, use the command shown below where <LINK> is the download link for the JDK binary distribution:
    sudo wget <LINK> -P /labkey/src
  • Unzip the .tar.gz file into the directory <LABKEY_ROOT>/apps/ for example:
    sudo tar -xvfz OpenJDK17U-jdk_x64_linux_hotspot_##.#.#_##.tar.gz -C /labkey/apps/
  • Create a symbolic link from /usr/local/java (the default Linux location) to <LABKEY_ROOT>/apps/jdk-##.#.#. This will make Java easier to update in the future.
    sudo ln -s /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 and exit.
  • Apply changes to your current shell:
    source /etc/profile

Install the Database (PostgreSQL)

  • Below we describe how to install PostgreSQL as the database.
  • Use your native Linux install utility to install PostgreSQL (like apt or yum) or go to http://www.postgresql.org/download/ 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;
    \q
  • The username, password, and db name you choose above will be provided to the server in the application.properties file.

Download the LabKey Distribution

Download the distribution:

  • Premium Edition users can download their custom distribution from the Server Builds section of their client support portal.
  • Community Edition users can register and download the distribution here: Download LabKey Server Community Edition.
Get the download link to the current binary tar.gz distribution from the URL for the Download tar.gz button or link.
  • Download into the <LABKEY_ROOT>/src directory:
    sudo wget <LINK> -P /labkey/src
  • Unzip into the same directory:
    sudo tar -xvfz LabKey#.#.#-#####.#-community-bin.tar.gz -C /labkey/src
After unpacking, the directory will contain:
  • The "labkeyServer.jar" file.
  • A VERSION text file that contains the version number of LabKey
  • A bin directory that contains various DLL and EXE files (Not needed for installation on Linux)
  • A config directory, containing an application.properties template.
  • An example Windows service install script (Not needed for installation on Linux)
  • An example systemd unit file for Linux named "labkey_server.service"

Deploy the LabKey Components

Copy the following from the unpacked distribution into <LABKEY_HOME>.

  • The labkeyServer.jar
  • The config directory

Customize the application.properties File

In the <LABKEY_HOME>/config folder you just copied, you need to edit your application.properties file to provide settings and configurations including, but not limited to:

  • Your database configuration and credentials
  • The port and TLS/SSL settings (HTTP and HTTPS access information)
  • Other details and customizations you may need
Learn about customizing this file in:

Configure the LabKey User and Service

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

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

The instructions and .service file we provide are written for Ubuntu 22.04; you may need to adjust to suit your environment.

  • Create the labkey user (and associated group):
    sudo useradd -r -m -U -s /bin/false labkey
  • Give this user ownership over <LABKEY_HOME> and the <LABKEY_HOME>/labkey-tmp directory. For example:
    sudo chown -R labkey:labkey /labkey/labkey
    sudo chown -R labkey:labkey /labkey/labkey/tomcat-tmp
  • Create the labkey_server.service file:
    sudo nano /etc/systemd/system/labkey_server.service
  • Paste in the template contents of the "labkey_server.service" file provided in the LabKey distribution, then edit to customize it:
    • Substitute any paths, version numbers, and other parameters to fit your environment.
    • The 'labkey' user name we suggest using is included as the value of both User and Group in the template.
  • Save and close the file.
  • Notify the system of the new service and refresh system dependencies:
    sudo systemctl daemon-reload

Start the Server

  • Start the server:
    sudo systemctl start labkey_server
  • After you start the server, you'll see logs begin to accumulate in <LABKEY_HOME>/logs.
  • Point your web browser at the base URL of the LabKey webapp.
  • 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
  2. Application Properties
  3. Installation: Third-Party Components