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 a version of LabKey that uses embedded Tomcat 10. These instructions are written for Linux Ubuntu and require familiarity with Linux administration. If you are upgrading on another version of Linux (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.
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 confirm that both Java and your database are using supported versions. If you need to make any upgrades, do so prior to upgrading the server. For details see:
Supported Technologies
Review Existing Installation
Confirm that your existing installation follows the
guidelines we provide. Specifically, the new distribution jar will overwrite some locations under <LABKEY_HOME>, so it's important that any user-specific content is in the correct location(s).
Upgrade LabKey
Since you previously completed the migration to LabKey Server with embedded Tomcat 10, this upgrade is simple. You do not need (or want) to change the service file or application.properties file if you are simply upgrading and not making specific configuration changes. You only need to:
When you restart the same service that was running, the new jar will be deployed and the database upgraded. Tail the <LABKEY_HOME>/logs/labkey.log to see progress.
More detail about the directory structure in your existing installation is provided below for reference.
Detailed Overview of LabKey Server Installation
This section outlines the details of locations in your LabKey Server installation.
| Variable | Linux default location | Description |
|---|
| LK_ROOT | /labkey | This is the top level for LabKey-related content. |
| | <LK_ROOT>/src | Storage of current and past LabKey tar.gz installation binaries. |
| | <LK_ROOT>/apps | Recommended location for related apps like Java and your database. |
| | <LK_ROOT>/backupArchive | This 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>/logs | This location holds the logs. |
| | <LABKEY_HOME>/externalModules | The directory for any additional, user-developed modules you use. You may not need this location. |
| | <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. |
|
| | <LABKEY_HOME>/labkeywebapp | The directory containing the LabKey Server web application. This location will be overwritten at every upgrade. Do not place customizations under this location. |
| | <LABKEY_HOME>/modules | The directory containing the LabKey Server modules. This location will be overwritten at every upgrade. Do not place custom modules under this location. |
| | <LABKEY_HOME>/backup | Some versions place a temporary backup here. This location will be overwritten at every upgrade. Do not place customizations under this location. |
| | <LABKEY_HOME>/labkey-tmp | Temp location used internally. This location will be overwritten at every upgrade. Do not place customizations under this location. |
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.
Related Topics
