• Download the New LabKey Server Distribution
• Locate your Existing LabKey Server Installation
• Prepare to Copy the New Files
• Copy Files from the New LabKey Server Distribution
• Install Third Party Components
• Check for Changes in the LabKey Server Configuration File
• Restart Tomcat and Test
• Troubleshooting

Download the New LabKey Server Distribution

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

• Download LabKey Server Community Edition
• Download the Windows distribution: Download zip (i.e. LabKeyxx.x-xxxx-bin.zip)
• Unzip the distribution bundle.

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

  C:\labkey\backup\v191

  .
• 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.

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.

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.

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.