On Premise to On Premise In-place Upgrade Procedures

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

From Clarity LIMS Version 6.2 to 6.3

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

For installation requirements, see Technical Requirements.

If you have questions about the upgrade procedure, contact the Illumina Support team.

Migration Paths

The following table shows the applicable migration paths.

From	To	Notes
PostgreSQL: v6.2 On-premise	v6.3 On-premise	-

Prerequisites

Before proceeding with the in-place upgrade from Clarity LIMS v6.2 to v6.3, note on the following:

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

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

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

• Make sure that all standard OS security updates have been applied.

• Make sure that all user accounts have email addresses associated with them. Users must reset their passwords after the upgrade.

Upgrade Pre-validation

To assist with validating the system before an upgrade, install the UpgradePreValidation RPM on the existing 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.

   • 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

Upgrade steps

1. Shut Down Clarity LIMS Components

2. Backup the Database and Clarity LIMS

3. Upgrade Clarity LIMS Components

4. Install or Upgrade LabLink

5. #Reinstall-Clarity-LIMS-Integration:Sequencer-API-RPM

6. Upgrade PostgreSQL database server

7. Start the Clarity LIMS services

8. [Optional] Upgrade Clarity LIMS Integrations

9. Check Clarity LIMS Components

10. Validate the Installation

Shut Down Clarity LIMS Components

1. Determine if any of the remote automation workers (AI nodes) are running.

   • As the glsjboss user, run the following command:

     Substitute the variables as appropriate for the specific environment.

     Copy

     java -jar /opt/gls/clarity/tools/ai-monitor/ai-monitor.jar -u <apiuser> -p <password> -i https://<apihost>/api/ -n

   • Make a note of any remote automation workers, and let them complete their current commands.

     NOTE: As of Clarity LIMS v5, the term AI node has been replaced with automation worker.

2. Stop any and all integration services.

   • Find all the integration services and stop them, as described in the integration documentation.

3. Shut down the Clarity LIMS services.

   • As the root user, run the following command:

     Copy

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

     • If a service is already stopped, it will be ignored.

     • If any service fails to stop, the script will exit and no further services will be stopped.

Any Clarity LIMS components still running should be shut down. Use the following commands to force stop these components if the previous commands did not lead to Tomcat stopping.

Tomcat

1. Check if there is a need to force stop the tomcat application:

   pgrep jsvc

2. As the root user, force stop the tomcat processes:

   pkill jsvc

Backup the Database and Clarity LIMS

1. 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> -b -Ft <database_name> -f ~glsjboss/backups/database/clarity-old_version-`date +%Y%m%d%H%M`.tar

2. Backup Clarity LIMS

   • On the Clarity LIMS server, back up the contents of the folder /opt/gls/clarity/glscontents/.

   • As the glsjboss or root user run the following commands:

     cd ~glsjboss
     mkdir -p backups/clarity
     tar czf ~glsjboss/backups/clarity/glscontents-old_version-`date +%Y%m%d$H$M`.tar.gz /opt/gls/clarity/glscontents/

Upgrade Clarity LIMS Components

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

   yum --enablerepo=GLS_Clarity63 update "ClarityLIMS-App"

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

   /opt/gls/clarity/config/configuration_test.sh

   • This script analyzes the system and lists any required configuration steps. Make sure to carefully apply the instructions provided in the output of the scripts.

     Example:

     As root run the sequence
     su - glsjboss -c /opt/gls/clarity/config/pending/27_update_claritylims_platform.sh
     su - glsjboss -c /opt/gls/clarity/config/pending/28_update_claritylims_tenant.sh
     /opt/gls/clarity/config/pending/32_root_configure_rabbitmq.sh
     /opt/gls/clarity/config/pending/33_root_configure_elasticsearch.sh
     /opt/gls/clarity/config/pending/40_root_install_proxy.sh

   NOTE: Update /opt/gls/clarity/tomcat/current/lib/activity-management-ui-config.groovy If your database server is standalone or remote. Use the following code snippet:

   multiTenantDataSource {
     urlTemplate="jdbc:postgresql://<Replace me: Remote DB IP>:<Replace me: Remote DB Port>/{0}"
     ... other properties ...
   }
   
   ... other properties ...
   
   dataSource {
     ... other properties ...
     url="jdbc:postgresql://<Replace me: Remote DB IP>:<Replace me: Remote DB Port>/{tenantLookupDB}"
   }    

3. Check that all scripts have been run. As glsjboss user run any that are remaining:

   su - glsjboss -c /opt/gls/clarity/config/configuration_test.sh

Install or Upgrade LabLink

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

Install LabLink 2.5

NOTE: This step is only required if installing Lablink for the first time.

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

Upgrade LabLink 2.5

Lablink must be upgraded to the latest version if there is an order version installed.

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

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

yum --enablerepo=GLS_Clarity63 update ClarityLIMS-LabLink

Reinstall Clarity LIMS Integration: Sequencer API RPM

NOTE: This step is only required if BaseSpaceLIMS-sequencer-api RPM is installed on the server. The RPM needs to be re-installed to resolve a known issue for version 6.3.

Run the following command to identify if the Sequencer API RPM is installed:

yum list installed | grep BaseSpaceLIMS-sequencer-api

Use the following command to reinstall the Sequencer API RPM. Make sure that the same version is being reinstalled.

yum --enablerepo=GLS_Clarity63 reinstall BaseSpaceLIMS-sequencer-api

Upgrade PostgreSQL database server

Upgrade your PostgreSQL database server to v15.6. Consult a DBA to perform the upgrade.

Start the Clarity LIMS services

Use the run_clarity.sh script to start all services in the required order as follow:

• Elasticsearch

• RabbitMQ

• Search Indexing

• Tomcat

• httpd/Apache proxy

• AI in the required order

As the root user, run the following command:

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

• After the script has completed, all Clarity LIMS services should be ready for use.

[Optional] Upgrade Clarity LIMS Integrations

NOTE: This step is required only if Integration is needed.

Start the integration services.

• Find all the integration services and stop them, as described in the integration documentation.

Check Clarity LIMS Components

1. Determine the components that are running.

   • As the glsjboss or root user, run the following command:

     • Tomcat:

       ps -ef | grep jsvc

     • Automation workers:

       ps -ef | grep automat

     • Sequencing services:

       ps -ef | grep seq

   Take note of the component that is running.

2. [Optional] Restart remote automation workers.

   • Manually restart each of the remote automation worker from its local machine.

Validate the Installation

1. Log in to Clarity LIMS.

2. Make sure that Clarity LIMS is operating by performing your own validation steps.