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, OpenJDK.
- /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 log directory for Tomcat.
Install Java
- Go to OpenJDK (Opens in a new tab.) and get the download link to the JDK binary distribution, a .tar.gz file.
- 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 openjdk-##.#.#_linux-x64_bin.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:
- 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:
Install the Apache Tomcat Web Server
- Identify a compatible version of Apache Tomcat at http://tomcat.apache.org/ (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/startup.sh
- 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/shutdown.sh
Install the Database Server (PostgreSQL)
- Below we describe how to install PostgreSQL as the database server. If you wish to use MS SQL Server, complete the topic: Install Microsoft SQL Server
- 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 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.sh - 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
echo $CATALINA_HOME
Deploy Tomcat Libraries
- Ensure that Tomcat is stopped by running the shutdown script:
sudo sh $CATALINA_HOME/bin/shutdown.sh
- Copy all the JAR files from the /tomcat-lib directory to the <CATALINA_HOME>/lib directory, namely these six 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
[Unit]
Description=lk Apache Tomcat Application
After=syslog.target network.target
[Service]
Type=forking
Environment="JAVA_HOME=/usr/local/labkey/apps/jdk-13.0.2"
Environment="CATALINA_BASE=/usr/local/labkey/apps/apache-tomcat-9.0.30"
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 -Djava.net.preferIPv4Stack=true"
Environment="CATALINA_TMPDIR=/usr/local/labkey/tomcat-tmp"
ExecStart=/usr/local/labkey/apps/apache-tomcat-9.0.30/bin/catalina.sh start
ExecStop=/usr/local/labkey/apps/apache-tomcat-9.0.30/bin/catalina.sh stop
SuccessExitStatus=0 143
Restart=on-failure
RestartSec=2
User=tomcat
Group=tomcat
[Install]
WantedBy=multi-user.target
- 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
- (Current Topic) Install on Linux: Main Components
- Installation: Tomcat Configuration
- Installation: SMTP, Encryption, LDAP, and File Roots
- Installation: Third-Party Components
