Upgrade Procedure for On Premise to On Premise Deployments

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 the Clarity LIMS Technical Requirements

•

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

•

Upgrades are only supported from Clarity LIMS versions 4.2, 5.0, and 5.1 and 4.3 and 5.2 (Oracle).

•

The command hostname -f must resolve to the fully qualified domain name (FQDN) of the server. For details, refer to the Verify Hostname Resolution section of Pre-Installation Requirements.

To configure the new instance, follow the instructions provided in the Clarity LIMS Pre-Installation Requirements and refer to 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.

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

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:

•

For more information on the prompts, refer to the Configuration Script section of Guide to Secret Management.

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

Archive the backup in case a rollback is required.

Before performing the backup, stop Clarity LIMS.

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

This command stops all Clarity LIMS components, including Automation Worker and integration services.

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

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

Additional configurations:

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

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 Installation Procedure (Clarity LIMS v6.0)

•

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

LabLink v2.2 is compatible with Clarity LIMS v6.0.

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

•

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

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

1.

Extract the backup zip file into a suitable location (eg, /tmp/restore).

2.

If using PostgreSQL database, the DBA imports the database dump into the new database instance. Dropping and recreating the database can be necessary. If needed, use the following command to do so:

dropdb -U postgres "CentOS7DB"

createdb -U postgres "CentOS7DB"

psql -U postgres -d "CentOS7DB" -c 'ALTER DATABASE "CentOS7DB" OWNER TO "CentOS7User"'

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/custom/extensions

•

/opt/gls/clarity/glscontents

•

/etc/httpd/conf.d

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, refer to Install a Purchased SSL/TLS Certificate.

7.

Restore files and configurations.

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

For details, refer to Change the Clarity LIMS Hostname

This step is required only 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, refer to Update Server Passwords and Database Connection Details.

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

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 Clarity 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 (eg, /opt/gls/cla/opt/gls/clarity/extensions/ngs-common/v5/EPP)d to your old instance (eg, /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.

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:

curl _XDELETE 'http://localhost:9200/_all'

•

Restart Clarity LIMS:

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

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