On Premise to Hosted Upgrade Procedures

This section provides instructions for upgrading existing on premise Clarity LIMS deployments to hosted deployments. For assistance with upgrade steps, contact the Illumina Support team.

From Versions 4.2 / 4.3 / 5.0 / 5.1 / 5.2 / 6.0 / 6.1 /6.2 (PostgreSQL) and 4.2 / 4.3 / 5.0 / 5.1 / 5.2 (Oracle) to 6.3

This section provides the steps required to upgrade an existing on-premise deployment of Clarity LIMS to a RedHat Enterprise Linux/Oracle Linux compatible hosted deployment of Clarity LIMS v6.3.

For installation requirements, see Technical Requirements.

Migration Paths

The following table shows the applicable migration paths.

From	To	Notes
PostgreSQL: v4.2 On-premise v5.0 On-premise v5.1 On-premise	v6.3 hosted	Upgrading from CentOS6 to Oracle Linux v8.10 (on-premise to hosted).
PostgreSQL: v4.3 On-premise v5.2 On-premise v6.0 On-premise v6.1 On-premise	v6.3 hosted	Upgrading from CentOS7 to Oracle Linux v8.10 (on-premise to hosted).
PostgreSQL: v6.2 On-premise	v6.3 hosted	Oracle Linux v8 to Oracle Linux v8.10
Oracle: v4.3 On-premise v5.2 On-premise	v6.3 hosted	Migrating from Oracle to PostgresQL. v6.3 supports PostgreSQL only.

Prerequisites

Before Illumina can proceed with the upgrade, complete the following prerequisite steps.

1. Provision the New Instance

2. Verify User Accounts Email Addresses

3. Install and Run the Pre-Validation Script on the Source Server

4. Back Up the Current Database and Clarity LIMS

Provision the New Instance

Illumina provisions an instance installed with the latest qualified Oracle Linux version in the cloud.

Upgrades are only supported from Clarity LIMS versions 4.2, 4.3, 5.0, 5.1, 5.2, 6.0, 6.1 and 6.2 (on-premise).

• Custom configurations: If you have made any additional configurations that are not part of the Clarity LIMS preinstallation requirements, apply these configurations to the new instance.

• Passwords: Configure all passwords to be same as the existing instance. After you have verified the new instance, you can change passwords as needed.

Verify User Accounts Email Addresses

Make sure that all user accounts have email addresses associated with them. User passwords must be reset after the upgrade is complete.

Install and Run the Pre-Validation Script on the Source Server

To assist with validating the system before an upgrade, install the UpgradePreValidation RPM on the source server.

• This RPM is installed temporarily, and provides tools to help check the system before an upgrade.

• If validation is successful, you can remove this RPM and proceed with the upgrade.

1. Install the UpgradePreValidation RPM. Make sure you have the correct repo enabled.

   • On the source server, as the root user, run the following command:

     yum --enablerepo=GLS_Clarity63 install ClarityLIMS-UpgradePreValidation

2. [Optional] Set up Secret Utility.

   • If ClarityLIMS-SecretUtil was installed previously, run the following command to set up Secret Utility as the glsjboss user:

     ./opt/gls/clarity/config/pending/05_configure_claritylims_secretutil.sh

     NOTE: Using a vault is the safer way of storing application secrets. If using a vault is not possible, the configuration script supports file-based storage.

     For more information on the prompts, see Configuration Script section of Guide to Secret Management.
3. Run the validation script as follows.

   1. Make sure that the Clarity LIMS server is running.

   2. As the root user, run the following command:

      bash /opt/gls/ClarityUpgradeValidation/bin/validate.sh

   3. Review the output of the script to determine if you can proceed with the upgrade. If the script outlines any issues with the potential upgrade, review the generated log files and contact the Illumina Support team for further assistance.

4. Remove the PreValidation RPM.

   Remove the PreValidation RPM only after you confirm that you can upgrade. If you are unsure, consult the Illumina Support team.

   • As the root user, run the following command:

     yum remove ClarityLIMS-UpgradePreValidation

Back Up the Current Database and Clarity LIMS

Archive the backup in case a rollback is required.

Before performing the backup, stop Clarity LIMS. The following command stops all Clarity LIMS components, including Automation Worker and integration services.

1. Stop Clarity LIMS:

   • On the command-line interface, run the following command as the root user:

     /opt/gls/clarity/bin/run_clarity.sh stop 

2. Back up Postgresql database:

   On the PostgreSQL server, best practice recommends backing up the database using the pg_dump utility.

   The following example assumes the following:

   • The database server and the application server are on the same server.

   • The pg_dump utility is accessible to the glsjboss user.

     Example

     The Postgres DBA uses the following commands to create a database backup in the glsjboss home directory. Substitute the variables as appropriate for the specific environment.

     • As the glsjboss user:

       cd ~glsjboss
       mkdir -p backups/database
       pg_dump -U <database_user> -O -b -Ft <database_name> -f ~glsjboss/backups/database/clarity-old_version-`date +%Y%m%d%H%M`.tar

3. Make sure that the following items, and any other files and configurations, are backed up safely:

   • crontab -l

   • custom scripts

   • OS configuration files

   • firewall rules

   • network configuration

   • etc.

   If there are custom changes to any application configurations (to increase performance, security, etc.), restore/configure these items manually later by referencing the backup.

   We recommend that you back up the items into a single zip file and transfer them to the new Cloud instance.

   Directories

   /opt/gls/clarity/users/glsftp or /home/glsftp (Clarity LIMS file store location)

   /opt/gls/clarity/customextensions

   /opt/gls/clarity/glscontents

   Additional configurations:

   rpm -qa | grep "BaseSpace\|Clarity" > clarityrpms.txt

Illumina will assists with the deployment of hosted Clarity LIMS.