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. The process assumes that you have previously installed LabKey using our recommended folder structure. 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.

In this release, this topic is specifically for upgrading for the first time to version 24.3 (or later) using embedded Tomcat. Versions 23.11 and earlier used a standalone installation (of Tomcat 9) and a different configuration method. You'll be able to draw configuration information from that previous installation to upgrade to version 24.3 with embedded Tomcat 10 using the instructions here. In future, the upgrade process will be even simpler for you.

If you need to do any intermediate upgrades to bring your current server to a version that supports upgrade to 24.3, please review the documentation archives for the previous upgrade process to bring your server to version 23.11 prior to following these steps.

If you previously upgraded to use embedded Tomcat with 24.3 and are upgrading to a later release, follow the simpler steps for Future Upgrades below.

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

Note that Postgres 11 is no longer supported in LabKey version 24.3.

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.

VariableWindows default locationDescription
LK_ROOTC:\labkeyThe top level under which all LabKey-related files are nested.
 <LK_ROOT>\appsThis is a good location for installation of related apps like Java and your database.
 <LK_ROOT>\backupArchiveThis is a good location for storing your own backups, including the backup prior to performing this upgrade.
 <LK_ROOT>\srcThis is where your current and past LabKey tar.gz installation binaries are saved.
This is where the actual LabKey application is located.
 <LABKEY_HOME>\logsThis location will be created during the setup steps below and will hold the logs.
 <LABKEY_HOME>\labkeywebappThe directory containing the LabKey Server web application. This location will be created during server startup and thus overwritten at every upgrade. If you have any customizations under this location, you need to move them before this upgrade.
 <LABKEY_HOME>\modulesThe directory containing the LabKey Server modules. This should only contain modules provided to you in the LabKey distribution. Any of your own modules should be in the parallel "externalModules" directory.
 <LABKEY_HOME>\labkey-tmpThe Tomcat temp directory that LabKey will be using after the upgrade. Your previous installation may have used a location named "tomcat-tmp" for the same kinds of things; you do not need to continue to use that previous location.
 <LABKEY_HOME>\externalModulesThe directory for any additional, user-developed modules you use. You may not need this location.
 <LABKEY_HOME>\pipeline-libThis is a legacy directory that is no longer in use. If you have this directory, you can delete it.
 <LABKEY_HOME>\backupThe automated upgrade process will store the immediate prior backup in this location. This location will be overwritten each time the server starts. If you already have this directory and anything saved in it, move it to <LK_ROOT>\backupArchive before continuing.
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.

It is important to note that the contents of the following locations will be replaced completely by deploying the LabKey distribution. Any content you want to retain must be moved elsewhere before the upgrade. You may not have all of these locations currently.
  • <LABKEY_HOME>\modules
  • <LABKEY_HOME>\labkeywebapp
  • <LABKEY_HOME>\backup
  • <LABKEY_HOME>\labkey-tmp

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 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:

CATALINA_HOMEVaries. Could be:
C:\labkey\tomcat OR
C:\labkey\apps\tomcat OR
This is where your previous Tomcat version is currently installed. It may be one of the locations to the left or may be somewhere else. All of the following resources will be under this <CATALINA_HOME> location.
 <CATALINA_HOME>\SSLThis is where your existing Java KeyStore is located. You will be moving it to <LABKEY_HOME>\SSL to use after this upgrade.
 <CATALINA_HOME>\confContains configuration information including the server.xml and/or web.xml files.
CONFIG_FILE<CATALINA_HOME>\conf\Catalina\localhostThe main LabKey configuration file. This will be named either ROOT.xml or labkey.xml, or something similar.
 <CATALINA_HOME>\libThe existing LabKey Server libraries and JAR files.
 <CATALINA_HOME>\binThe location of tomcat9w.exe and setenv.bat

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
Copy these items and store them in your backupArchive location.

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.
2. Place it in the <LK_ROOT>\src location:

Unpack the distribution in that location.


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 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
Create this directory to contain logs that will be written when the server is running:

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


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 File

The Tomcat 10 Embedded application requires the <LABKEY_HOME>\config\ 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:

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.

5. Copy the "prunsrv.exe" file to your <LABKEY_HOME> directory.
  • 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.
6. Copy the new "install_service.bat" file from your unpacked LabKey distribution tar.gz to <LABKEY_HOME>. Edit the <LABKEY_HOME>\install_service.bat file to provide the information you collected earlier that is unique to your particular instance, including but not limited to paths, memory configurations, etc.

Review details of commonly needed edits to the service file in this topic (it will open in a new tab):

7. To install your Windows Service, open a Command Prompt and navigate to the <LABKEY_HOME> directory. Both "install_service.bat" and "prunsrv.exe" are in this location.

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.
It is best practice to have first completed this upgrade using a staging server, and then perform your own testing to validate the upgrade. Once testing on staging is complete, proceed to repeat the upgrade process of your production database.

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 your first migration to LabKey Server with embedded Tomcat 10, future upgrades 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

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all