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.
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.
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
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).
Since you previously completed the migration to LabKey Server with embedded Tomcat 10, this upgrade is much simpler. You do not need (or want) to change the service file or application.properties file if you are simply upgrading and not making other changes. You only need to:
Learn more in this topic: Content Security Policy
This section outlines the details of locations in your LabKey Server installation. We use variables like <LABKEY_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 user that runs the LabKey service.
Variable | Windows default location | Description |
---|---|---|
LK_ROOT | C:\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 C:\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. |
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. The upgrade process itself will not touch this location.
Note however, that you may need to update your own external modules with each release. Even if changes are not needed, you will need to update the schema versions on them every year, even if there are no schema changes. This is what we do internally and it ensures that module versions are up to date and an automatic upgrade will work when it becomes necessary.
If you were 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.
1. Download the distribution tar.gz file:
<LK_ROOT>\src\NAME_OF_DISTRIBUTION.tar.gz
Unpack the distribution in that location.
tar -xvzf NAME_OF_DISTRIBUTION.tar.gz
It will contain: