Follow the instructions in this topic to manually upgrade an existing LabKey Server running on a Windows machine to a new version. Note that Windows is no longer supported for new installations. These instructions assume you have familiarity with Windows system administration.
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 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:
When you restart the same service that was running, the new jar will be deployed and the database upgraded. Watch the <LABKEY_HOME>\logs\labkey.log to see progress.
Detailed Overview of LabKey Server Installation
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. |
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 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.
How to 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:
<LK_ROOT>\src\NAME_OF_DISTRIBUTION.tar.gz
Unpack the distribution in that location.
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
- A config directory, containing an application.properties template
- An example Windows service install script named "install_service.bat"
- An example systemd unit file for Linux (Not needed for installation on Windows)
Continue with the
upgrade process here.
Related Topics
