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.

• Pre-Upgrade Steps
• Notify Users
• Upgrade All Dependencies
• Existing LabKey Server Installation
• Custom or External Modules (If needed)
• Move Custom log4j2.xml and Custom Stylesheet (Uncommon)
• Previous Tomcat Installation Details
• Back Up Components and Configuration
• Obtain the New LabKey Server Distribution
• Deploy Distribution Files
• Reassert Ownership of Installation
• Customize the application.properties File
• Set Up the Service
• Start Service and Test
• Post-Upgrade Cleanup (Optional)
• Future Upgrades

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.

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:

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

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.

/labkey/src/NAME_OF_DISTRIBUTION.tar.gz

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 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

<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:

• Migrate Configuration to Application Properties

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 setenv.sh script under <CATALINA_HOME>/bin

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

• Delete the existing Tomcat default file if present.

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.
• 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.
• 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).
• You will likely need to increase the webapp memory from the service file's default (-Xms and -Xmx values).
• If you are not using /labkey/labkey as the <LABKEY_HOME>, there are several places to update this path in the file.
• Do not change the setting of the java.io.tmpdir (Tomcat temp directory in the LABKEY_JAR_OPS) to match what you used previously. Going forward, <LABKEY_HOME>/labkey-tmp will be used.

• Service File Customizations
• Save and close the file.

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.

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

• Migrate Configuration to Application Properties
• Set Application Properties
• Upgrade LabKey
• Troubleshoot Installation and Configuration