Upgrade Procedure for Cloud to On Premise Deployments

The following table shows the applicable migration paths.

From	To	Notes
v4.2 Cloud v4.3 Cloud v5.0 Cloud v5.1 Cloud v5.2 Cloud v5.3 Cloud v5.4 Cloud v6.0 Cloud v6.1 Cloud	v.6.2 On-premise	Changing environment from Illumina Cloud hosted to On-premise.

•

The system must meet the requirements listed in the Technical Overview.

•

All standard 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.

•

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

To configure the new instance, follow the instructions provided in the Clarity LIMS Pre-Installation Requirements. Refer to the 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, remove this RPM and proceed with the upgrade.

1.

Install the UpgradePreValidation RPM (make sure that the correct repo is enabled).

•

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

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 the 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 Pre-Validation RPM.

Remove the Pre-Validation RPM only after you confirm that you can upgrade. If you are unsure, consult the Clarity 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 example provided makes the following assumptions:

•

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, and so on), 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) that 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.2).

•

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.4 is compatible with Clarity LIMS v6.2.

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 with the name of 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_Clarity62 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 might be necessary. If this is needed, use the following command:

dropdb -U postgres <OLOS8DB>

createdb -U postgres <OLOS8DB>

psql -U postgres -d <OLOS8DB> -c 'ALTER DATABASE "<OLOS8DB>" OWNER TO "<OLOS8User>"'

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) than 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:

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

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.

1.

ElasticSearch, Search Indexer, and RabbitMQ

a.

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

b.

Check that search results are returned.

c.

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

2.

Tomcat, Apache, Automation Worker

a.

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

b.

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

c.

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

d.

Log in with api user credentials.

e.

Check that all projects are returned in the response.

3.

LabLink

a.

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

b.

Log in with administrator credentials.

c.

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

4.

[Optional]Sequencing Service

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