This topic covers the manual upgrade process for LabKey Server.
Download the New LabKey Server Distribution
Register and download the appropriate LabKey Server distribution bundle for your operating system via this link:
Unzip or untar the distribution bundle. We recommend using the location <LABKEY_ROOT>/src/labkey as a base
for unpacked distributions. On Unix-based systems, the command tar xfz LabKeyxx.x-xxxx-bin.tar.gz
will unzip and untar the archive. For a description of the files included in the distribution, see the topic Install the LabKey Server System Components
The unpacked bundle will now be located in a directory like (including the version number) <LABKEY_ROOT>/src/labkey/LabKeyxx.x-xxxx-bin/
Locate Your Existing LabKey Server Installation
If you did not install using the recommended directory structure
, this is a reasonable time to make the switch if practical. Identifying a <LABKEY_ROOT> (i.e. depending on your platform either "C:\labkey" or "/usr/local/labkey") allows you to keep all necessary components in one place.
Locate your <LABKEY_HOME>
directory, the directory to which you previously installed LabKey Server. The default location is <LABKEY_ROOT>/labkey.
Find your Tomcat home directory, referred to as <CATALINA_HOME>
. By default it will be <LABKEY_ROOT>/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>/labkeywebapp: The directory containing the LabKey Server web application.
- <LABKEY_HOME>/modules: The directory containing the LabKey Server modules.
- <LABKEY_HOME>/externalModules: The directory containing 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 existing LabKey Server libraries and JAR files.
- <CATALINA_HOME>/conf/Catalina/localhost/labkey.xml: The LabKey Server configuration file should be located in . This file may be named labkey.xml, LABKEY.xml, or ROOT.xml.
Prepare to Copy the New Files
Shut down the Tomcat web server. If you are running LabKey Server on Windows, it may be running as a Windows service, and you should shut down the service. (You can do this via the Services panel on Windows.) If you are running on a Unix-based system, you can use the shutdown script in the <CATALINA_HOME>/bin directory. Note that you do not need to shut down the database that LabKey Server connects to.
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 incrementing integer style such as C:\labkey\backup\my_backup1
Back up your resources by moving or copying the following directories to the new backup subfolder:
- Move <LABKEY_HOME>/labkeywebapp
- Move <LABKEY_HOME>/modules
- Move <LABKEY_HOME>/externalModules (if it exists)
- Copy <CATALINA_HOME>/lib
- Copy <CATALINA_HOME>/conf
Create the following new directories to replace the ones you moved:
- <LABKEY_HOME>/externalModules (If your installation included an externalModules directory that you moved.)
For installations that use the LabKey Server Enterprise Pipeline
on the remote server, follow these steps:
- Perform the same steps for the labkeywebapp and modules directories as described above
- Copy the <LABKEY_HOME>/pipeline-lib directory on the remote server to the backup directory
- Create a new directory <LABKEY_HOME>/pipeline-lib on the remote server
Copy Files from the New LabKey Server Distribution
Copy the contents of the following subdirectories of the unpacked <LABKEY_ROOT>/src/labkey/LabKeyxx.x-xxxx-bin/ directory into the appropriate locations:
- Copy the contents of the /labkeywebapp directory to the new <LABKEY_HOME>/labkeywebapp directory.
- Copy the contents of the /modules directory to the new <LABKEY_HOME>/modules directory.
- Copy the contents of the /externalModules directory (if any) to the new <LABKEY_HOME>/externalModules directory.
- If you are running Windows, copy the executable files and Windows libraries in the unpacked distribution /bin directory to the <LABKEY_HOME>/bin directory. If you are running on Unix, you will need to download these components separately. See Third-Party Components and Licenses (Optional Install) for more information.
- Copy the LabKey Server 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.
For installations that use the LabKey Server Enterprise Pipeline
, on the remote server, copy the following directories/files from the unzipped location to <LABKEY_HOME> on the remote server:
- bin (only if on Windows)
Install Third Party Components
If you are running Windows:
- Back up your existing <LABKEY_HOME>/bin directory by moving it to the backup directory. Note that this will lose any third-party binaries that you might have installed manually. Be sure to reapply them again if needed.
- Create the directory <LABKEY_HOME>/bin
- Copy the executable files and Windows libraries in the unpacked distribution /bin directory to the <LABKEY_HOME>/bin directory.
If you are running on Unix:
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.
Note: This will upgrade the versions of X!Tandem and TPP tools which are currently being used with LabKey Server.
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 labkey.xml Configuration File Reference
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
Restart the Tomcat web server. If you have any problems starting Tomcat, check the Tomcat logs in the <CATALINA_HOME>/logs directory.
Navigate to your LabKey Server application with a web browser using the appropriate URL address and upgrade the LabKey Server application modules when you are prompted to do so.
It is good practice to review the Properties 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.