Hosted to On Premise Upgrade Procedures

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

From Versions 4.2 / 4.3 / 5.0 / 5.1 / 5.2 / 5.3 / 5.4 / 6.0 / 6.1 /6.2 to 6.3

This document provides details on the steps required to upgrade an existing Clarity LIMS to RedHat Enterprise Linux/Oracle Linux compatible Clarity LIMS v6.3.

For installation requirements and Oracle Linux compatibility, see Technical Requirements.

Migration Paths

The following table shows the applicable migration paths.

From	To	Notes
v4.2 Hosted v4.3 Hosted v5.0 Hosted v5.1 Hosted v5.2 Hosted v5.3 Hosted v5.4 Hosted v6.0 Hosted v6.1 Hosted v6.2 Hosted	v6.3 On-premise	Changing environment from Hosted to On-premise

Prerequisites

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

1. Provision the New Instance

2. Configure the New Instance

3. Verify User Accounts Email Addresses

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

5. Back Up the Current Database and Clarity LIMS

Provision the New Instance

We recommend you provision an instance with similar or higher specifications to the current Clarity LIMS instance.

Note the following:

• Your system must meet the requirements listed in Technical Requirements.

• All standard operating system (OS) security updates must have been applied.

• Upgrades are only supported from Clarity LIMS v4.2/4.3/5.0/5.1/5.2/5.3/5.4/6.0/6.1/6.2.

• The command hostname -f must resolve to the fully qualified domain name (FQDN) of the server. For details, see the Confirm Hostname Resolution section of Pre-installation Requirements.

Before installing Clarity LIMS on the new instance, make sure that the instance has the same fully-qualified domain name (QFDN) as the existing Production instance. If it is not possible to have the same QFDN, contact the Illumina Support team.

Configure the New Instance

To configure the new instance, follow the instructions provided in the Pre-installation Requirements and see also Technical Overview.

• Custom configurations: If you have made any additional configurations that are not part of the Clarity LIMS pre-installation 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. Users must reset their passwords 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 instance.

   Directories

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

   /opt/gls/clarity/customextensions

   /opt/gls/clarity/glscontents

   /etc/httpd/conf.d

   /etc/httpd/sslcertificate

   Files

   .pgpass

   /opt/gls/pgsql/9.x/pg_hba.conf

   /opt/gls/pgsql/9.x/postgresql.conf

   /opt/gls/pgsql/12.x/pg_hba.conf

   /opt/gls/pgsql/12.x/postgresql.conf

   Additional configurations:

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

Upgrade steps

1. Install Latest Clarity LIMS on New Instance

2. Install and Configure LabLink 2.5

3. Restore Backup Onto the New Instance

4. [Optional] Change the Clarity LIMS Hostname

5. [Optional] Update Application Configuration

6. Perform Application Migration

7. [Optional] Install NGS, Illumina Preset Protocols (IPP), and Sequencing RPMs

8. Delete ElasticSearch Indices and Restart Clarity LIMS on the New Instance

Install Latest Clarity LIMS on New Instance

1. Make sure that the repository file exists in the following location:

   /etc/yum.repos.d/

2. As the root user, install the RPMs required on the new instance by referencing the content of clarityrpms.txt.

   • If you are upgrading from Clarity LIMS v4.x, some RPMs (eg, Server RPM) are now included under other RPMs.

   • Install any other required RPMs (eg, Python packages) which are not part of the Clarity LIMS setup.

   • Do not install NGS, Illumina Preset Protocols (IPP), and Sequencing RPMs during this step. You install these RPMs later in the installation process.

3. Configure and validate the new system, following the procedure outlined in the

   When prompted for user passwords, enter the passwords used in the previous instance.

4. Stop Clarity LIMS. To do so, on the command-line interface, run the following command as the root user:

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

The following steps are only required if you are restoring from a previous instance. If you are installing on a testing environment, proceed to Verify the New Instance section.

Install and Configure LabLink 2.5

LabLink v2.5 is compatible with Clarity LIMS v6.3.

If upgrading from Clarity LIMS v4.x, Illumina migrates your LabLink-related data with the following exceptions:

• sample submission templates

• customized UI CSS

• lablink property table configurations

Before completing the following steps, make sure that a database named lablink is created with the same database user as Clarity LIMS database.

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

   • On the new instance, as the root user, run the following command:

     yum --enablerepo=GLS_Clarity63 install ClarityLIMS-LabLink

2. Run the pending initialization script.

   • As the glsjboss user, run the following command:

     bash /opt/gls/clarity/config/pending/60_initialize_lablink.sh

3. The script prompts for a Google reCAPTCHA URL, site key, and secret key.

   • Google reCAPTCHA URL: https://www.google.com/recaptcha/

   • Google reCAPTCHA site key and secret key: View these keys from the Google reCAPTCHA Admin Console, under Settings.

     NOTE: If you prefer not to use reCAPTCHA, leave the site-key and secret-key fields blank when running the configuration script. LabLink does not display the reCAPTCHA when these fields are left blank. You can also use your own reCAPTCHA accounts when configuring LabLink.

   • To reconfigure LabLink (without initializing the database), run the following command as the glsjboss user:

     bash /opt/gls/clarity/config/configure_lablink.sh

Restore Backup Onto the New Instance

1. Extract the backup zip file into a suitable location, e.g. /tmp/restore.

   NOTE: If using Oracle database, skip the following steps 2 and 3. Contact the Illumina Support team for assistance in performing the migration from Oracle to PostgreSQL.

2. If using PostgreSQL database, the DBA imports the database dump into the new database instance. Dropping and recreating the database might be necessary. If you need to do this, use the following command:

   dropdb -U postgres <OL8DB>

   createdb -U postgres <OL8DB>

   psql -U postgres -d <OL8DB> -c 'ALTER DATABASE "<OL8DB>" OWNER TO "<OL8User>"'

3. Restore the database exported from the previous instance.

4. Extract and restore the following directories to the same directory on the new instance:

   • Clarity LIMS file store: /opt/gls/clarity/users/glsftp or /home/glsftp

   • /opt/gls/clarity/customextensions

   • /opt/gls/clarity/glscontents

   • /etc/httpd/conf.d

   NOTE: As of RedHat Enterprise Linux/Oracle Linux 8.10, Apache v2.4 is installed. There are several configuration changes in this version. You can use the new configuration, or merge your previous configuration file cautiously to the new configuration file. For details on the changes, refer to: httpd.apache.org.

5. Copy the SSL certificate files to the following location (create the directory if it does not exist):

   /etc/httpd/sslcertificate

6. To configure the certificates, run the following command on the command-line interface, as the root user:

   /opt/gls/clarity/config/installCertificates.sh

   For more information, see Install a Purchased SSL/TLS Certificate.

7. Restore files and configurations.

   • Copy any custom scripts into their folder locations.

   • For PostgreSQL database, copy / merge the database configuration file, i.e. pg_hba.conf and postgresql.conf.

   • Restore crontab from file.

   • Copy / Merge any additional application configurations.

[Optional] Change the Clarity LIMS Hostname

This step is required only if the new instance hostname is different from the old instance hostname.

For details, see Change the Clarity LIMS Hostname.

[Optional] Update Application Configuration

This step is only required if the passwords for glsftp and / or apiuser have changed.

To update the application configuration, complete the following steps:

1. Update glsftp password.

2. Update apiuser password.

3. Update database connection details.

For details, see Update Server Passwords and Database Connection Details.

Perform Application Migration

In this step, the clarity-migrator tool is used to perform the changes required to make the database compatible with the new Clarity LIMS version.

On the command-line interface, run the following commands as the glsjboss user:

cd /opt/gls/clarity/config/
./migrate_claritylims_database.sh

[Optional] Install NGS, Illumina Preset Protocols (IPP), and Sequencing RPMs

This step is required only if the RPMs have been installed on the existing Clarity LIMS instance.

• Install the latest NGS, IPP, and Sequencing RPMs compatible with the new LIMS version, as listed in clarityrpms.txt.

All existing workflows, protocols, steps, and master steps are restored during the restoration process. After installing the NGS and IPP RPMs, you do not need to install the workflows again.

• If the automation/External Program Plugin (EPP) scripts installed on the new instance are of a later version (e.g. /opt/gls/clarity/extensions/ngs-common/v5/EPP ), to your old instance (e.g. /opt/gls/clarity/extensions/ngs-common/v4/EPP), you must manually update the script location in your automation / EPP command lines. You can do update the script location in the Clarity LIMS interface or the Operations interface.

• If you intend to install NovaSeq API-based integration, NextSeq integration, or MiSeq integration, use the latest package to ensure OS compatibility.

Delete ElasticSearch Indices and Restart Clarity LIMS on the New Instance

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

• Make sure that ElasticSearch is running:

  service elasticsearch start

• When ElasticSearch service is running, remove the ElasticSearch indexes:

  for indexname in `curl -s 'http://localhost:9200/_cat/indices?h=index'`; do echo "Delete index: $indexname"; curl -XDELETE "http://localhost:9200/$indexname"; echo ""; done

• Restart Clarity LIMS:

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

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

Verify the New Instance

The following verification steps are the minimum required to confirm that the various services are up and running properly.

To conduct a thorough verification, perform your verification steps or daily routine on the new Clarity LIMS instance.

ElasticSearch, Search Indexer, and RabbitMQ

1. Log in to BaseSpace Clarity LIMS via https://<FQDN>/clarity and perform a basic search.

2. Check that search results are returned.

3. If no search results are returned, try again later as the search indexes are still building.

Tomcat, Apache, Automation Worker

1. Run a sample through a QC protocol step. Create a temporary workflow if necessary.

2. Make sure that the automation executes successfully and the log files are accessible.

3. Open a browser window and access https://<FQDN>/api/v2/projects.

4. Log in with api user credentials.

5. Check that all projects are returned in the response.

LabLink

1. Open a browser window and access https://<FQDN>/lablink/.

2. Log in with administrator credentials.

3. On the Projects page, make sure that all data are properly displayed.

[Optional] Sequencing Service

To make sure that the service is running properly, you must initiate an actual sequencing run on the instrument.