These topics provide step by step instructions for upgrading an existing LabKey Server installation to a newer version.
This documentation section has been updated for upgrading to versions 24.3 and later using embedded Tomcat. Versions 23.11 and earlier used a standalone installation (of Tomcat 9) and different configuration method.
If you need to do any intermediate upgrades to bring your current server to a version that supports upgrade to 24.3 (or later), please review
the documentation archives for the previous upgrade process to bring your server to version 23.11 prior to following these steps.
Supported Versions for Upgrade
Please see the
LabKey Releases and Upgrade Support Policy page. In some cases, you may need to perform an intermediate upgrade to reach the latest version.
Best Practice: Use a Staging Server
We recommend first upgrading a
Staging server, as it will help you confirm that the production upgrade will be successful. Bring up a temporary staging server using your current version and a copy of the production database, then upgrade that. Once testing is complete, you can repeat the upgrade process on your production server.
Learn more in this topic:
Use a Staging Server
Upgrade Instructions
Version 24.3 of LabKey Server changes the way we package and deliver the software. In addition to embedding Tomcat, we now provide a single "labkeyServer.jar" file that bundles the modules, webapp, and other dependencies that will be unpacked when the service starts up and deploys the distribution. This process significantly simplifies the installation and upgrade process that previously required more manual copying or scripting.
The files necessary for both Linux and Windows installation are included in the same distribution. Please carefully review the revised upgrade instructions for your platform.
Upgrade on Linux or OSX
Upgrade on Windows
Considerations and Notes
Reset Browser Cache
If menus, tabs, or other UI features appear to display incorrectly after upgrade, particularly if different browsers show different layouts, you may need to clear your browser cache to clear old stylesheets.
Pipeline Jobs
It is a known issue that pipeline jobs that are in progress prior to an upgrade may not resume successfully after an upgrade. The same is true for jobs that may have hit an error condition if they are retried after an upgrade. In general, hotfix releases should not have incompatibilities when resuming jobs, but significant version upgrades will sometimes exhibit this problem. When possible, it is recommended to let jobs complete prior to performing an upgrade.
To check the status of jobs, use the
Pipeline link from the Admin Console.
Upgrade Performance
From time to time, one time migrations may result in longer upgrade times than expected for certain modules. Check the logs and do not simply "cancel" an upgrade midstream as it will likely leave your server in an unstable state.
Related Topics
LabKey Cloud Solutions AvailableLabKey can take care of the upgrade process for you, so that you can focus on your research. Learn more on our website:
