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 familiarity with Linux administration. If you are upgrading on another version (or on OSX), you will need to adjust 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.

This topic is specifically for upgrading for the first time to a version using embedded Tomcat 10. Versions 23.11 and earlier used a standalone installation (of Tomcat 9) and a different configuration method. You need to draw configuration information from that previous installation to upgrade to a version with embedded Tomcat 10 using the instructions here. Once you have completed this one-time migration, the upgrade process will be much simpler for you.

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

If you have already migrated to use embedded Tomcat with 24.3 and are upgrading to a later release, follow the simpler steps for Future Upgrades below.

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

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.
LABKEY_HOME<LK_ROOT>/labkey
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.
 <LABKEY_HOME>/files OR
other file root location(s)
By default, the server's file root is <LABKEY_HOME>/files, though you may be using other file root(s) as well. You can leave files in place during the upgrade, and the server will continue to use the same path(s). Check the site file root from the admin console.

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 application.properties 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:

VariableLocationDescription
CATALINA_HOMEVaries. Could be
/labkey/tomcat OR
/labkey/apps/tomcat OR
/labkey/apps/apache/apache-tomcat#.#.##/
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 setenv.sh 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, 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:
/labkey/src/NAME_OF_DISTRIBUTION.tar.gz

Navigate to that location and unpack the distribution.

sudo tar -xvzf 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 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 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>:
<LABKEY_HOME>/SSL

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 application.properties File

The Tomcat 10 Embedded application requires the <LABKEY_HOME>/config/application.properties 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. If you used another <LABKEY_HOME>, create /labkey-tmp there.

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 setenv.sh 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.
  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.
  3. If you are not using /labkey/labkey as the <LABKEY_HOME>, update the setting of the LABKEY_HOME variable and any other occurrances of the /labkey/labkey path in the service file.
  4. If the user running tomcat was not 'labkey', update the User and Group settings to match the prior configuration.
  5. You will likely need to increase the webapp memory from the service file's default (-Xms and -Xmx values).
  6. Learn more about customizing 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. Obtain the distribution and unpack the new tar.gz binaries under <LK_ROOT>/src, as described above.
  4. Replace the labkeyServer.jar under <LABKEY_HOME> (i.e. <LK_ROOT>/labkey) with the one you unpacked. Do NOT copy the 'config' subdirectory; you do not want to overwrite your customized application.properties file.
  5. Start your LabKey service.
The new jar will be deployed and the database upgraded. Tail the <LABKEY_HOME>/logs/labkey.log to see progress.

Related Topics

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand allcollapse all