Upgrade Procedure for On Premise to On Premise Deployments

From Versions 4.3 and 5.2 (PostgreSQL) to 6.0

This document provides details on the steps required to upgrade from Clarity LIMS v4.3 or v5.2 to Clarity LIMS v6.0.

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

The following table shows the applicable migration paths.

From

To

PostgreSQL:

v4.3 On-premise

v5.2 On-premise

v6.0 On-premise
• The system meets the requirements listed in the Clarity LIMS Technical Requirements.
• All standard operating system (OS) security updates have been applied.
• The command hostname -f resolves to the fully qualified domain name (FQDN) of the server. For details, refer to the Verify Hostname Resolution section of Pre-Installation Requirements.
• All user accounts have email addresses associated with them. Users must reset their passwords after the upgrade is done.

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

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, refer to Guide to Secret Management and refer to the Configuration Script section.
3. Run the validation script.
a. Make sure that your Clarity LIMS server is running.
b. As the root user, run the following command:

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

c. 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 Clarity LIMS 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 Clarity LIMS LIMS Support team.

• As the root user, run the following command:

yum remove ClarityLIMS-UpgradePreValidation

Upgrading the Clarity LIMS Server

The following steps are required to update the Clarity LIMS server.

All instances of Clarity LIMS must have a purchased SSL Certificate installed before installation or upgrade. For instructions on creating the necessary Certificate Signing Request to send to your SSL Certificate vendor, and installing the certificate files received from your vendor into Clarity LIMS, refer to Install a Purchased SSL/TLS Certificate.

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

1. As the glsjboss user, run the following command. Substitute the variables as appropriate for your specific environment.

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

2. Make a note of any remote automation workers. Let these automation workers complete their current commands.

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

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

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

• If a service is already stopped, it is ignored.
• If a service fails to stop, the script exits. No further services are stopped.

In rare circumstances, the previous commands might fail to stop JBoss and/or Tomcat. In this scenario, use the following kill commands to stop these components.

JBoss

1. Check if you must kill the JBoss application:

pgrep jboss

2. As the glsjboss user, kill the JBoss application:

/etc/init.d/jboss kill

Tomcat

1. Check if you must kill the Tomcat application:

pgrep jsvc

2. As the root user, kill the Tomcat processes:

pkill jsvc

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

Assumptions of the following example:

• The database server and the application server are on the same server.
• The pg_dump utility is accessible to the glsjboss user.

Example:

Your Postgres DBA can use the following commands to create a database backup in the glsjboss home directory. Substitute the variables as appropriate for your 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

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/

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

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

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

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

This script analyzes the system and lists any required configuration steps.

3. Carefully apply the instructions provided in the output of the scripts. For example, as root, run the following 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

4. If your database server is standalone or remote, update the /opt/gls/clarity/tomcat/current/lib/activity-management-ui-config.groovy file with the following code snippet. Substitute the Remote DB IP and Remote DB Port placeholders with the information for your server.

hibernate {

isis {

template {

url="jdbc:postgresql://<Remote DB IP>:<Remote DB Port>/{0}"

}

}

}

If you do not update the script, log and database connection errors can occur.

5. Check that all scripts have been run. As the glsjboss user, run any remaining scripts:

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

LabLink v2.2 is compatible with Clarity LIMS v6.0. If you are running an older version of LabLink, you must upgrade to the latest version.

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

• Sample submission templates
• Customized UI CSS
• LabLink property table configurations

Before installing LabLink v2.2, 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_Clarity6 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.

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

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

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

If you are running an older version of LabLink, upgrade to the latest version as follows.

1. Upgrade the LabLink RPM (make sure that you have the correct repo enabled).
2. On the instance, as the root user, run the following command:

yum --enablerepo=GLS_Clarity6 update ClarityLIMS-LabLink

Upgrade your PostgreSQL database server to v12.7. Consult a DBA to perform the upgrade.

Use the run_clarity.sh script to start all services (Elasticsearch, RabbitMQ, Search Indexing, Tomcat, httpd/Apache proxy, AI) in the required order, with one command.

• As the root user:

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

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

Start the Sequencing services (if applicable).

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

Determine which components are running.

1. As glsjboss, or root user, run the following commands.

Tomcat:

ps -ef | grep jsvc

Automation Workers:

ps -ef | grep automat

Sequencing services:

ps -ef | grep seq

2. Note which components are running.
3. If applicable, restart Remote Automation Workers.
• If remote automation workers were reported as running, manually restart each one from its local machine.
1. Log in to Clarity LIMS.
2. Using your own acceptance criteria, make sure that Clarity LIMS is operating as you would expect.