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 Illumina cloud hosted deployments, this configuration is completed by Illumina.

Pre-requisites

1. You are planning to install Clarity LIMS v6.0.0 and newer.

2. You have installed the latest version of either HashiCorp Vault Open Source or Enterprise.

3. You have read the Getting Started tutorials for Vault on the HashiCorp website and/or possess a basic knowledge of HashiCorp Vault.

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.

1. To enable the AppRole authentication method, refer to the AppRole Pull Authentication tutorial provided on the HashiCorp Vault website.

2. When AppRole is enabled, create an AppRole with the appropriate Access Control List (ACL) policy (see the following section).

3. Make a note of the Role ID and Secret ID. You need these IDs when configuring Secret Utility.

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.

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.

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

Verification

1. SSH into the Clarity LIMS instance.

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

\

Before installing Clarity LIMS, you must purchase hardware and software that meet the minimum requirements (see Technical Overview). 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 Technical Requirements for details.

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:

1. Purchase an SSL / TLS certificate.

2. Save the certificate files on the server on which the Clarity LIMS server is installed.

3. Provide the Clarity LIMS 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

Set Up Root Access Server

Clarity LIMS is installed using industry standard RPM packaging. The Clarity LIMS 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.

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

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

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 Clarity LIMS Support team. Upon request, the Clarity LIMS 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.

For more information, refer to .

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

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

For installation requirements, see Technical Requirements.

Migration Paths

The following table shows the applicable migration paths.

Prerequisites

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

Provision the New Instance

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

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

1. Install the UpgradePreValidation RPM. Make sure you have the correct repo enabled.

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

2. [Optional] Set up Secret Utility.

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.

1. Stop Clarity LIMS:

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

2. Back up Postgresql database:

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

Clarity LIMS can work with Named or WildCard certificates.

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

1. Request a certificate from your IT organization, or purchase a certificate from a third-party SSL/TLS vendor.

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

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

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

For installation requirements and Oracle Linux compatibility, see Technical Requirements.

Migration Paths

The following table shows the applicable migration paths.

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.

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.

1. Install the UpgradePreValidation RPM. Make sure you have the correct repo enabled.

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

2. [Optional] Set up Secret Utility.

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.

1. Stop Clarity LIMS:

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

2. Back up Postgresql database:

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

Upgrade steps

Install Latest Clarity LIMS on New Instance

1. Make sure that the repository file exists in the following location:

2. As the root user, install the RPMs required on the new instance by referencing the content of clarityrpms.txt.

   • If you are upgrading from Clarity LIMS v4.x, some RPMs (eg, Server RPM) are now included under other RPMs.

Install and Configure LabLink 2.4

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

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

• sample submission templates

• customized UI CSS

• lablink property table configurations

Before completing the following steps, make sure that a database named lablink is created with the same database user as Clarity LIMS database.

1. Install the LabLink RPM. Make sure that you have the correct repo enabled.

   • On the new instance, as the root user, run the following command:

2. Run the pending initialization script.

Restore Backup Onto the New Instance

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

2. If using PostgreSQL database, the DBA imports the database dump into the new database instance. Dropping and recreating the database might be necessary. If you need to do this, use the following command:

   dropdb -U postgres <OL8DB> createdb -U postgres <OL8DB>

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

1. Update glsftp password.

2. Update apiuser password.

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

[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

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

2. Check that search results are returned.

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

Tomcat, Apache, Automation Worker

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

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

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

LabLink

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

2. Log in with administrator credentials.

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

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

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

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