This topic explains how to install LabKey on Linux systems, along with its prerequisites: Java and a database. Tomcat is embedded in the LabKey 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:
An
install-script is available for automating this process. Learn more in the GitHub repository:
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:
Directory | Description |
---|
/labkey | This is the top level, referred to in the documentation as <LK_ROOT> |
/labkey/labkey | This is <LK_ROOT>/labkey, where LabKey Server gets installed, known as <LABKEY_HOME> in the documentation. |
/labkey/src | This is where the downloaded distribution files go before installing. |
/labkey/apps | This holds the prerequisite apps and other utilities. |
/labkey/backupArchive | Use this to hold backups as needed. Do NOT use /labkey/labkey/backup as that location will be overwritten. |
/labkey/labkey/labkey-tmp | A 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 <LK_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 <LK_ROOT>/apps/ for example:
sudo tar -xvzf OpenJDK17U-jdk_x64_linux_hotspot_##.#.#_##.tar.gz -C /labkey/apps/
- Create a symbolic link from /usr/local/java (the default Linux location) to <LK_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:
- 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:
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:
- 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 <LK_ROOT>/src directory:
sudo wget <LINK> -P /labkey/src
- Unzip into the same directory:
sudo tar -xvzf 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> recursively. For example:
sudo chown -R labkey:labkey /labkey/labkey
- 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. Review details of common edits required in this topic (it will open in a new tab):
- 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.
Related Topics