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

Upgrade Changes for 20.7

The JDBC jars (jtds.jar, postgresql.jar, mysql.jar) are now versioned and distributed inside the module directories like any other third-party jar, making it unnecessary to copy them to the CATALINA_HOME/lib directory during installation and upgrade. When you upgrade to 20.7, delete these JDBC jar files from CATALINA_HOME/lib to avoid conflicts.

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.

Prepare to Copy the New Files

  • 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.
  • In the <LABKEY_ROOT>/backup directory, create a new subdirectory to store the backup of your current configuration. For instance, you could use a date, or a number that reflects the outgoing version. such as
  • Back up your resources by moving and copying the following directories to the new backup subfolder. Note that it is critical that you completely replace the /labkeywebapp, /modules, and /externalModules directories below.
    • Move <LABKEY_HOME>/bin
    • Move <LABKEY_HOME>/labkeywebapp
    • Move <LABKEY_HOME>/modules
    • Move <LABKEY_HOME>/externalModules (if it exists)
    • 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.

Copy the LabKey Server Configuration File

  • Back up the existing LabKey Server configuration file by copying it to your backup location. It is located in the <CATALINA_HOME>/conf/Catalina/localhost/ directory and named labkey.xml, LABKEY.xml, or ROOT.xml.
  • Copy the new labkey.xml configuration file from the /LabKeyxx.x-xxxx-bin directory to <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: SMTP, Encryption, LDAP, and File Roots.

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.

  • Merge any other settings you have changed in your old configuration file into the new one. Open both files in a text editor, and replace all parameters (designated as @@param@@) in the new file with the corresponding values from the old file.

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.


If menus, tabs, or other UI features appear to display incorrectly after upgrade, particularly if different browsers show different layouts, you may need to clear your browser cache to clear old stylesheets.


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all