Manual Upgrade Checklist for Linux and OSX

Follow this checklist to manually upgrade LabKey Server to a new version. The process assumes that you have previously installed LabKey using the recommended directory structure described in Install on Linux: Main Components.

Upgrade Changes for 20.7

The JDBC jars (jtds.jar, postgresql.jar, mysql.jar) are now versioned and distributed inside the module directories like any other third-party jar, making it unnecessary to copy them to the CATALINA_HOME/lib directory during installation and upgrade. When you upgrade to 20.7, delete these JDBC jar files from CATALINA_HOME/lib to avoid conflicts.

These JDBC jars are not the same as the LabKey JDBC Driver which allows client applications to query against the data stored in LabKey. Learn more about the JDBC Driver jar in this topic: LabKey JDBC Driver

Note that each LabKey distribution includes an upgrade script that automates much of the process. Consider using this script before you proceed with the fully manual process described below.

Notify Users

  • Before upgrade, notify your users in advance that the server will be down for a period of time.

Upgrade All Dependencies

  • Before upgrading LabKey Server, it is important to upgrade Java, Tomcat, and your database (PostgreSQL or SQL Server) to their recommended versions. For details see: Supported Technologies
  • If you did not install using the recommended directory structure, this is a reasonable time to make the switch. Using the root directory "/usr/local/labkey" allows you to keep all necessary components in one place.

Download the New LabKey Server Distribution

  • Navigate to the directory /usr/local/labkey/src, the base directory for downloading and unpacking distributions:
cd /usr/local/labkey/src
  • Premium Edition users can download their custom distribution from the Server Builds section of their client portal.
  • Community Edition users can register and download the distribution package at Download LabKey Server Community Edition.
  • To download the Linux/OSX package, get the URL from the button Download tar.gz and use wget, for example:
  • The name of the distribution archive includes the version number, build number, and edition. For example, "LabKey20.3.2-65320.7-community-bin.tar.gz" indicates:
    • version: 20.3.2
    • build number: 65320.7
    • edition: community
  • Unpack the distribution archive. In the example below, substitute the pound symbols #### appropriately:
sudo tar xfz LabKey####-bin.tar.gz
  • The unpacked bundle will now be located in a directory like:

Locate Your Existing LabKey Server Installation

  • Locate your LABKEY_HOME directory. The default location is /usr/local/labkey/labkey.
  • Find your Tomcat home directory, referred to as CATALINA_HOME. The default location is usr/local/labkey/apps/apache/apache-tomcat-#.#.##.
  • Confirm the locations of the existing LabKey Server files on your system for each of the following components, in preparation for replacing them with the corresponding LabKey Server files:
    • LABKEY_HOME/labkeywebapp: The directory containing the LabKey Server web application.
    • LABKEY_HOME/modules: The directory containing the LabKey Server modules.
    • LABKEY_HOME/externalModules: The directory containing additional, user-developed LabKey Server modules, if applicable. (Not all installations contain an externalModules directory. If you don't see one, skip this step.)
    • CATALINA_HOME/lib: The existing LabKey Server libraries and JAR files.
    • CATALINA_HOME/conf/Catalina/localhost/labkey.xml: The LabKey Server configuration file. This file may be named labkey.xml, LABKEY.xml, or ROOT.xml.

Stop Tomcat and Backup

  • Shut down the Tomcat web server. Note that you do not need to shut down the database that LabKey Server connects to. To shutdown Tomcat, use a command like the following, or the script provided by Apache.
sudo systemctl stop tomcat
  • Backup the database by following the topic: Backup and Maintenance
  • Create a backup directory for your current server. For example, to backup LabKey version 20.3:
mkdir /usr/local/labkey/backups/labkey203
  • For convenience, export the following, replacing pound symbols ####, and any path differences, to fit your environment:
export LABKEY_HOME=/usr/local/labkey/labkey
export BACKUP_LOCATION=/usr/local/labkey/backups/####
export CATALINA_HOME=/usr/local/labkey/apps/apache-tomcat-####
export LABKEY_DIST=/usr/local/labkey/src/LabKey####-bin
  • Backup your resources by following these steps. It is critical that you completely replace the /labkeywebapp, /modules, and /externalModules directories below, to avoid including conflicting artifacts in the upgraded server.
  • Move the following directories to the backup directory:
sudo mv $LABKEY_HOME/labkeywebapp $BACKUP_LOCATION
sudo mv $LABKEY_HOME/pipeline-lib $BACKUP_LOCATION #If it exists.
sudo mv $LABKEY_HOME/externalModules $BACKUP_LOCATION #If it exists.
  • Confirm that the LABKEY_HOME folder no longer contains these four subdirectories.
  • Copy the following directories to the same backup subfolder. You may need to return to their current status but it is not necessary to fully replace these directories in the upgrade process.

Deploy Distribution Files

  • Copy the contents of the distribution directory as follows.
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 ##Only necessary if installing a remote pipeline server.##
  • If your installation includes other modules not included the distribution bundle, recompile these modules against the server version you're installing (or otherwise obtain updated versions of the modules) and add them to $LABKEY_HOME/externalModules
  • Copy the contents of LABKEY_DIST/tomcat-lib into CATALINA_HOME/lib. Choose to overwrite any jars with the same names that are already present. Do not delete or move the other files in the CATALINA_HOME/lib folder, as they are required for Tomcat to run. 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
  • If you have customized the server's stylesheet, restore your modified stylesheet from the backup directory into the new LABKEY_HOME/labkeywebapp directory.

Install Third Party Components

  • See Installation: Third-Party Components for the list of required components, required versions and installation instructions.
  • Ensure that the LABKEY_HOME/bin directory is on your system path, or on the path of the user account that will be starting Tomcat.
Note: This will upgrade the versions of X!Tandem and TPP tools which are currently being used with LabKey Server.

Check for Changes to labkey.xml

  • Compare the outgoing and incoming labkey.xml (or root.xml) files.
  • If necessary, merge any other settings you have changed in the outgoing file into the incoming one.
  • If there are changes, update CATALINA_HOME/conf/Catalina/localhost/labkey.xml.
Note: The name of the LabKey Server configuration file determines the URL address of your LabKey Server application. If you change the name (or case) of this configuration file, any external links to your LabKey Server application will break. For more information, see Installation: LabKey Configuration File.

For example, if your existing LabKey Server installation has been running as the root web application on Tomcat and you want to ensure that your application URLs remain identical after the upgrade, rename the copied labkey.xml to ROOT.xml in the same localhost subfolder location.

Check for Changes to log4j.xml

  • If you have not customized the log4j.xml file at LABKEY_HOME/labkeywebapp/WEB-INF/classes/log4j.xml, then you can skip this step.
  • If you have customized the log4j.xml file, then compare your modified file with the incoming log4j.xml file. If necessary, merge your customizations with the incoming version.

Reassert Tomcat User Ownership

If necessary, reassert the Tomcat user's ownership over LABKEY_HOME and CATALINA_HOME. For example:

sudo chown -R tomcat: $CATALINA_HOME
sudo chown -R tomcat: $LABKEY_HOME

Start Tomcat and Test

  • Start Tomcat:
sudo systemctl start tomcat
  • If you have any problems starting Tomcat, check the Tomcat logs in the CATALINA_HOME/logs directory.
  • At this point LabKey Server should be up and running.
  • It is good practice to review Server Information and System Properties on the Admin Console immediately after the upgrade to ensure they are correct.
  • If you have problems, check the Tomcat logs, and double-check that you have properly named the LabKey Server configuration file and that its values are correct.

Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all