NovaSeq 6000Dx Integration v1.1 Installation

The Illumina NovaSeq 6000Dx Integration v1.1 supports the integration between Clarity LIMS (v5.1 or later) and the NovaSeq 6000Dx instrument. The integration includes the following changes:

• Updates to the NovaSeq 6000Dx library tube and flow cell barcodes that are accepted by the workflow.
• Fixes to the Denial of Service (CVE-2022-22970) and Integer Overflow (CVE-2022-22976) vulnerabilities.

This document provides instructions for installing NovaSeq 6000Dx Integration v1.1 and describes the components that are installed in the default configuration.

Illumina NovaSeq 6000Dx Integration v1.1 includes the following features and functionality:

• Preconfigured NovaSeqDx v1.1 workflow that maps to lab protocols and instrument runs.
• The following preconfigured protocols:
– Run Format (NovaSeqDx v1.1)
– NovaSeqDx Standard (NovaSeqDx v1.1) (supports the loading of pooled libraries into a library tube and the IVD sequencing run for the S2 and S4 flow cells)
– NovaSeqDx Xp (NovaSeqDx v1.1) (supports individual lane loading on the NovaSeq 6000Dx)
– AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.1)
• Automated generation of the v2 sample sheet. This file is automatically uploaded to the sequencing instrument through the Sequencer API and is used to set up the run.
• Automated validation of run setup information. This information is uploaded to the NovaSeq 6000Dx Operating Software (NVOS) through the Sequencer API. It is used to create the run recipe and initiate the run.
• Automated tracking of the following NovaSeq 6000Dx sequencing run information, and parsing of run statistics into Clarity LIMS:
– Progress and metrics of sequencing run
– Per-instrument sequencing runs (tracked as part of the Run ID field value)
– Sequencing run parameters
– Sequencing run data directory location
– Real-Time Analysis v3 (RTA3) version and other run-specific information
• [Optional] Preconfigured Library Prep Validation v2.3.0 workflow used for validation purposes. This workflow contains a single-step protocol that models the library prep required to produce normalized libraries that are ready for the NovaSeqDx v1.0 workflow. For more information, refer to NovaSeq 6000Dx Integration v1.1 Validation and Troubleshooting.

The Illumina NovaSeq 6000Dx Integration Package v1.1 depends on the configuration provided in Illumina Protocols (IPP) v2.5.

The installation procedure provided in this document includes steps that install the following IPP configurations on the server used for the NovaSeq 6000Dx integration installation:

• QC Protocols Base configuration
• NovaSeqDx configuration
• Library Prep Validation configuration (optional, but recommended)

For details on IPP v2.5 installation and configuration, refer to the Illumina Preset Protocols documentation.

The Illumina cloud hosted installation configures an additional include directive for /etc/httpd/conf.d/clarity.conf in the proxy configuration. Additional proxy configuration files for the Sequencer API service are expected to be placed in the /etc/httpd/conf.d/clarity folder.

If Clarity LIMS Secret Utility is not installed or configured, use the following information to configure Secret Utility:

Installation on a hosted system with Clarity LIMS (v5.4 or later)

The Clarity LIMS installation tooling configures this installation. No additional configuration is necessary.

Installation on Clarity LIMS (v5.3 or later)

The installation includes the following components:

• Tenant DB Password
• Clarity DB Password
• FTP password
• LDAP manager password (if LDAP is enabled)
• LabLink DB password (for Clarity LIMS v5.3 LabLink only)
• Reporting DB password (if installed)
• RabbitMQ password

For more information on Secret Utility configuration, refer to the Clarity LIMS Core Functionality documentation.

NovaSeq 6000Dx Integration v1.1 is distributed as the BaseSpaceLIMS-sequencer-api RPM package. This package must be installed on the Clarity LIMS server.

The BaseSpaceLIMS-sequencer-api RPM installs the following files and scripts:

•Sequencer API WAR file
•application.yml configuration file
•configure_sequencer_api_proxy.sh configuration script
•configure_sequencer_api_env.sh configuration script
• configure_sequencer_api_application.sh configuration script

The RPM installs the Sequencer API WAR file into the same Tomcat container as Clarity LIMS. The WAR file is installed to the following location: /opt/gls/clarity/tomcat/current/webapps/Illumina#Sequencer#v2##2.5.0.0.war

The version number can differ.

The WAR file is deployed automatically when Clarity LIMS launches. Because the RPM installs a new WAR file, Clarity LIMS is automatically stopped during installation of the RPM. Restart Clarity LIMS before installing the NovaSeq and Library Prep Validation workflow configuration from the IPP.

The application.yml configuration file is installed to the following location:

/opt/gls/clarity/extensions/sequencer-api/application.yml

The file properties are configured with a script during the installation process.

For a complete list of all properties included in the application.yml file, refer to NovaSeq 6000Dx Integration v1.1 Configuration and User Interaction.

The scripts in the following table are installed to the following location:

/opt/gls/clarity/config

During installation, the RPM runs these scripts as they are needed.

Script Name

User

Description

configure_sequencer_api_proxy.sh

root

Adds configuration to the proxy to allow communication with the Sequencer API after Tomcat has been started.

Run this script in the following scenarios:

• When the Sequencer API is first installed.
• When reconfiguring the Clarity LIMS proxy. This process happens until a version of Clarity LIMS that includes the necessary configuration files from /etc/httpd/clarity/*.conf is available.

Not required for Illumina cloud hosted installations.

configure_sequencer_api_env.sh

root

Adds Secret Management setting into the Clarity LIMS Tomcat configuration.

Run this script when the Sequencer API is first installed on a Secret Util-enabled Clarity LIMS.

configure_sequencer_api_application.sh

glsjboss

• Configures the installed application.yml file.
• Sets the Clarity LIMS URL and the key to use when signing access tokens.

Run this script when the Sequencer API is first installed.

If you run the script multiple times, the script reconfigures each setting to its default. The only exception is the signing key. For this setting, you are asked if you want a reset. If the reset is done, all previously issued tokens are no longer valid.

NovaSeq 6000Dx Integration v1.1 supports RedHat Enterprise Linux and CentOS up to v7.9. Use v7.9 due to mitigate security risks. CentOS v6 is not supported.

If running the sequencing service and Automation Worker on the same instance, the instance must also be running a supported version of the Linux operating system.

If you are using PhiX control, install the base configuration of the QC Protocols from IPP as follows.

1. Log in as the root user on the server being used to install the integration.
2.Use the following yum command to install the IPP RPM:

yum install BaseSpaceLIMS-Illumina-Preset-Protocols --enablerepo=<< repo name info from support >>

The --enablerepo command-line argument must be included to enable the repo. The Illumina Support team can provide you with the repo file with the appropriate naming convention.

3.Enter y to confirm that you want to proceed with the RPM and package installation.
4.Make sure that NGS Extension Package v5.22 is installed.

If this package is not installed, you must install it or upgrade the existing package.

5.As the glsjboss user, install the QC_Protocols.qc-protocols configuration from the following location:

/opt/gls/clarity/config/illumina-preset-protocols-installer.sh -o install QC_Protocols.qc-protocols.

For information on IPP installer commands, parameters, and options, refer to Illumina Preset Protocols Integration v2.5 Installation and Configuration in the Illumina Preset Protocols documentation.

Install the Sequencer API as follows.

1. On the Clarity LIMS server, log in as the root user.
2.Use the following yum command to install the RPM:

yum install BaseSpaceLIMS-sequencer-api --enablerepo=< repo name info from support >

The --enablerepo command-line argument must be included to enable the repository. The Illumina Support team can provide you with the repo file with the appropriate naming convention.

3.Enter y to confirm that you want to proceed with the RPM installation.
4.If necessary, install the Secret Utility Package.

For more information on this package, refer to Prerequisite 3: Secret Utility Configuration.

5.As the glsjboss user, run configure_sequencer_api_application.sh from the following location:

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

6.Enter values for the presented as follows.

You can also press Enter to accept the default values in the application.yml configuration file. For more information about the application.yml properties, refer to NovaSeq 6000Dx Integration v1.1 Configuration and User Interaction.

•Would you like to use the apiuser user for communication with Clarity? [Y]
•Enter required value for Token Expiry (hours) [88]
7.Update the Clarity LIMS proxy for the Sequencer API as follows.
•For an on-premise system, run the following command:

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

•For an Illumina cloud hosted system, make sure that the proxy has been updated as follows. Place the sequencer-api.include file in /etc/httpd/conf.d/clarity.

<Location "/Illumina/Sequencer/v2">

ProxyPass ajp://localhost:9009/Illumina/Sequencer/v2

ProxyPassReverse ajp://localhost:9009/Illumina/Sequencer/v2

</Location>

8.Update the Clarity LIMS Tomcat configuration as follows.
a. Make sure that Secret Utility is installed and configured. For more information, refer to Prerequisite 3: Secret Utility Configuration.
b. Run the following command to add the Secret Utility configuration to Clarity LIMS:

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

This script modifies /opt/gls/clarity/tomcat/current/bin/setenv.sh for Clarity LIMS Tomcat to load the Secret Utility environment variable file (/etc/profile.d/claritysecret.sh) during startup.

c. Use the following command to Start Clarity LIMS:

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

Install the NovaSeqDx and Library Prep workflow configuration from IPP as follows.

1. As the glsjboss user, run the following command to install the NovaSeq 6000Dx v1.1 workflow configuration:

bash /opt/gls/clarity/config/illumina-preset-protocols-installer.sh -o install Illumina_Instruments.novaseqdx-v1.1

The installer validates the import of the workflow and provides the Warning/Error details in STDOUT, which allows you to either proceed with the import or cancel it.

2.[Optional] Run the following command to install the Library Prep Validation v2.3.0 workflow:

/opt/gls/clarity/config/illumina-preset-protocols-installer.sh -o install Illumina_Instruments.Library-Prep-Validation-v2.3

This step is optional, but recommended. The Library Prep Validation v2.3.0 workflow allows you to validate the NovaSeqDx v1.1 workflow.

Make sure that the Sequencer API is working as follows.

1. Visit https://<< Clarity LIMS URL >>/Illumina/Sequencer/v2/sequencing-run/login. This page returns the following URL string:

https://<< Clarity LIMS URL >>/Illumina/Sequencer/v2/oauth/authorize?client_id=illumina_sequencer&amp;redirect_uri=../sequencer_login&amp;response_type=token

2.Copy and paste the URL string into the browser. The Clarity LIMS Sign In page opens.
3.Enter sign in credentials.
4.Select Sign In. A Successfully Authenticated message displays.

The installer script configures the application.yml configuration properties by prompting for values. You can also configure these properties by editing the application.yml file, and then restarting Clarity LIMS. Configuring these properties is optional.

For more information, refer to NovaSeq 6000Dx Integration v1.1 Configuration and User Interaction.

NovaSeq 6000Dx Integration v1.1 includes the workflows, protocols, and steps listed in the following table.

Package

Workflow

Protocols

Steps

IPP v2.5

NovaSeqDx v1.1

Run Format (NovaSeqDx v1.1)

1. Define Run Format (NovaSeqDx v1.1)

NovaSeqDx Standard (NovaSeqDx v1.1)

1. Make Bulk Pool for NovaSeqDx Standard (NovaSeqDx v1.1)
2.Dilute and Denature (NovaSeqDx v1.1)

NovaSeqDx Xp (NovaSeqDx v1.1)

1. Make Bulk Pool for NovaSeqDx Xp (NovaSeqDx v1.1)
2.Dilute, Denature, and ExAmp (NovaSeqDx v1.1)
3.Load to Flowcell (NovaSeqDx v1.1)

AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.1)

1. AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.1)

IPP v2.5

Library Prep Validation v2.3.0

Library Prep Validation v2.3.0

1. Library Prep Validation v2.3.0

For detailed descriptions of the steps and automations included in each protocol, and details on other components in the configuration, refer to NovaSeq 6000Dx Integration v1.1 Configuration and User Interaction.

For instructions on using the Library Prep Validation v2.3.0 protocol, refer to NovaSeq 6000Dx Integration v1.1 Validation and Troubleshooting.

The NovaSeq 6000Dx instrument software includes the following components:

•NovaSeq 6000Dx Operating Software (NVOS)—Contains the user interface for setting up the sequencing run. Responsible for controlling the instrument and acquiring the images.
•Real-Time Analysis v3 (RTA3)—Takes the images generated by the first module, processes, and analyzes them. Makes sure that data files are created and copied to the final destination folder.
•Sequencing Analysis Viewer (SAV)—Displays the important quality metrics generated by the RTA3 software.
•NovaSeq 6000Dx recipes—Provides system operation instructions for use with NovaSeq 6000Dx reagent kits for SP, S1, S2, and S4 flow cells.
•Universal Copy Service—Copies output files to destinations such as final destination folder and/or BaseSpace Sequence Hub (when the instrument is configured for use with BaseSpace Sequence Hub).

For the NovaSeq 6000Dx API integration to work, the instrument must be able to communicate with Clarity LIMS through the API. Complete the following steps to configure the NVOS and confirm that you can access Clarity LIMS from the instrument.

1. Launch NVOS and wait for the initialization process to complete.
2.On the NVOS Instrument Settings page, do as follows.
a. Select the Global Settings tab.
b. Under Instrument Mode, select one of the following modes:
•Allow users to switch between IVD and RUO
•IVD Only
•RUO Only
3.If you selected IVD Only instrument mode, select the IVD Settings tab and complete the following steps:
a. Configure Run Setup as follows.
•Select the Select runs from the LIMS server option.
•Enter the Clarity LIMS URL (eg, https://yourserver.claritylims.com).
b. [Optional] Under Output Location, enter the output folder location. You can also specify the output folder location when setting up a run in NVOS.
4.If you selected RUO Only instrument mode, select the RUO Settings tab and complete the following steps:
a. Configure Run Setup as follows.
•Select the Select runs from the LIMS server option.
•Enter the Clarity LIMS URL(eg, https://yourserver.claritylims.com).
b. Configure Default Work Type as follows.
•[Optional] If selection support between NovaSeq Xp or NovaSeq Standard is required for the workflow, select the Enable workflow selection checkbox.
•Select the required default workflow type: NovaSeq Standard or NovaSeq Xp.
c. [Optional] Configure Output Location as follows.
•[Optional] Enter the output folder location. You can also specify the output folder location when setting up a run in NVOS.
•[Optional] To upload and store run data in the cloud server, select the BaseSpace Sequence Hub checkbox. Select a Configuration option (Run Monitoring and Storage or Run Monitoring Only) and select your Hosting Location from the drop-down list.
5.Select Save to complete the configuration.
6.On the NVOS home page, you can now select Sequence to log into Clarity LIMS and start a run.