This section provides instructions for upgrading existing cloud hosted Clarity LIMS deployments to on premise deployments. For assistance with upgrade steps, contact the Clarity LIMS Support team.
Last updated
Was this helpful?
This document provides details on the steps required to upgrade an existing Clarity LIMS to RedHat Enterprise Linux/Oracle Linux compatible Clarity LIMS v6.2.
For installation requirements and Oracle Linux compatibility, see Technical Requirements.
The following table shows the applicable migration paths.
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
v6.2 On-premise
Changing environment from Cloud to On-premise
Before Illumina can proceed with the upgrade, complete the following prerequisite steps.
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.
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.
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.
Install the UpgradePreValidation RPM. Make sure you have the correct repo enabled.
On the source server, as the root user, run the following command:
[Optional] Set up Secret Utility.
If ClarityLIMS-SecretUtil was installed previously, run the following command to set up Secret Utility as the glsjboss user:
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.
Run the validation script as follows.
Make sure that the Clarity LIMS server is running.
As the root user, run the following command:
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.
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:
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.
Stop Clarity LIMS:
On the command-line interface, run the following command as the root user:
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:
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
Additional configurations:
rpm -qa | grep "BaseSpace\|Clarity" > clarityrpms.txt
Make sure that the repository file exists in the following location:
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.
Configure and validate the new system, following the procedure outlined in the Installation Procedure
When prompted for user passwords, enter the passwords used in the previous instance.
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 named lablink is created with the same database user as Clarity LIMS database.
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:
Run the pending initialization script.
As the glsjboss user, run the following command:
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
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 Clarity LIMS Support team for assistance in performing the migration from Oracle to PostgreSQL.
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>"'
Restore the database exported from the previous instance.
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.8, 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.
Copy the SSL certificate files to the following location (create the directory if it does not exist):
/etc/httpd/sslcertificate
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
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.
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
This step is only required if the passwords for glsftp and / or apiuser have changed.
To update the application configuration, complete the following steps:
Update glsftp password.
Update apiuser password.
Update database connection details.
For details, see 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:
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.
On the command-line interface, run the following commands as the root user:
Make sure that ElasticSearch is running:
When ElasticSearch service is running, remove the ElasticSearch indexes:
Restart Clarity LIMS:
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.
Log in to BaseSpace Clarity LIMS via https://<FQDN>/clarity and perform a basic search.
Check that search results are returned.
If no search results are returned, try again later as the search indexes are still building.
Run a sample through a QC protocol step. Create a temporary workflow if necessary.
Make sure that the automation executes successfully and the log files are accessible.
Open a browser window and access https://<FQDN>/api/v2/projects.
Log in with api user credentials.
Check that all projects are returned in the response.
Open a browser window and access https://<FQDN>/lablink/.
Log in with administrator credentials.
On the Projects page, make sure that all data are properly displayed.
To make sure that the service is running properly, you must initiate an actual sequencing run on the instrument.
The command hostname -f must resolve to the fully qualified domain name (FQDN) of the server. For details, see the section of Pre-Installation Requirements.
For more information on the prompts, see section of Guide to Secret Management.