Follow the instructions in this topic to manually upgrade an existing 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. These instructions are written for Linux Ubuntu and require general familiarity with Linux administration. If you are upgrading on another version (or on OSX), you will need to make some changes to the instructions given here.

In any upgrade, it is highly recommended that you first upgrade a staging server and confirm that the upgrade process goes smoothly and the upgraded server passes your own acceptance testing before repeating the process to upgrade your production server.

In this release, this topic is specifically for upgrading to use embedded Tomcat for the first time. Versions 23.11 and earlier used a standalone installation (of Tomcat 9) and a different configuration method. You'll be able to draw configuration information from that previous installation to upgrade to version 24.3 with embedded Tomcat 10 using the instructions here. In future, the upgrade process will be even simpler for you.

If you need to do any intermediate upgrades to bring your current server to a version that supports upgrade to 24.3, please review the documentation archives for the previous upgrade process to bring your server to version 23.11 prior to following these steps.

Pre-Upgrade Steps

Notify Users

Before upgrade, notify your users in advance that the server will be down for a period of time. Consider using a ribbon bar message as part of this notification.

Upgrade All Dependencies

Before upgrading LabKey Server, it is important to upgrade Java, and your database to supported versions. For details see: Supported Technologies

Note that Postgres 11 is no longer supported in LabKey version 24.3.

Existing LabKey Server Installation

First, locate all the component parts of your existing LabKey Server installation. We provide recommended directory locations, but also use variables like <LABKEY_HOME> and <CATALINA_HOME> to make it easier to follow the documentation no matter where your installation is located.

This topic assumes the following structure, with each of these directories and their contents being owned by the same user that was starting the Tomcat service previously.

VariableLinux default locationDescription
LK_ROOT/labkeyThe top level under which all LabKey-related files are nested.
 <LK_ROOT>/srcThis is where your current and past LabKey tar.gz installation binaries are saved.
 <LK_ROOT>/appsThis is a good location for installation of related apps like Java and your database.
 <LK_ROOT>/backupArchiveThis is a good location for storing your own backups, including the backup prior to performing this upgrade.
i.e. /labkey/labkey
This is where the actual LabKey application is located.
 <LABKEY_HOME>/logsThis location will be created during the first startup of the new server and will hold the logs.
 <LABKEY_HOME>/labkeywebappThe directory containing the LabKey Server web application. This location will be created during server startup and thus overwritten at every upgrade. If you have any customizations under this location, you need to move them before this upgrade.
 <LABKEY_HOME>/modulesThe directory containing the LabKey Server modules. This should only contain modules provided to you in the LabKey distribution. Any of your own modules should be in the parallel "externalModules" directory.
 <LABKEY_HOME>/labkey-tmpThe Tomcat temp directory that LabKey will be using after the upgrade. If your tomcat installation was previously using a different location, you will switch to this location.
 <LABKEY_HOME>/externalModulesThe directory for any additional, user-developed modules you use. You may not need this location.
 <LABKEY_HOME>/pipeline-libThis is a legacy directory that is no longer in use. If you have this directory, you can delete it.
 <LABKEY_HOME>/backupThe automated upgrade process will store the immediate prior backup in this location. This location will be overwritten each time the server starts. If you already have this directory and anything saved in it, move it to <LK_ROOT>\backupArchive before continuing.

It is important to note that the contents of the following locations will be replaced completely by deploying the LabKey distribution. Any content you want to retain must be moved elsewhere before the upgrade. You may not have all of these locations currently.
  • <LABKEY_HOME>/modules
  • <LABKEY_HOME>/labkeywebapp
  • <LABKEY_HOME>/backup
  • <LABKEY_HOME>/labkey-tmp

Custom or External Modules (If needed)

If you have any modules not provided to you in a LabKey distribution, such as custom modules written by you or someone else in your organization, they should NOT be in the <LABKEY_HOME>/modules directory with the LabKey-distribution modules, but instead in <LABKEY_HOME>/externalModules. The <LABKEY_HOME>/modules directory will be overwritten with each upgrade.

Modules that are in the expected <LABKEY_HOME>/externalModules directory will be automatically seen and loaded when LabKey Server starts. Upgrades will not touch this location.

If you had been using a command line argument to Tomcat to specify a different location for externalModules, you should now move them to the <LABKEY_HOME>/externalModules location with this upgrade.

Move Custom log4j2.xml and Custom Stylesheet (Uncommon)

If you have customized the log4j2.xml file at <LABKEY_HOME>/labkeywebapp/WEB-INF/classes/log4j2.xml, move the custom version to a new location, otherwise it will be overwritten at every upgrade. You will provide the path to the new location in the file.

If you had previously customized the server's stylesheet, by placing one in the <LABKEY_HOME>/labkeywebapp directory, save it elsewhere before you upgrade. After the upgrade, you should upload your custom stylesheet via the Look and Feel Settings page.

Previous Tomcat Installation

After this upgrade, you will no longer need to install or manage Tomcat yourself. Locate the existing installation so that you can carry forward the necessary configuration:

CATALINA_HOMEVaries. Could be
/labkey/tomcat OR
/labkey/apps/tomcat OR
This is where your previous Tomcat version is currently installed. It may be one of the locations to the left or may be somewhere else. All of the following resources will be under this <CATALINA_HOME> location.
 <CATALINA_HOME>/SSLThis is where your existing Java KeyStore is located. You will be moving it to <LABKEY_HOME>/SSL to use after this upgrade.
 <CATALINA_HOME>/confContains configuration information including the server.xml and/or web.xml files.
CONFIG_FILE<CATALINA_HOME>/conf/Catalina/localhostThe main LabKey configuration file. This will be named either ROOT.xml or labkey.xml, or something similar.
 <CATALINA_HOME>/libThe existing LabKey Server libraries and JAR files.
 /etc/defaultConfiguration files

Confirm which user was being used to start your Tomcat service (referred to below as the <TOMCAT_USER>). This should not be the root user for security reasons. It might be 'tomcat', 'labkey', or something else, depending on how you originally installed your system.

You will also need to locate your service file and know the configuration of your service and what values are being passed, such as memory, heap dump locations, Java paths, etc. This information may be in one of a few different places. Copy all three of these items and store them in your backupArchive location.

  • The existing Tomcat service file under /etc/systemd/system
  • The Tomcat default file under /etc/default
  • The script under <CATALINA_HOME>/bin
The distribution includes an example service file to start with. Later in this topic, we will guide you in customizing it as needed.

Search Index Note: You may want to find your current installation's full text search index. This previous location might have been <CATALINA_HOME>/temp/labkey_full_text_index or <LK_ROOT>/temp/labkey_full_text_index or similar; use the previous server's UI to locate it if you are not sure. During this upgrade, the new full text search index will be created in <LABKEY_HOME>/files/@labkey_full_text_index. In the cleanup steps after upgrade, you may want to delete the prior index to save disk space.

You do not need to back up the search index.

Back Up Components and Configuration

In the unlikely event that you need to go back to the previous installation of LabKey with Tomcat 9, it will be important to be able to start from the same baseline with more configuration detail than for a usual upgrade. Choose a backup location like <LK_ROOT>/backupArchive/backup2311 in which to store the various files and zip bundles.

  1. Ensure you have a copy of the binaries you originally used to install the existing LabKey Server.
  2. Stop Tomcat.
  3. Back up your existing database, files and configuration and log files.
  4. Back up your existing Tomcat configuration, including files in the /etc/default directory and the systemd service that starts Tomcat.

Obtain the New LabKey Server Distribution

1. Download the distribution tar.gz file:

  • 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 package here: Download LabKey Server Community Edition.
2. Place it in the <LK_ROOT>/src location:

Navigate to that location and unpack the distribution.

sudo tar -xvfz NAME_OF_DISTRIBUTION.tar.gz

It 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 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 Distribution Files

Copy the following from the unpacked distribution into <LABKEY_HOME> (i.e. /labkey/labkey):

  • The labkeyServer.jar
  • The config directory
Copy the directory that contains your Java Keystore (often but not necessarily under <CATALINA_HOME>) and place it under <LABKEY_HOME>:

Reassert Ownership of Installation

If necessary, reassert the <TOMCAT_USER>'s ownership recursively over the entire <LABKEY_HOME> directory. For example, if your <TOMCAT_USER> is 'labkey' and your <LABKEY_HOME> is /labkey/labkey, use:

sudo chown -R labkey:labkey /labkey/labkey

Customize the File

The Tomcat 10 Embedded application requires the <LABKEY_HOME>/config/ to be filled in with values that are unique to your specific LabKey instance and were previously provided in other files or possibly command line options.

A detailed guide to migrating your configuration settings from both your <CONFIG_FILE> and from Tomcat configuration files under <CATALINA_HOME>/conf is provided in this topic:

Set Up the Service

1. Create the <LABKEY_HOME>/labkey-tmp directory if it does not exist. This location is referenced in the service file. Using our recommended structure, this location is /labkey/labkey/labkey-tmp.

2. Assuming your prior instance was started with a service, confirm the configuration of that service and what values are being passed, such as memory, heap dump locations, Java paths, etc. Locating where these service details were defined was covered in the earlier section about your prior Tomcat configuration.

3. Confirm that you have stored a backup copy of each of these, if they exist:

  • The existing Tomcat service file under /etc/systemd/system. The name of this file varies; it could be tomcat_lk.service (used in the following examples), labkey.service, tomcat.service, apache-tomcat.service or something else.
  • The Tomcat default file under /etc/default
  • The script under <CATALINA_HOME>/bin
4. Stop the existing Tomcat service and delete the previous service file:

Stop your existing service, and confirm that Tomcat is no longer running by using the following command:

sudo systemctl status tomcat_lk.service

In the /etc/systemd/system directory:

  • Delete the existing Tomcat service file from this location.
  • Run the following command to reload/refresh the system dependencies, removing any trace of the old Tomcat service:
    sudo systemctl daemon-reload
5. In the /etc/default directory:
  • Delete the existing Tomcat default file if present.
6. Copy the "labkey_server.service" file included in the distribution into the /etc/systemd/system directory.

Edit this new "labkey_server.service" file so that it corresponds to your particular instance and all the information gathered in step 2, including but not limited to memory, Java paths, etc. Note: you do not copy full parameter lines like "CATALINA_OPTS" into the new service file. Selectively replace settings in the template we send with the values from your previous configuration.

  1. Update the setting of JAVA_HOME to be the full path used in your previous installation, and if your previous service used a different setting for java.library.path, update that argument in the JAVA_PRE_JAR_OPS as well.
  2. Edit the ExecStart line to replace "$JAVA_HOME" with the full path to java you set as JAVA_HOME in the section above. The service will not make this substitution (though it will make the other "OPS" substitutions).
  3. You will likely need to increase the webapp memory from the service file's default (-Xms and -Xmx values).
  4. If you are not using /labkey/labkey as the <LABKEY_HOME>, there are several places to update this path in the file.
  5. Do not change the setting of the (Tomcat temp directory in the LABKEY_JAR_OPS) to match what you used previously. Going forward, <LABKEY_HOME>/labkey-tmp will be used.
You can find details about commonly needed edits to the service file in this topic (it will open in a new tab): When finished, run this command to reload/refresh the system dependencies again:
sudo systemctl daemon-reload

Start Server, Test, then Delete Tomcat

Start your service and then access the <LABKEY_HOME>/logs directory.

  • If the service started correctly, new logs should have been generated and you should be able to tail the labkey.log file to see startup progress.
  • Once the server is up and running, access it via your browser.
  • It is good practice to review Server Information and System Properties on the Admin Console immediately after the upgrade to ensure they are correct.
It is best practice to have first completed this upgrade using a staging server, and then perform your own testing to validate the upgrade. Once testing on staging is complete, proceed to repeat the upgrade process of your production database.

Troubleshoot Service Start Issues

If your service did not start as expected, gather additional information about the specific misconfiguration by using these one or both of the following commands:

systemctl status labkey_server.service

journalctl -xe

Post-Upgrade Cleanup (Optional)

Once you are confident that the upgrade was successful and you don't have a need to roll back your changes, you can proceed to delete the prior installation of Tomcat 9, i.e. delete the <CATALINA_HOME> directory.

You may also want to delete the prior installation's full text search index, in order to save disk space, though this is not required. We suggested locating it earlier in this topic.

Future Upgrades

Once you have completed this migration to LabKey Server version 24.3 with embedded Tomcat 10, future upgrades to new releases will be much simpler. You will only need to:

  1. Stop your LabKey service.
  2. Backup your database.
  3. Unpack your newer tar.gz binaries under <LK_ROOT>/src
  4. Replace the labkeyServer.jar under <LABKEY_HOME> (i.e. <LK_ROOT>/labkey) with the newer one you unpacked.
  5. Start your LabKey service.

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all