• Notify Users
• Upgrade All Dependencies
• Download the New LabKey Server Distribution
• Locate the Existing LabKey Server Installation
• Stop Tomcat and Backup
• Deploy Distribution Files
• Install Third Party Components
• Check for Changes to labkey.xml
• Re-assert Tomcat Ownership
• Start Tomcat and Test
• Troubleshooting

Notify Users

• Before upgrade, notify your users in advance that the server will be down for a period of time.

Upgrade All Dependencies

• Before upgrading LabKey Server, it is important to upgrade Java, Tomcat, and your database (PostgreSQL or SQL Server) to their recommended versions. For details see: Supported Technologies
• If you did not install using the recommended directory structure, this is a reasonable time to make the switch. Using the root directory "/usr/local/labkey" allows you to keep all necessary components in one place.

Download the New LabKey Server Distribution

• Navigate to the directory /usr/local/labkey/src, the base directory for downloading and unpacking distributions:

cd /usr/local/labkey/src

• Premium Edition users can download their custom distribution from the Server Builds section of their client portal.
• Community Edition users can register and download the distribution package at Download LabKey Server Community Edition.
• To download the Linux/OSX package, get the URL from the button Download tar.gz and use wget, for example:

sudo wget http://labkey.s3.amazonaws.com/downloads/general/r/20.3.2/LabKey20.3.2-65320.7-community-bin.tar.gz

• The name of the distribution archive includes the version number, build number, and edition. For example, "LabKey20.3.2-65320.7-community-bin.tar.gz" indicates:
• version: 20.3.2
• build number: 65320.7
• edition: community
• Unpack the distribution archive. In the example below, substitute the pound symbols #### appropriately:

sudo tar xfz LabKey####-bin.tar.gz

• The unpacked bundle will now be located in a directory like:

/usr/local/labkey/src/LabKey####-bin/

• For a description of the files included in the distribution, see the topic Install on Linux: Main Components.

Locate Your Existing LabKey Server Installation

• Locate your LABKEY_HOME directory. The default location is /usr/local/labkey/labkey.
• Find your Tomcat home directory, referred to as CATALINA_HOME. The default location is usr/local/labkey/apps/apache/apache-tomcat-#.#.##.
• 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. This file may be named labkey.xml, LABKEY.xml, or ROOT.xml.

Stop Tomcat and Backup

• Shut down the Tomcat web server. Note that you do not need to shut down the database that LabKey Server connects to. To shutdown Tomcat, use a command like the following, or the script provided by Apache.

sudo systemctl stop tomcat

• Backup the database by following the topic: Backup and Maintenance
• Create a backup directory for your current server. For example, to backup LabKey version 20.3:

mkdir /usr/local/labkey/backups/labkey203

• For convenience, export the following, replacing pound symbols ####, and any path differences, to fit your environment:

export LABKEY_HOME=/usr/local/labkey/labkey
export BACKUP_LOCATION=/usr/local/labkey/backups/####
export CATALINA_HOME=/usr/local/labkey/apps/apache-tomcat-####
export LABKEY_DIST=/usr/local/labkey/src/LabKey####-bin

• Backup your resources by following these steps. It is critical that you completely replace the /labkeywebapp, /modules, and /externalModules directories below, to avoid including conflicting artifacts in the upgraded server.
• Move the following directories to the backup directory:

sudo mv $LABKEY_HOME/labkeywebapp $BACKUP_LOCATION
sudo mv $LABKEY_HOME/modules $BACKUP_LOCATION
sudo mv $LABKEY_HOME/pipeline-lib $BACKUP_LOCATION #If it exists.
sudo mv $LABKEY_HOME/externalModules $BACKUP_LOCATION #If it exists.

• Confirm that the LABKEY_HOME folder no longer contains these four subdirectories.
• Copy the following directories to the same backup subfolder. You may need to return to their current status but it is not necessary to fully replace these directories in the upgrade process.

sudo cp -R $CATALINA_HOME/lib $BACKUP_LOCATION
sudo cp -R $CATALINA_HOME/conf $BACKUP_LOCATION

Deploy Distribution Files

• Copy the contents of the distribution directory as follows.

sudo cp -R $LABKEY_DIST/labkeywebapp $LABKEY_HOME
sudo cp -R $LABKEY_DIST/modules $LABKEY_HOME
sudo cp -R $LABKEY_DIST/pipeline-lib $LABKEY_HOME ##Only necessary if installing a remote pipeline server.##

• If your installation includes other modules not included the distribution bundle, recompile these modules against the server version you're installing (or otherwise obtain updated versions of the modules) and add them to $LABKEY_HOME/externalModules
• Copy the contents of LABKEY_DIST/tomcat-lib into CATALINA_HOME/lib. Choose to overwrite any jars with the same names 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. For example:

sudo cp $LABKEY_DIST/tomcat-lib/javax.activation.jar $CATALINA_HOME/lib
sudo cp $LABKEY_DIST/tomcat-lib/labkeyBootstrap.jar $CATALINA_HOME/lib
sudo cp $LABKEY_DIST/tomcat-lib/mail.jar $CATALINA_HOME/lib

• If you have customized the server's stylesheet, restore your modified stylesheet from the backup directory into the new LABKEY_HOME/labkeywebapp directory.

Install Third Party Components

• See Installation: Third-Party Components 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.

Check for Changes to labkey.xml

• Compare the outgoing and incoming labkey.xml (or root.xml) files.
• If necessary, merge any other settings you have changed in the outgoing file into the incoming one.
• If there are changes, update CATALINA_HOME/conf/Catalina/localhost/labkey.xml.

Reassert Tomcat User Ownership

If necessary, reassert the Tomcat user's ownership over LABKEY_HOME and CATALINA_HOME. For example:

sudo chown -R tomcat: $CATALINA_HOME
sudo chown -R tomcat: $LABKEY_HOME

Start Tomcat and Test

• Start Tomcat:

sudo systemctl start tomcat

• If you have any problems starting Tomcat, check the Tomcat logs in the CATALINA_HOME/logs directory.
• At this point LabKey Server should be up and running.
• It is good practice to review Server Information and System Properties on the Admin Console immediately after the upgrade to ensure they are correct.
• 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.

Related Topics

• Install on Linux: Main Components
• Troubleshoot Server Installation and Configuration