This topic explains how to upgrade LabKey Server to version 2.0. Before you upgrade, it's best to notify your users that the system will be down for a period of time.

If you are upgrading to a new version of Apache Tomcat, see the Supported Tomcat Versions page for important information about using different versions of Tomcat with LabKey Server.

Upgrade Shortcuts

You can now upgrade LabKey Server on Windows using the Windows binary installer. Follow the steps in this help topic if you prefer to upgrade LabKey Server manually.

If you are upgrading LabKey Server on Linux, you can use the upgrade.sh script to streamline the upgrade process. Type "upgrade.sh" with no parameters in a console window for help on the script's parameters.

Download the New LabKey Server Distribution

• Download the appropriate LabKey Server archive file for your operating system from the download page. On Windows, use LabKey2.0-xxxx-bin.zip; on Unix-based systems, used LabKey2.0-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 LabKey2.0-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 Install Required Components topic.

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. 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 these three components, in preparation for replacing them with the corresponding LabKey Server 2.0 files:
• lib: The existing LabKey Server libraries should be located in <tomcat-home>/common/lib.
• labkeywebapp: The directory containing the LabKey Server web application (<labkeywebapp>) may be named labkeywebapp or simply webapp. It may be a peer directory of the <tomcat-home> directory.
• 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. 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.
• Back up your existing <labkey-home>/webapp directory to <labkey-home>/webapp-bak.
• Back up your <tomcat-home>/conf directory.
• Create the following new, empty directories:
• <labkey-home>/labkeywebapp
• <labkey-home>/modules
• <labkey-home>/bin

Copy Files from the New LabKey Server Distribution

• Copy the contents of the LabKey2.0-xxxx-bin/labkeywebapp directory to the new <labkey-home>/labkeywebapp directory.
• Copy the contents of the LabKey2.0-xxxx-bin /modules directory to the new <labkey-home>/modules directory.
• If you are running Windows, copy the executable files and Windows libraries in the LabKey2.0-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 /LabKey2.0-xxxx-bin/common-lib directory into <tomcat-home>/common/lib. Choose to overwrite any jars that are already present. Do not delete or move the other files in this folder, as they are required for Tomcat to run.
• Copy the LabKey Server libraries from the /LabKey2.0-xxxx-bin/server-lib directory into <tomcat-home>/server/lib. Do not delete or move the other files in this 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.

Copy the LabKey Server Configuration File

• Back up the existing LabKey Server configuration file (the file named labkey.xml, LABKEY.xml, or ROOT.xml) by renaming it to labkey.xml.old.
• Copy the new labkey.xml configuration file from the /LabKey2.0-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. Note that LabKey Server 2.0 adds a new line to this file to tell Tomcat to use a special ClassLoader.

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. Note that if you name the configuration file something other than labkey.xml, you will also need to edit the context path settings within the configuration file. For more information, see Modify the Configuration File.

Note: If you are upgrading from CPAS 1.0 to LabKey Server 2.0, your configuration file will contain a number of additional <Environment> tags. These tags specify settings that are now saved in the database. When you upgrade, these settings will be copied to the database, so after you upgrade, you can delete them. There's no harm in leaving them either, as LabKey Server will ignore them, but you may want to clean them up to avoid confusion.

Note: If you are upgrading from LabKey Server 1.3 or 1.4, you only need to add one line to your LabKey Server configuration file, within the <context> tags:

<Loader loaderClass="org.fhcrc.labkey.bootstrap.LabkeyBootstrapClassLoader"/>

Verify Path References

• Add a reference to the <labkey-home>/bin directory to your system path, or to the path of the user account that will be starting Tomcat.
• Ensure that Perl is on the system path (see Configure the Web Application for more information on configuring Perl).

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.

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.