Follow the instructions in this topic to manually upgrade an existing LabKey Server running on a Windows machine to a new version. The process assumes that you have previously installed LabKey using the recommended folder structure described in Install on Windows. 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
• 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
• Confirm Ownership of Installation
• Restore Any Third Party Components (If needed)
• 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 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.

Move Custom log4j2.xml and Custom Stylesheet (Uncommon)

If you had 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 during upgrades. You will provide the path to the new location in the application.properties file.

If you had customized the server's stylesheet by placing it in the <LABKEY_HOME>\labkeywebapp directory, save it elsewhere before you upgrade. After you 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 is being used to start your Tomcat service (referred to below as the <TOMCAT_USER>). This should not be the admin 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.

• The existing Windows service: It should be accessible by using <CATALINA_HOME>\bin\tomcat9w.exe
• The <CATALINA_HOME>\bin\setenv.bat script file

The distribution includes an example "install_service.bat" file to start with. Later in this topic, we will guide you in customizing it as needed.

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, we suggest that 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. You may also want to make a copy of the existing contents of <LABKEY_HOME> to save in your backupArchive location, particularly if you were using any custom modules or third party components.
2. Stop Tomcat. Open the Service panel, select Apache Tomcat #.#, and click Stop the service.
3. Back up your existing database, files and configuration and log files.
4. Back up your existing Tomcat configuration, including any scripts you have created that reside in the <CATALINA_HOME>\bin directory, including the setenv.bat and the service that starts Tomcat.
5. If you currently have anything in <LABKEY_HOME>\bin, you may want to save a copy to the backupArchive. This directory is overwritten during upgrade.

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.

<LK_ROOT>\src\NAME_OF_DISTRIBUTION.tar.gz

Unpack the distribution in that location.

tar xfz 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)

Deploy Distribution Files

Copy the following from the unpacked distribution into <LABKEY_HOME>.

• The labkeyServer.jar
• The config directory
• The bin directory

<LABKEY_HOME>\logs

Copy the directory that contains your Java Keystore (often but not necessarily under <CATALINA_HOME>) and place it under <LABKEY_HOME>:

<LABKEY_HOME>\SSL

Restore Third Party Components

• If you are using any third party components and libraries listed in this topic, restore them from the backupArchive directory. (Backing up your existing <LABKEY_HOME>\bin directory by moving it to the backupArchive directory causes the loss of any third-party binaries that might have been installed manually.)
• Ensure that the <LABKEY_HOME>\bin directory is on the system path if you are using binaries here.

Confirm Ownership of Installation

If your Windows installation has custom permissions for folder and file security, we recommend you confirm that the files and folders under <LABKEY_HOME> have the <TOMCAT_USER> configured with Full Control permissions under the Security tab of the properties of your LabKey files.

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

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 C:\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 configurations, Java paths, etc. Locating where these service details were defined was covered in the earlier section about your prior Tomcat configuration.

3. Access your Windows Services and disable the old Tomcat/LabKey service.

4. Download the Apache Commons Daemon and unzip it. <LK_ROOT>\apps is a good place to store the download.

• https://dlcdn.apache.org/commons/daemon/binaries/windows/commons-daemon-1.3.4-bin-windows.zip

• Note: Be sure to copy the correct file for your CPU. In the downloaded bundle, the 32-bit version is in the main directory and there is a 64-bit version in the AMD64 subfolder. If you use the incorrect one, the service will not install correctly. You will need to delete that partially-created service, and recreate it with the correct prunsrv version.

• Edit the LABKEY_HOME and LABKEY_APPS paths if you did not use our suggested locations.
• Edit JAVA_HOME to point to where the JDK is installed.
• Edit the line pointing to prunsrv.exe to point to the copy you just placed in <LABKEY_HOME>. It is important that both prunsrv.exe and the script file itself are in the same location, i.e. <LABKEY_HOME>. Edit the script we send so that the line pointing to prunsrv reads:

  --Install "%LABKEY_HOME%\prunsrv.exe" ^

• Service File Customizations

Run the following command to install the service:

install_service.bat install

Start Server, Test, then Delete Tomcat

Once the service is successfully installed, go to the Windows Services console and start your service.

• If the service starts correctly, new logs will be generated. You should be able to see the <LABKEY_HOME>\logs\labkey.log file growing and your LabKey instance will come back online.
• Review the log file for any errors and to check on the progress of your upgrade migration.
• Once upgrade is complete, access the running server 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.

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 and bin directory under <LABKEY_HOME> with the newer ones you unpacked.
5. Start your LabKey service.

Related Topics

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