This topic covers the manual upgrade process for LabKey Server running on a Windows machine.

Pre-Upgrade Steps

Notify Users

Upgrade All Dependencies

  • Before upgrading LabKey Server, it is important to upgrade Java, Tomcat, and your database (PostgreSQL or SQL Server) to their recommended versions. For details see: Supported Technologies
  • If you did not install using the recommended directory structure, this is a reasonable time to make the switch. Using our recommendations allows you to keep all necessary components in one place and more easily follow our documentation.

Download the New LabKey Server Distribution

Register and download the appropriate LabKey Server distribution bundle using this link:

Locate Your Existing LabKey Server Installation

  • Locate your <LABKEY_HOME> directory, the directory to which you previously installed LabKey Server. A typical location is C:\labkey\labkey.
  • Find your Tomcat home directory, referred to as <CATALINA_HOME>. A typical location will be C:\labkey\apps\apache\apache-tomcat-x.x.xx.
  • Confirm the locations of the existing LabKey Server files on your system for each of the following components, in preparation for replacing them with the corresponding LabKey Server files:
    • <LABKEY_HOME>/bin: Contains the LabKey executables.
    • <LABKEY_HOME>/labkeywebapp: Contains the LabKey Server web application.
    • <LABKEY_HOME>/modules: Contains the LabKey Server modules.
    • <LABKEY_HOME>/externalModules: Contains additional, user-developed LabKey Server modules, if applicable. (Not all installations contain an externalModules directory. If you don't see one, skip this step.)
    • <CATALINA_HOME>/lib: The LabKey Server libraries and JAR files.
    • <CATALINA_HOME>/conf/Catalina/localhost/labkey.xml: The LabKey Server configuration file. This file may be named labkey.xml, LABKEY.xml, or ROOT.xml.

Stop Tomcat and Back Up

Stop Tomcat

  • Shut down the Tomcat web server. On Windows, Tomcat is typically run as a Windows service, in which case you should shut down Tomcat using the Services panel. Note that you do not need to shut down the database that LabKey Server connects to.
  • Open the Service panel, select Apache Tomcat #.#, and click Stop the service.

Back Up Database

Back Up Current LabKey Installation

  • In the <LABKEY_ROOT>/backups directory, create a new subdirectory to store the backup. For instance, you could use a date, or other shorthand that reflects the outgoing version. such as
  • Back up your resources following these steps.
    • Important: it is critical that you completely replace the prior contents of the /labkeywebapp, /modules, and /externalModules directories, to avoid including conflicting artifacts in the upgraded server.

  • Move the following directories to the backup directory:
    • Move <LABKEY_HOME>/bin
    • Move <LABKEY_HOME>/labkeywebapp
    • Move <LABKEY_HOME>/modules
    • Move <LABKEY_HOME>/externalModules (if it exists)
  • Confirm that the LABKEY_HOME folder no longer contains these four subdirectories and the backup location does.
  • Copy the following directories to the same backup directory:
    • Copy <CATALINA_HOME>/lib
    • Copy <CATALINA_HOME>/conf

Copy Files from the New LabKey Server Distribution

  • Copy the the following subdirectories from the unpacked new distribution <LABKEY_ROOT>/src/labkey/LabKeyxx.x-xxxx-bin/ into the appropriate locations:
  • Copy the /bin directory to <LABKEY_HOME>.
  • Copy the /labkeywebapp directory to <LABKEY_HOME>.
  • Copy the /modules directory to <LABKEY_HOME>.
  • Copy the /externalModules directory (if any) to <LABKEY_HOME>.
  • Copy the .jar libraries from the /tomcat-lib directory into <CATALINA_HOME>/lib. Choose to overwrite any jars that are already present. Do not delete or move the other files in the <CATALINA_HOME>/lib folder, as they are required for Tomcat to run.
  • If you have customized the stylesheet for your existing LabKey Server installation, copy your modified stylesheet from the backup directory into the new <LABKEY_HOME>/labkeywebapp directory.

Restore Third Party Components

  • If you are using any third party components and libraries, restore them from the backup directory. (Backing up your existing <LABKEY_HOME>/bin directory by moving it to the backup directory causes the loss of any third-party binaries that might have been installed manually.)
  • Ensure that the <LABKEY_HOME>/bin directory is on your system path, or on the path of the user account that will be starting Tomcat.

Check for Changes in the LabKey Server Configuration File

  • Compare the outgoing and incoming labkey.xml (or root.xml) files.
  • If there are changes, backup the outgoing labkey.xml file.
  • Then merge any settings you have changed in the outgoing file into the incoming one.
  • Finally update CATALINA_HOME/conf/Catalina/localhost/labkey.xml.
Note: The name of the LabKey Server configuration file determines the URL address of your LabKey Server application. If you change the name (or case) of this configuration file, any external links to your LabKey Server application will break. For more information, see Installation: LabKey Configuration File.

For example, if your existing LabKey Server installation has been running as the root web application on Tomcat and you want to ensure that your application URLs remain identical after the upgrade, rename the copied labkey.xml to ROOT.xml in the same localhost subfolder location.

Restart Tomcat and Test

  • Using the Services panel, start the Tomcat web server. If you have any problems starting Tomcat, check the Tomcat logs in the <CATALINA_HOME>/logs directory.
  • Navigate to the LabKey Server application with a web browser using the appropriate URL address.
  • It is good practice to review the module version numbers on the Admin Console immediately after the upgrade to ensure they are correct.
  • At this point LabKey Server should be up and running. If you have problems, check the Tomcat logs, and double-check that you have properly named the LabKey Server configuration file and that its values are correct.

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all