Download the New LabKey Server Distribution

• Download the appropriate LabKey Server archive file for your operating system from the download page. On Windows, use LabKeyxx.x-xxxx-bin.zip; on Unix-based systems, used LabKeyxx.x-xxxx-bin.tar.gz.
• Unzip or untar the archive file to a temporary directory on your computer. 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 section Install the LabKey Server System Components in the topic Install Required Components.

Locate Your Existing LabKey Server Installation

• Locate your LabKey Server home (<labkey-home>) directory, the directory to which you previously installed LabKey Server. For example, if you used the LabKey Server binary installer to install LabKey Server on Windows, your default <labkey-home> directory is C:\Program Files\LabKey Server.
• Find your Tomcat home directory (<tomcat-home>). If you used the LabKey Server binary installer to install an earlier version of LabKey Server on Windows, your default Tomcat directory is <labkey-home>/jakarta-tomcat-n.n.n.
• Find 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:
• lib: The existing LabKey Server libraries should be located in <tomcat-home>/lib.
• labkeywebapp: The directory containing the LabKey Server web application (<labkeywebapp>) may be named labkeywebapp or simply webapp. It may be in the <labkey-home> directory or may be a peer directory of the <tomcat-home> directory.
• modules: The directory containing the LabKey Server modules. This directory is found in the <labkey-home> directory.
• externalModules: The directory containing additional, user-developed LabKey Server modules. This directory is found in the <labkey-home> directory. (Not all installations contain an externalModules directory. If you don't see an externalModules directory, you can skip this step.)
• labkey.xml: The LabKey Server configuration file should be located in <tomcat-home>/conf/Catalina/localhost/. 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 <tomcat-home>/bin directory. Note that you do not need to shut down the database that LabKey Server connects to.
• Create a new directory to store the a backup of your current configuration. Create the directory <labkey-home>/backup1
• NOTE: if the directory <labkey-home>/backup1 already exists, increment that directory name by 1. For example, if you already have backup directories named backup1 and backup2, then new backup directory should be named <labkey-home>/backup3
• Back up your existing labkeywebapp directory:
• Move the <labkeywebapp> directory to the backup directory
• Back up your existing modules directory:
• Move the <labkey-home>/modules directory to the backup directory
• Back up your existing externalModules directory, if it exists:
• Move the <labkey-home>/externalModules directory to the backup directory
• Back up your <tomcat-home>/lib directory:
• Copy the <tomcat-home>/lib directory to the backup directory
• Back up your <tomcat-home>/conf directory:
• Copy the <tomcat-home>/conf directory to the backup directory
• Create the following new directories
• <labkey-home>/labkeywebapp
• <labkey-home>/modules
• <labkey-home>/externalModules (If your installation includes an externalModules directory.)

• For installations that use the LabKey Server Enterprise Pipeline, on the remote server:
• 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 LabKeyxx.x-xxxx-bin/labkeywebapp directory to the new <labkey-home>/labkeywebapp directory.
• Copy the contents of the LabKeyxx.x-xxxx-bin/modules directory to the new <labkey-home>/modules directory.
• Copy the contents of the LabKeyxx.x-xxxx-bin/externalModules directory to the new <labkey-home>/externalModules directory.
• If you are running Windows, copy the executable files and Windows libraries in the LabKeyxx.x-xxxx-bin/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 for more information.
• Copy the LabKey Server libraries from the /LabKeyxx.x-xxxx-bin/tomcat-lib directory into <tomcat-home>/lib. Choose to overwrite any jars that are already present. Do not delete or move the other files in this folder (<tomcat-home>/lib), 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 labkeywebapp directory to <labkey-home> on the remote server
• Copy the modules directory to <labkey-home> on the remote server
• Copy the pipeline-lib directory to <labkey-home> on the remote server
• Copy the bin directory to <labkey-home> on the remote server (if on Windows)
• Copy the file tomcat-lib/labkeyBootstrap.jar to <labkey-home> on the remote server

Install Third Party Components

• If you are running Windows:
• Back up your existing bin directory: Move the <labkey-home>/bin directory 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 LabKeyxx.x-xxxx-bin/bin directory to the <labkey-home>/bin directory.
• If you are running on Unix:
• You will need to download and upgrade these components. See Third-Party Components and Licenses for the list of required components, required versions and installation instructions.
• 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 (the file named labkey.xml, LABKEY.xml, or ROOT.xml)
• The file is located in <tomcat-home>/conf/Catalina/localhost/
• Copy the file to the backup directory
• Copy the new labkey.xml configuration file from the /LabKeyxx.x-xxxx-bin directory to <tomcat-home>/conf/Catalina/localhost/labkey.xml.
• Alternately, 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, copy labkey.xml to <tomcat-home>/conf/Catalina/localhost/ROOT.xml.
• 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.
• Important: The name of the LabKey Server configuration file determines the URL address of your LabKey Server application. If you change this configuration file, any external links to your LabKey Server application will break. Also, since Tomcat treats URLs as case-sensitive, external links will also break if you change the case of the configuration file. For that reason, you may want to name the new configuration file to match the original one. For more information, see labkey.xml Configuration File.

Restart Tomcat and Test

• Restart the Tomcat web server. If you have any problems starting Tomcat, check the Tomcat logs in the <tomcat-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.

Troubleshooting

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. For example, the left screenshot below shows an incorrect display after upgrade from version 11.2 to 13.3 on windows8; the right image is after a hard reset (ctrl-F5 in Chrome) and shows the correct default home page layout.