1 of 8

On-Premise Deployments

Pre-installation Requirements

Before installing Clarity LIMS, you must purchase hardware and software that meet the minimum requirements (see ). Following those purchases there are several components that you must organize, install, or configure.

The following sections discuss these components, and how to install and configure them. These sections apply to on-premise customers only. Before completing the steps described, make sure that the server has the minimum requirements. See for details.

Before the Illumina support team can install Clarity LIMS, the items listed above must be set up and configured as described in this document. Confirm the completion of this work with the support team.

Purchase SSL / TLS Certificate(s)

All instances of Clarity LIMS must have a purchased SSL / TLS certificate installed.

Certificate Authorities will no longer issue SSL / TLS certificates for internal server names. As a result, to obtain a certificate you must have a valid, public DNS entry for your server.

Before installing or upgrading Clarity LIMS, do the following:

Purchase an SSL / TLS certificate.
Save the certificate files on the server on which the Clarity LIMS server is installed.
Provide the Illumina Support team with the private key and password for the SSL / TLS certificate.

For instructions on obtaining a certificate, see .

Check SELinux Mode

Security-Enhanced Linux (SELinux) is not supported for use with Clarity LIMS. Make sure that SELinux is set to either permissive or disabled mode.

For instructions, see the following sections of the Red Hat documentation:

5.4.1.2 Permissive Mode
5.4.2 Disabling SELinux

You can find additional documentation on users at /opt/gls/clarity/documentation/users/

Set Up Root Access Server

Clarity LIMS is installed using industry standard RPM packaging. The Illumina support team requires root credentials to the server during the installation process.

The following sections discuss the system user accounts that the support team sets up during the installation process. It is important that you do not change these system users.

The production server must be configured in US locale.

Server-based User Accounts

During initial installation, the RPMs create the following server-based user accounts in a common group named claritylims.

glsjboss: This user account is used for setting up and starting the Tomcat application server.
glsai: This user account is used for setting up and starting the automation worker service.
glsftp: This user account is configured to allow SFTP access and to redirect the home directory to the data storage area. The glsftp user account is used by BaseSpace Clarity LIMS clients to import and export files from the LIMS file server.

NOTE: Do not create these user accounts manually.

During initial installation of the elastic search subsystem, the RPM creates the following server-based user account in the elasticsearch group.

elasticsearch: This user account is used for setting up and starting the elastic search subsystem used by the LIMS search mechanism.

NOTE: Do not create these user accounts manually.

During initial installation of the RabbitMQ subsystem, the RPM creates the following server-based user account in the rabbitmq group.

rabbitmq: This user account is used for setting up and starting the RabbitMQ subsystem used by the search indexing mechanism.

NOTE: Do not create these user accounts manually.

Setting User Account Password

During the installation process, no default passwords are created for the glsjboss, glsai, and glsftp user accounts.

Passwords must be set for these accounts.
During execution of the Clarity LIMS installation script, you are prompted for the password of the glsftp user. Use the same password you set at the operating system level for this user.

NOTE: You can find additional documentation on users at /opt/gls/clarity/documentation/users/

Allow SSH Password-based Authentication

To enable SSH Password Authentication, add the following configuration to the /etc/ssh/sshd_config file:

Install and Configure the Database

After installing a supported database, Clarity LIMS requires certain changes to the default database configuration.

Additional tablespace names and user profiles may be needed, depending on the configuration of your system.

For more information or for assistance with your database configuration, contact the Illumina Support team.

Configure PostgreSQL Database for Use with Clarity LIMS

On your database server, create a Clarity LIMS user. The Clarity LIMS user must have either full rights and permissions, or the ones defined by this command:
CREATE ROLE clarity WITH NOSUPERUSER CREATEDB NOCREATEROLE LOGIN
NOTE: The Clarity LIMS user must use only the public schema. Clarity LIMS does not support other schemas.
Create one database named ClarityDB and another named ClarityTenantLookup. Make sure that both databases are set up to receive remote connections from the Clarity LIMS application server.
Restart PostgreSQL
Confirm the completion of these items with the Illumina Support team, and provide the following information:
- The database user name and password for both databases.
- The hostname/IP address of the database server.
- The PostgreSQL port number.

Set Up Database Maintenance Tasks

To achieve optimum performance, we recommend you perform the following database maintenance tasks, using the appropriate tools and commands.

PostgreSQL: Routinely vacuum the database.
For instructions, refer to the PostgreSQL documentation.

IPv4 Support

Clarity LIMS supports only IPv4.

NOTE: Clarity LIMS will not work with IPv6.

Confirm Hostname Resolution

To access the Clarity LIMS server via DNS, make sure that the following apply:

The server local host file /etc/hosts does not contain an entry for that hostname bound to its loopback address.
Any hostname entries correspond to their entries in DNS.
The command hostname -f must return the fully-qualified domain name of the server.

For client systems:

Users should use the fully-qualified domain name (FQDN) when logging on to the system. Using the FQDN ensures persistence of the session ID.

Set the TimeZone (TZ) Environment Variable

Clarity LIMS requires the environment variable TZ be set on the Clarity LIMS server to your correct timezone. If the value is not configured, a default of GMT is configured by Clarity LIMS in the file /etc/profile.d/clarity.sh.

This file might update on upgrade. Any changes must be manually applied across upgrades.

Configure TCP/IP Settings

To allow proper system communication, the following ports on the Clarity LIMS server must be accessible by the LIMS clients:

TCP/IP Port 22 (SFTP) for file transfers between the client and server
TCP/IP Port 443 (HTTPS) for Apache proxy
TCP/IP Port 80 (HTTP) used to forward any unknown unsecured requests over SSL / TLS and port 443

The following ports are required on the local Clarity LIMS server:

TCP/IP Port 4369 for Epmd for RabbitMQ
TCP/IP Port 5432 for PostgreSQL database communications *
TCP/IP Port 9009 for Tomcat
TCP/IP Port 9200 for Elastic Search
TCP/IP Port 9300 for Elastic Search
TCP/IP Port 5672 for RabbitMQ
TCP/IP Port 15672 for RabbitMQ

The database ports are configurable and might be different in your organization.

Configure automation worker TCP/IP settings

Computers running an automation worker must be able to reach the Clarity LIMS server via the following ports:

TCP/IP Port 22 (SFTP) for file transfers between the client and server
TCP/IP Port 443 (HTTPS) for Apache proxy
TCP/IP Port 80 (HTTPS) used to forward any unknown, unsecured requests over SSL / TLS and port 443

Configure VPN Access for Hosted Systems

To facilitate instrument integrations, a site-to-site IPSEC VPN connection can be set up between your facility and the hosted instance.

There are two ports that must be opened: 4500/udp and 500/udp.

If a VPN is required, you must provide more detailed setup information to the Illumina Support team. Upon request, the Illumina Support team will provide the additional form required to do this.

Save any Apache Proxy Configuration

Clarity LIMS uses an Apache proxy and the Clarity LIMS installation process installs and configures it automatically. If the server already has an Apache proxy installed and configured, the installation process overwrites the current configuration. If that configuration is important, you must back it up before running the Clarity LIMS installation process. Any settings that are important to your organization must be reconfigured manually after an install or upgrade of Clarity LIMS.

Install and Configure HashiCorp Vault

In Clarity LIMS v6.0.0 and later, you can choose to install and configure a HashiCorp Vault to store Clarity LIMS-related passwords and secrets safely.

Install a Purchased SSL/TLS Certificate

This section explains how to install purchased SSL/TLS certificates into Clarity LIMS v5 and later.

Clarity LIMS can work with Named or WildCard certificates.

Typically, the process to install the certificates into Clarity LIMS is as follows:

Request a certificate from your IT organization, or purchase a certificate from a third-party SSL/TLS vendor.
Install the certificate using the script installCertificates.sh provided with Clarity LIMS. This script prompts for the required inputs and helps you to configure Clarity LIMS to use your SSL/TLS certificate.

Some IT organizations have preexisting certificates issued by an internal organization, typically referred to as an 'internal CA.' These internal CA certificates are not fully compatible with Java, and prevent the automation worker—and all integrations—from properly communicating with the Clarity LIMS server. Internal CA certificates are therefore not supported in Clarity LIMS.

Obtaining the Certificate

You will need your organization or the third-party SSL/TLS vendor to provide you with the following:

An Apache 2.4-compatible SSL/TLS Certificate
The Certificate private key
The corresponding certificate chain, properly prepared for Apache 2.4. This component may not be required, depending on the organization that signs your certificate.

Your IT organization might provide you with a WildCard certificate. Clarity LIMS can use WildCard certificates, as long as the Apache 2.4-compatible certificate, private key, and certificate chain files are provided.

If purchasing from a third-party vendor, make sure that the vendor provides you with an Apache 2.4-compatible bundle that includes the components listed above. To purchase from a vendor, refer to their documentation.

Private key password considerations

By default, a private key has a password associated with it. On startup, Apache requests a passphrase to access the private key. You can use either of the following methods to resolve this issue:

Method 1 — Place a passphrase file on the system and reference it in your clarity.conf file.

Create a passphrase file in a directory that has read, write, and execute permissions for only the root or apache user.
```
#! /bin/bash 
echo "privatekeypassword"
```
Edit the clarity.conf file. The clarity.conf file is in the /etc/httpd/conf.d directory.
Add the following line to your clarity.conf file, before the section:
```
SSLPassPhraseDialog exec:/path/to/passphrase-script 
```

Method 2: Removing passphrase from an OpenSSL key

Removing the passphrase from an OpenSSL key is a security risk. Only remove the passphrase if you know that this risk is acceptable.

Remove the password from an OpenSSL key using the following command:
Copy
```
% openssl rsa -in private.key -out private_nopassphrase.key     
```

Install SSL/TLS Certificates for Use with Clarity LIMS

Assumptions and Prerequisites

You have installed BaseSpace Clarity LIMS and run the 40_install_proxy.sh script.
You have OpenSSL (installed by default on the Clarity LIMS Linux server when you install Clarity LIMS). OpenSSL is used by the installCertificates.sh script.
You have the files listed in the following table (obtained from the process described previously) available on the Clarity LIMS server. In the example shown below, these files are located at /tmp/certs.

Install the signed SSL/TLS Certificates

On the Clarity LIMS server, as the root user, run the installCertificates.sh script:

[root@doclarity04 ~]# cd /opt/gls/clarity/config/
[root@doclarity04 config]# bash installCertificates.sh
Java KeyTool detected
    This script will prompt you to supply the required SSL Certificates for your ClarityLIMS server.
    These files include:
    - A private key file and signed Certificate file for use by apache.
    - Optionally, depending on the organization that signs your Certificate, you may receive a 'Chain' file.
Enter the full path to the SSL Private Key for your server:/tmp/certs/private.key
Enter the full path to the Apache Certificate for your server - This is the Certificate signed by the SSL Vendor or Certificate Authority:/tmp/certs/customer_domain.crt
Enter the full path to the SSL Vendor Chain file:/tmp/certs/intermediate.crt
INFO: Testing Apache
Syntax OK
Apache Proxy is ready

Configure Your HashiCorp Vault

The following steps use the HashiCorp Vault user interface (UI) to guide you through the configuration of your HashiCorp Vault instance.

These configurations are mandatory for on premise Clarity LIMS deployments. For hosted deployments, this configuration is completed by Illumina.

Detailed information and instructions for HashiCorp Vault are available on the HashiCorp website: www.hashicorp.com.

Pre-requisites

You are planning to install Clarity LIMS v6.0.0 and newer.
You have installed the latest version of either HashiCorp Vault Open Source or Enterprise.
You have read the Getting Started tutorials for Vault on the HashiCorp website and/or possess a basic knowledge of HashiCorp Vault.
You have system administrator permissions to perform the necessary operations to your HashiCorp Vault instance.
You have allowed the necessary port 443 from the Clarity LIMS instance to your HashiCorp Vault instance.
You have access to all the passwords required to be configured in your HashiCorp Vault instance.

Configuration

Enable a new KV Secret Engine

To enable a new KV Secret Engine, refer to the Versioned Key/Value Secrets Engine tutorial provided on the HashiCorp Vault website.

Configuring Secret Engine

The following table lists the secrets required for Clarity LIMS. To use the paths shown in the table, replace $host with your fully qualified domain name (FQDN).

When configuration is complete, these secrets are listed in the Vault user interface.

Authentication Methods

AppRole

AppRole is the recommended authentication method to use with the Clarity LIMS Secret Utility tool.

To enable the AppRole authentication method, refer to the AppRole Pull Authentication tutorial provided on the HashiCorp Vault website.
When AppRole is enabled, create an AppRole with the appropriate Access Control List (ACL) policy (see the following section).
Make a note of the Role ID and Secret ID. You need these IDs when configuring Secret Utility.

Secret Utility does not manage your Role ID and Secret ID for you (eg, renewing, revoking, and so on). It accepts the Role ID and Secret ID as-is, and attempts to authenticate with Vault.

Token

Alternatively, the Clarity LIMS Secret Utility tool also works with the token authentication method.

To learn more about tokens, see the Tokens documentation on the HashiCorp Vault website.

Secret Utility does not manage your tokens for you (eg, renewing, revoking, and so on). It accepts the token as-is, and attempts to authenticate with Vault.

Authentication ACL Policies

After enabling the AppRole authentication method, create ACL policies to access the Secret Engine.

IMPORTANT: Replace "claritylims" with your Secret Engine path.

ACL Policies

# For clarity instance to read from hashicorp vault
path "claritylims/data/+/clarity/*"
{
  capabilities = ["read"]
}
# For integration to write to hashicorp vault
path "claritylims/data/+/integration/*"
{
  capabilities = ["read","create","update"]
}
# For listing and deleting metadata of integration keys
path "claritylims/metadata/+/integration/*"{
  capabilities = ["list","delete"]
}
# For global values
path "claritylims/data/global/*"
{
   capabilities = ["read"]
}

You might need to update or create additional ACL policies for your System Administrator to rotate the credentials, when required.

To create the ACL policy, refer to the Vault Policies tutorial provided on the HashiCorp Vault website.

Verification

SSH into the Clarity LIMS instance.
After installing Clarity LIMS and configuring Secret Utility using the instructions provided in Guide to Secret Management, run the command to read an existing password/secret from HashiCorp Vault.

On Premise to On Premise 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 Versions 4.2 / 4.3 / 5.0 / 5.1 / 5.2 / 6.0 / 6.1 (PostgreSQL) and 4.3 / 5.2 (Oracle) to 6.3

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

The installation procedure includes provisioning and configuring the new instance, and installing and then verifying the new Clarity LIMS version.

For installation requirements, see .

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

Migration Paths

The following table shows the applicable migration paths.

From

Notes

Prerequisites

Before Illumina can proceed with the upgrade, complete the following prerequisite steps.

Provision the New Instance

We recommend you provision an instance with similar or higher specifications to the current Clarity LIMS instance.

Note the following:

All standard operating system (OS) security updates must have been applied.
Upgrades are only supported from Clarity LIMS v4.2/5.0/5.1/6.0/6.1, and v4.3/5.2.0 (Oracle).

Before installing Clarity LIMS on the new instance, make sure that the instance has the same FQDN as the existing production instance. If your new instance cannot have the same FQDN as the production instance, contact the Illumina Support team.

Configure the New Instance

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.

Verify User Accounts Email Addresses

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

Install and Run the Pre-Validation Script on the Source Server

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.
1. Make sure that the Clarity LIMS server is running.
2. As the root user, run the following command:
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.
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:

Back Up the Current Database and Clarity LIMS

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:
    Copy
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
/opt/gls/pgsql/12.x/pg_hba.conf
/opt/gls/pgsql/12.x/postgresql.conf
Additional configurations:
rpm -qa | grep "BaseSpace\|Clarity" > clarityrpms.txt

Upgrade steps

Install Latest Clarity LIMS on New Instance

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

Restore Backup Onto the New Instance

Restore backup must be carried out before LabLink v2.5 can be installed.

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:
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
Copy the SSL certificate files to the following location (create the directory if it does not exist):
To configure the certificates, run the following command on the command-line interface, as the root user:
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.

Install and Configure LabLink 2.5

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

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:

[Optional] Change the Clarity LIMS Hostname

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

[Optional] Update Application Configuration

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.

Perform Application Migration

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:

[Optional] Install NGS Illumina Preset Protocols (IPP), and Sequencing RPMs

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.

Delete ElasticSearch Indices and Restart Clarity LIMS on the New Instance

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:

Verify the New Instance

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.

ElasticSearch, Search Indexer, and RabbitMQ

Log in to 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.

Tomcat, Apache, Automation Worker

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.

LabLink

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.

[Optional] Sequencing Service

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

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 .

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

Migration Paths

The following table shows the applicable migration paths.

From

Notes

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 .
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 section of .
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.

Install the UpgradePreValidation RPM.
- 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.
1. Make sure that the Clarity LIMS server is running.
2. As the root user, run the following command:
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.
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:

Upgrade steps

Shut Down Clarity LIMS Components

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
- 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.
Stop any and all integration services.
- Find all the integration services and stop them, as described in the integration documentation.
Shut down the Clarity LIMS services.
- As the root user, run the following command:
  Copy
  - 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

Check if there is a need to force stop the tomcat application:
pgrep jsvc
As the root user, force stop the tomcat processes:
pkill jsvc

Backup the Database and Clarity LIMS

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

Upgrade Clarity LIMS Components

As the root user, run the following command:
As the glsjboss user, run the following command:
- 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:
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:
Check that all scripts have been run. As glsjboss user run any that are remaining:

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.

Install the LabLink RPM. Make sure that you have the correct repo enabled.
- On the 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

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:

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:

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

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:

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

Determine the components that are running.
- As the glsjboss or root user, run the following command:
  - Tomcat:
  - Automation workers:
  - Sequencing services:
Take note of the component that is running.
[Optional] Restart remote automation workers.
- Manually restart each of the remote automation worker from its local machine.

Validate the Installation

Log in to Clarity LIMS.
Make sure that Clarity LIMS is operating by performing your own validation steps.

On Premise to Hosted Upgrade Procedures

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

From Versions 4.2 / 4.3 / 5.0 / 5.1 / 5.2 / 6.0 / 6.1 /6.2 (PostgreSQL) and 4.2 / 4.3 / 5.0 / 5.1 / 5.2 (Oracle) to 6.3

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

For installation requirements, see Technical Requirements.

Migration Paths

The following table shows the applicable migration paths.

From

Notes

Prerequisites

Before Illumina can proceed with the upgrade, complete the following prerequisite steps.

#provision-the-new-instance
#verify-user-accounts-email-addresses
#install-and-run-the-pre-validation-script-on-the-source-server
#back-up-the-current-database-and-clarity-lims

Provision the New Instance

Illumina provisions an instance installed with the latest qualified Oracle Linux version in the cloud.

Upgrades are only supported from Clarity LIMS versions 4.2, 4.3, 5.0, 5.1, 5.2, 6.0, 6.1 and 6.2 (on-premise).

Custom configurations: If you have made any additional configurations that are not part of the Clarity LIMS preinstallation 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.

Verify User Accounts Email Addresses

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

Install and Run the Pre-Validation Script on the Source Server

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:
  yum --enablerepo=GLS_Clarity63 install ClarityLIMS-UpgradePreValidation
[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.
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.
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

Back Up the Current Database and Clarity LIMS

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:
  /opt/gls/clarity/bin/run_clarity.sh stop
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> -O -b -Ft <database_name> -f ~glsjboss/backups/database/clarity-old_version-`date +%Y%m%d%H%M`.tar
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 Cloud instance.
Directories
/opt/gls/clarity/users/glsftp or /home/glsftp (Clarity LIMS file store location)
/opt/gls/clarity/customextensions
/opt/gls/clarity/glscontents
Additional configurations:
rpm -qa | grep "BaseSpace\|Clarity" > clarityrpms.txt

Illumina will assists with the deployment of hosted Clarity LIMS.

Hosted to On Premise Upgrade Procedures

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

From Versions 4.2 / 4.3 / 5.0 / 5.1 / 5.2 / 5.3 / 5.4 / 6.0 / 6.1 /6.2 to 6.3

This document provides details on the steps required to upgrade an existing Clarity LIMS to RedHat Enterprise Linux/Oracle Linux compatible Clarity LIMS v6.3.

For installation requirements and Oracle Linux compatibility, see .

Migration Paths

The following table shows the applicable migration paths.

From

Notes

Prerequisites

Before Illumina can proceed with the upgrade, complete the following prerequisite steps.

Provision the New Instance

We recommend you provision an instance with similar or higher specifications to the current Clarity LIMS instance.

Note the following:

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/6.2.

Before installing Clarity LIMS on the new instance, make sure that the instance has the same fully-qualified domain name (QFDN) as the existing Production instance. If it is not possible to have the same QFDN, contact the Illumina Support team.

Configure the New Instance

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.

Verify User Accounts Email Addresses

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

Install and Run the Pre-Validation Script on the Source Server

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.
1. Make sure that the Clarity LIMS server is running.
2. As the root user, run the following command:
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.
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:

Back Up the Current Database and Clarity LIMS

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
/opt/gls/pgsql/12.x/pg_hba.conf
/opt/gls/pgsql/12.x/postgresql.conf
Additional configurations:
rpm -qa | grep "BaseSpace\|Clarity" > clarityrpms.txt

Upgrade steps

Install Latest Clarity LIMS on New Instance

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

Install and Configure LabLink 2.5

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

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:

Restore Backup Onto the New Instance

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 Illumina 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:
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.10, 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):
To configure the certificates, run the following command on the command-line interface, as the root user:
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.

[Optional] Change the Clarity LIMS Hostname

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

[Optional] Update Application Configuration

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.

Perform Application Migration

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:

[Optional] Install NGS, Illumina Preset Protocols (IPP), and Sequencing RPMs

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.

Delete ElasticSearch Indices and Restart Clarity LIMS on the New Instance

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:

Verify the New Instance

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.

ElasticSearch, Search Indexer, and RabbitMQ

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.

Tomcat, Apache, Automation Worker

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.

LabLink

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.

[Optional] Sequencing Service

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

On Premise to On Premise 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 Versions 4.2 / 4.3 / 5.0 / 5.1 / 5.2 / 6.0 / 6.1 (PostgreSQL) and 4.3 / 5.2 (Oracle) to 6.3

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

The installation procedure includes provisioning and configuring the new instance, and installing and then verifying the new Clarity LIMS version.

For installation requirements, see .

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

Migration Paths

The following table shows the applicable migration paths.

From

Notes

Prerequisites

Before Illumina can proceed with the upgrade, complete the following prerequisite steps.

Provision the New Instance

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 .
All standard operating system (OS) security updates must have been applied.
Upgrades are only supported from Clarity LIMS v4.2/5.0/5.1/6.0/6.1, and v4.3/5.2.0 (Oracle).
The command hostname -f must resolve to the fully qualified domain name (FQDN) of the server. For details, see the section of .

Configure the New Instance

To configure the new instance, follow the instructions provided in the and see also .

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.

Verify User Accounts Email Addresses

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

Install and Run the Pre-Validation Script on the Source Server

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:
  yum --enablerepo=GLS_Clarity63 install ClarityLIMS-UpgradePreValidation
[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 section of .
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.
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

Back Up the Current Database and Clarity LIMS

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:
  /opt/gls/clarity/bin/run_clarity.sh stop
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:
    Copy
    cd ~glsjboss mkdir -p backups/database pg_dump -U <database_user> -O -b -Ft <database_name> -f ~glsjboss/backups/database/clarity-old_version-`date +%Y%m%d%H%M`.tar
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
/opt/gls/pgsql/12.x/pg_hba.conf
/opt/gls/pgsql/12.x/postgresql.conf
Additional configurations:
rpm -qa | grep "BaseSpace\|Clarity" > clarityrpms.txt

Upgrade steps

Install Latest Clarity LIMS on New Instance

Make sure that the repository file exists in the following location:
```
/etc/yum.repos.d/
```
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
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
```

The following steps are only required if you are restoring from a previous instance. If you are installing on a testing environment, proceed to section.

Restore Backup Onto the New Instance

Restore backup must be carried out before LabLink v2.5 can be installed.

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
```
```
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.10, 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: .
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 .
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.

Install and Configure LabLink 2.5

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

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:
  yum --enablerepo=GLS_Clarity63 install ClarityLIMS-LabLink
Run the pending initialization script.
- As the glsjboss user, run the following command:
  bash /opt/gls/clarity/config/pending/60_initialize_lablink.sh
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

[Optional] Change the Clarity LIMS Hostname

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

For details, see .

[Optional] Update Application Configuration

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 .

Perform Application Migration

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

[Optional] Install NGS Illumina Preset Protocols (IPP), and Sequencing RPMs

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.

Delete ElasticSearch Indices and Restart Clarity LIMS on the New Instance

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

Verify the New Instance

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.

ElasticSearch, Search Indexer, and RabbitMQ

Log in to 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.

Tomcat, Apache, Automation Worker

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.

LabLink

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.

[Optional] Sequencing Service

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

Hosted to On Premise Upgrade Procedures

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

From Versions 4.2 / 4.3 / 5.0 / 5.1 / 5.2 / 5.3 / 5.4 / 6.0 / 6.1 /6.2 to 6.3

This document provides details on the steps required to upgrade an existing Clarity LIMS to RedHat Enterprise Linux/Oracle Linux compatible Clarity LIMS v6.3.

For installation requirements and Oracle Linux compatibility, see .

Migration Paths

The following table shows the applicable migration paths.

From

Notes

Prerequisites

Before Illumina can proceed with the upgrade, complete the following prerequisite steps.

Provision the New Instance

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 .
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/6.2.
The command hostname -f must resolve to the fully qualified domain name (FQDN) of the server. For details, see the section of .

Configure the New Instance

To configure the new instance, follow the instructions provided in the and see also .

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.

Verify User Accounts Email Addresses

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

Install and Run the Pre-Validation Script on the Source Server

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:
  yum --enablerepo=GLS_Clarity63 install ClarityLIMS-UpgradePreValidation
[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 section of .
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.
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

Back Up the Current Database and Clarity LIMS

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:
  /opt/gls/clarity/bin/run_clarity.sh stop
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> -O -b -Ft <database_name> -f ~glsjboss/backups/database/clarity-old_version-`date +%Y%m%d%H%M`.tar
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
/opt/gls/pgsql/12.x/pg_hba.conf
/opt/gls/pgsql/12.x/postgresql.conf
Additional configurations:
rpm -qa | grep "BaseSpace\|Clarity" > clarityrpms.txt

Upgrade steps

Install Latest Clarity LIMS on New Instance

Make sure that the repository file exists in the following location:
```
/etc/yum.repos.d/
```
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
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
```

The following steps are only required if you are restoring from a previous instance. If you are installing on a testing environment, proceed to section.

Install and Configure LabLink 2.5

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

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:
  yum --enablerepo=GLS_Clarity63 install ClarityLIMS-LabLink
Run the pending initialization script.
- As the glsjboss user, run the following command:
  bash /opt/gls/clarity/config/pending/60_initialize_lablink.sh
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

Restore Backup Onto the New Instance

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 Illumina 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.10, 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 .
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.

[Optional] Change the Clarity LIMS Hostname

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

For details, see .

[Optional] Update Application Configuration

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 .

Perform Application Migration

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

[Optional] Install NGS, Illumina Preset Protocols (IPP), and Sequencing RPMs

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.

Delete ElasticSearch Indices and Restart Clarity LIMS on the New Instance

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

Verify the New Instance

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.

ElasticSearch, Search Indexer, and RabbitMQ

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.

Tomcat, Apache, Automation Worker

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.

LabLink

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.

[Optional] Sequencing Service

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

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

For installation requirements, see .

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

Migration Paths

The following table shows the applicable migration paths.

From

Notes

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 .
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 section of .
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.

Install the UpgradePreValidation RPM.
- As the root user, run the following command:
  yum --enablerepo=GLS_Clarity63 install ClarityLIMS-UpgradePreValidation
[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 section of .
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.
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

Shut Down Clarity LIMS Components

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.
Stop any and all integration services.
- Find all the integration services and stop them, as described in the integration documentation.
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

Check if there is a need to force stop the tomcat application:
pgrep jsvc
As the root user, force stop the tomcat processes:
pkill jsvc

Backup the Database and Clarity LIMS

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

As the root user, run the following command:

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

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

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.

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
Run the pending initialization script.
- As the glsjboss user, run the following command:
  bash /opt/gls/clarity/config/pending/60_initialize_lablink.sh
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

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.
[Optional] Restart remote automation workers.
- Manually restart each of the remote automation worker from its local machine.

Validate the Installation

Log in to Clarity LIMS.
Make sure that Clarity LIMS is operating by performing your own validation steps.