Illumina Connected Analytics (ICA) subscription includes access to DRAGEN TruSight Oncology 500 ctDNA Analysis Software. To get started, you need:
An ICA account with a valid subscription
A positive balance of iCredits for data storage
Refer to the for information on how to register ICA subscription and iCredits.
Instructions to install DRAGEN TSO 500 ctDNA Analysis Application on NovaSeq 6000Dx (RUO mode)
The following requirements must be met to install and run DRAGEN TruSight Oncology 500 ctDNA Analysis Application on NovaSeq 6000Dx:
A NovaSeq 6000Dx sequencing instrument with Illumina Run Manager v1.6.2 installed and paired with DRAGEN Server v4.
Administrator privileges on Illumina Run Manager.
Perform the following steps to download and install the DRAGEN TruSight Oncology 500 ctDNA Analysis Application on NovaSeq 6000Dx installation package:
Contact Illumina Customer Care for the link to the installation package. The link expires after 7 days.
Download the installation package with the link provided in the email from Illumina Customer Care. The installation package contains the following files:
DRAGEN IRES file: drageninstaller_<DRAGEN_VERSION>.el8.x86_64_prod.ires
Perform the following steps to specify a location to store analysis results:
Log into Illumina Run Manager as an administrator.
From the Settings menu, select External Storage for Analysis Results.
Configure the following parameters:
The v2.6.3 app uses DRAGEN v3.11.2, which is not designed to be co-installed with earlier DRAGEN versions (e.g. v3.10.18 and below, v4.3.5 and below). When launching analysis after installing another NovaSeq 6000Dx app and its dependent version of DRAGEN (that does not support multi-version installation), the software may sporadically be unable to run. For example, users may encounter an issue if the following steps occur in order:
installation of the DRAGEN TSO 500 ctDNA v2.6.3 app for NovaSeq 6000Dx and its dependent DRAGEN, v3.11.2
Illumina Run Manager: TSO500L_v<APP_VERSION>.iapp
Install the DRAGEN version using the IRES file.
Log into Illumina Run Manager as an administrator.
From the Settings menu, select DRAGEN.
Select Add DRAGEN Installer.
Select the DRAGEN IRES file to begin installation.
Check the install versions list to verify that the appropriate DRAGEN version is listed
Install the Illumina Run Manager-compatible application.
Log into Illumina Run Manager as an administrator.
From the left-hand menu, select Applications.
Select the RUO tab, select Install Application, and then select the IAPP file to install the application.
Check the RUO Applications list to verify that the appropriate application version is listed. You can configure application settings such as required users from this list.
In addition to storing the analysis results from any sequencing runs, this location contains the input data created when setting up runs. Make sure that the server location has sufficient storage space for your run.
Encryption—Select Require encryption during file transfer.
Select Save to preserve the changes to the external storage output parameters.
installation of the DRAGEN TSO 500 ctDNA v2.6.1 app* for NovaSeq 6000Dx and its dependent DRAGEN, v3.10.18
analysis is initiated using DRAGEN TSO 500 ctDNA v2.6.3 app
*or any other app requiring an incompatible DRAGEN version. See Installation of TSO 500 ctDNA v2.6.2, v2.6.3 on Standalone DRAGEN Server for DRAGEN co-installation compatibility.
See Troubleshooting section for a workaround. NovaSeq 6000Dx App Troubleshooting
The installation script for DRAGEN TruSight Oncology 500 ctDNA Analysis Software installs the following software and dependencies:
DRAGEN TruSight Oncology 500 ctDNA Analysis Software itself
DRAGEN Software if a compatible version is not present
Docker software if a compatible version is not present
A script required to generate DRAGEN genome hash table
A script to check that DRAGEN TruSight Oncology 500 ctDNA Analysis Software is installed properly
DRAGEN server v3 or v4
Linux CentOS 7.9 operating system (or later) or Oracle Linux 8 (or later), one of which is provided on the server. Oracle Linux 8 is recommended.
Docker Software, see table below for minimum version needed. If sufficient Docker software is not present on the server, the TSO 500 installer will install compatible Docker software.
DRAGEN Server Software*, see table below for minimum version needed as the host version on the server. If sufficient DRAGEN software is not present on the server, the TSO 500 installer will install compatible DRAGEN software.
*The DRAGEN Server Software version may be higher than the DRAGEN version used by the DRAGEN TSO 500 ctDNA v2.6.2 pipeline (DRAGEN v3.10.18), which is provided inside the DRAGEN TSO 500 ctDNA docker image.
TSO500Combined license
TSO500Combined license has been pre-installed to DRAGEN servers in manufacturing since August 2022. To generate a list of installed DRAGEN server licenses, run the following command: /usr/bin/dragen_lic. If a license is not installed, contact Illumina Customer Care at for the license.
Illumina recommends logging in as root user for installation, but as a non-root user for running TSO 500 ctDNA analysis.
A non-root user must be a member of the Docker group to run Docker. For more information on Docker permission requirements and alternatives to running as root, refer to the Docker documentation available on the .
Installing and uninstalling DRAGEN TruSight Oncology 500 ctDNA Analysis Software and running the system check requires root privileges.
Run DRAGEN TruSight Oncology 500 ctDNA Analysis Software without being logged in as a root user. Running the DRAGEN TruSight Oncology 500 ctDNA Analysis Software as root is not required or recommended.
DRAGEN TSO 500 Analysis Software ctDNA v2.6.2 and v2.6.3 (v2.6.2+) are multi-version compatible. Multi-version compatibility refers to ability to be installed on a single DRAGEN server with software running a different version of DRAGEN software. For example, multi-version compatible pipelines running DRAGEN v4.3.6+ can be co-installed on a server alongside DRAGEN TSO 500 ctDNA pipelines with DRAGEN server software v3.10.19 and above. For more details on DRAGEN multi-version compatibility, please visit .
Software versions without multi-version compatibility referred to as single-version compatible. DRAGEN TSO 500 ctDNA Analysis Software v2.6.2+ will disrupt installations of single-version compatible software from the DRAGEN server. To uninstall a previous version of DRAGEN TSO 500 ctDNA Analysis Software, refer to the respective guide.
Compatibility of software for co-installation with DRAGEN TSO 500 ctDNA on a DRAGEN server is summarized in the table below:
*DRAGEN TSO 500 Analysis Software ctDNA v2.6.2+ can run on a single server with DRAGEN TSO 500 v2.5.4, and should be installed after v2.5.4. DRAGEN TSO 500 Analysis Software ctDNA v2.6.2+ can be co-installed with multi-version compatible DRAGEN TSO 500 Analysis Software or other DRAGEN pipelines with any order of installation.
**For example, DRAGEN Enrichment, DRAGEN Germline, and others. Order of installation does not matter.
Uninstall all existing single-version compatible software on the server (see table above)
Install DRAGEN TSO 500 ctDNA Analysis Software v2.6.2+
This step will disrupt previously installed single-version compatible software but will not impact multi-version compatible ones (see table above)
As a root user, perform the following steps to install DRAGEN TSO 500 ctDNA Analysis Software v2.6.2 and v2.6.3 (v2.6.2 for an example):
Contact Illumina Customer Care at to obtain the DRAGEN TSO 500 ctDNA Analysis Software installer package.
Download the installation package provided in the email from Illumina. The link expires after 7 days.
It is recommended to use a command line tool like wget or curl to download the file rather than pasting the link into the web browser bar. For example:
curl -o {filename} "{link}"
wget -O {filename} "{link}"
Where the file name is the installation script file name, and the link is provided by Illumina Customer Care.
Make sure no other analysis is being performed. Installing the software while performing other analyses prevents the installer process from proceeding.
Copy the install script to the /staging directory to store the script in the directory.
Installation Script: install_DRAGEN_TSO500_CTDNA-2.6.2.run
SHA256 value: 1324c86183526e12afb267f553a569cf78b01fd7a4ee85f8e07cc2f6a33d8f41
Installation Script: install_DRAGEN_TSO500_CTDNA-2.6.3.run
SHA256 value: 77a4f3b44af22c8c83e0bfe43d3b186d2b74dc58b8bbdb6f324ba3ce6220ab9e
Use the following command to update the run script permission:
chmod +x /staging/install_DRAGEN_TSO500_CTDNA-2.6.2.run
Use the following command to run the installation script (run time ~ 20 minutes):
For Docker, use the following command:
sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500_CTDNA-2.6.2.run . The script installs compatible DRAGEN software and removes any previously installed versions.
After installation is complete, make sure the system functions properly by running the following command: /usr/local/bin/check_DRAGEN_TSO500_CTDNA-2.6.2.sh
The script checks that:
All required services are running
Proper Docker image is installed
DRAGEN TSO 500 ctDNA Analysis Software can successfully process a test data set
The system check script runs for approximately 25 minutes. If the script prints a failure message, contact Illumina Technical Support and provide the /staging/check_DRAGEN_TSO500_CTDNA_<timestamp>.tgz output file.
If using MacOS to connect to a server, an error can occur if the local settings are not in English. To resolve the error, disable the ability to set environment variables automatically in Terminal settings.
The DRAGEN TSO 500 ctDNA Analysis Software installation includes an uninstall script called uninstall_DRAGEN_TSO500_CTDNA-2.6.2.sh, which is located in /usr/local/bin.
Executing the uninstall script removes the following assets:
All DRAGEN TSO 500 Analysis Software related scripts located in /usr/local/bin
Resources found in /staging/illumina/DRAGEN_TSO500_CTDNA-2.6.2
The dragen_tso500_ctdna Docker image
To uninstall the DRAGEN TSO 500 ctDNA Analysis Software, run the following command as a root user:
uninstall_DRAGEN_TSO500_CTDNA-2.6.2.sh
You are not required to uninstall Docker or DRAGEN software. To remove Docker, review the install instructions for your operating system in the Docker documentation.
DRAGEN TSO 500
2.6.0
Single-version
No
DRAGEN TSO 500
2.5.4
Multi-version
Yes*
DRAGEN TSO 500
2.5.3 or below
Single-version
No
DRAGEN pipelines**
4.3.6+
Multi-version
Yes
DRAGEN pipelines**
4.2 or below
Single-version
No
Multi-version software can be installed in any order
If new DRAGEN version is not installed from the above command, use sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500_CTDNA-2.6.2.run -- --forceDragenInstall to force a reinstall of DRAGEN.
For Apptainer, use the following command:
sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500_CTDNA-2.6.2.run -- --noDockerInstall This will not install Apptainer, but will install the analysis software in the Singularity Image File (SIF) format and modify the software to launch analyses using Apptainer.
During the installation process, you may be instructed to reboot or power cycle the system to complete the installation of the DRAGEN software. A power cycle of the system requires the server be shut down and restarted.
Log out of the server and log back in.
Install your DRAGEN server licenses if needed (use /opt/dragen/3.11.2/bin/dragen_lic for v2.6.3):
To run DRAGEN TSO 500 ctDNA Analysis Software v2.6.2 , you need TSOCombined license. This license is pre-installed on DRAGEN servers purchased after August 2022. To check if the license is already installed, run /opt/dragen/3.10.19/bin/dragen_lic command.
For servers connected to the Internet, install your software licenses as follows:
First, test and confirm that the server is connected to the Internet. Example: ping www.illumina.com
To install the license, enter: /opt/dragen/3.10.19/bin/dragen_lic -i auto
For servers not connected to the internet, contact Illumina Customer Care at for license information.
After installing DRAGEN server licenses, generate a list of installed licenses by running the following command: /opt/edico/bin/dragen_lic
If license installation is successful, the list should include TSOCombined.
If the expected licenses are not installed, contact Illumina Customer Care.
Docker
20.10 or greater
Docker 20.10.15
DRAGEN Server Software*
v3.10.x, where x >=19, v4.3+ for TSO500 ctDNA v2.6.2;
v3.11.x, where x >=2, v4.3+ for TSO500 ctDNA v2.6.3
DRAGEN Software 3.10.19 for TSO500 ctDNA v2.6.2;
DRAGEN Software 3.11.2 for TSO500 ctDNA v2.6.3
DRAGEN TSO 500 ctDNA
2.6.2+
Multi-version
Yes
DRAGEN TSO 500 ctDNA
2.6.1 or below
Single-version
No
DRAGEN TSO 500
2.6.1+
Multi-version
Yes
The installation script for DRAGEN TruSight Oncology 500 ctDNA Analysis Software installs the following software and dependencies:
DRAGEN TruSight Oncology 500 ctDNA Analysis Software itself
DRAGEN Software if a compatible version is not present
Docker software if a compatible version is not present
A script required to generate DRAGEN genome hash table
A script to check that DRAGEN TruSight Oncology 500 ctDNA Analysis Software is installed properly
DRAGEN server v3 or v4
By default Linux CentOS 7.9 operating system (or later) or Oracle Linux 8 (or later), is provided. Oracle Linux 8 is recommended.
Docker Software, see table below.
DRAGEN Software, see table below.
DRAGEN TruSight Oncology 500 ctDNA v2.6.0 Analysis Software is not compatible with DRAGEN Software v4.0 or above on the same standalone DRAGEN server.
TSO500Combined license
TSO500Combined license has been pre-installed to DRAGEN servers in manufacturing since August 2022. To generate a list of installed DRAGEN server licenses, run the following command: /opt/edico/bin/dragen_lic. If a license is not installed, contact Illumina Customer Care at for the license.
Illumina recommends logging in as root user for installation, but as a non-root user for running TSO 500 ctDNA analysis.
A non-root user must be a member of the Docker group to run Docker. For more information on Docker permission requirements and alternatives to running as root, refer to the Docker documentation available on the .
Installing and uninstalling DRAGEN TruSight Oncology 500 ctDNA Analysis Software and running the system check requires root privileges.
Run DRAGEN TruSight Oncology 500 ctDNA Analysis Software without being logged in as a root user. Running the DRAGEN TruSight Oncology 500 ctDNA Analysis Software as root is not required or recommended.
DRAGEN TruSight Oncology 500 Analysis Software ctDNA v2.6.0 can be installed on one DRAGEN server with:
DRAGEN TruSight Oncology 500 Analysis Software v2.6.0 (v3.10.17*)
One prior 2.x version of DRAGEN TruSight Oncology 500 ctDNA Analysis Software (v2.1.1 (v3.10.9*), v2.5.0 (v3.10.15*), 2.6.0 (v3.10.17*), 2.6.1 (v3.10.18*))
One prior 2.x version of DRAGEN TruSight Oncology 500 Analysis Software (v2.1.1 (v3.10.9*), v2.5.3 (v3.10.16*)
*DRAGEN Software version
Contrary to the prior versions, the installation scripts for DRAGEN TruSight Oncology 500 ctDNA Analysis Software v2.6.0 and DRAGEN TruSight Oncology 500 v2.6.0 do not uninstall previous versions of DRAGEN TruSight Oncology 500 Analysis Software. To uninstall a previous version of DRAGEN TruSight Oncology 500 ctDNA Analysis Software, refer to the respective guide.
When installing DRAGEN TruSight Oncology 500 and DRAGEN TruSight Oncology 500 ctDNA software on the same DRAGEN server, install the software with the highest corresponding DRAGEN Software version last, as versions below v2.6.0 will overwrite with its corresponding DRAGEN Software version.
If a prior version of DRAGEN TruSight Oncology 500 ctDNA Analysis Software (eg. v2.5.0) is installed after v2.6.0, re-execute the installation script for v2.6.0 to install the compatible version of DRAGEN Software without impacting other installations.
As a root user, perform the following steps to install DRAGEN TruSight Oncology 500 ctDNA v2.6.0 Analysis Software:
Contact Illumina Customer Care at to obtain the DRAGEN TruSight Oncology 500 Analysis Software installer package.
Download the installation package provided in the email from Illumina. The link expires after 7 days.
It is recommended to use a command line tool like wget or curl to download the file rather than pasting the link into the web browser bar. For example:
curl -o {filename} "{link}"
wget -O {filename} "{link}"
Where the file name is the installation script file name, and the link is provided by Illumina Customer Care.
Make sure no other analysis is being performed. Installing the software while performing other analyses prevent the installer process from proceeding.
Copy the install script to the /staging directory to store the script in the directory.
Installation Script:
install_DRAGEN_TSO500_ctDNA-2.6.0.run
install_DRAGEN_TSO500_ctDNA-2.6.1.run
MD5sum values v2.6.0: sha256:e98ab87152b02e2c7958f2f750fa37880a496d68e77858a09f4ad5fb07b2145b v2.6.1: sha256:026efd4402e91e8472effb30749e231817958532aae128334c5f9943564e4b8d
Use the following command to update the run script permission:
chmod +x /staging/install_DRAGEN_TSO500_CTDNA-2.6.0.run
Use the following command to run the installation script, which runs for approximately 20 minutes:
For Docker, use the following command:
sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500_CTDNA-2.6.0.run
After installation is complete, make sure the system functions properly by running the following command: /usr/local/bin/check_DRAGEN_TSO500_CTDNA-2.6.0.sh
The script checks that:
All required services are running
Proper Docker image is installed
DRAGEN TruSight Oncology 500 ctDNA Analysis Software can successfully process a test data set
The system check script runs for approximately 25 minutes. If the script prints a failure message, contact Illumina Technical Support and provide the /staging/check_DRAGEN_TSO500_CTDNA_<timestamp>.tgz output file.
If using MacOS to connect to a server, an error can occur if the local settings are not in English. To resolve the error, disable the ability to set environment variables automatically in Terminal settings.
The DRAGEN TruSight Oncology 500 Analysis Software installation includes an uninstall script called uninstall_DRAGEN_TSO500_CTDNA-2.6.0.sh, which is located in /usr/local/bin.
Executing the uninstall script removes the following assets:
All DRAGEN TruSight Oncology 500 ctDNA Analysis Software related scripts located in /usr/local/bin
Resources found in /staging/illumina/DRAGEN_TSO500_CTDNA
The dragen_tso500_ctdna Docker image
To uninstall the DRAGEN TruSight Oncology 500 ctDNA Analysis Software, run the following command as a root user:
uninstall_DRAGEN_TSO500_CTDNA-2.6.0.sh
You are not required to uninstall Docker or DRAGEN software. To remove Docker, review the install instructions for your operating system in the Docker documentation.
For Apptainer, use the following command:
sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500_CTDNA-2.6.0.run -- --noDockerInstall This will not install Apptainer, but will install the analysis software in the Singularity Image File (SIF) format and modify the software to launch analyses using Apptainer.
During the installation process, you might be instructed to reboot or power cycle the system to complete the installation of the DRAGEN software. A power cycle of the system requires the server be shut down and restarted.
Log out of the server and then log back in.
Install your DRAGEN server licenses if needed:
To run DRAGEN TruSight Oncology 500 ctDNA v2.6.0 Analysis Software, you need TSOCombined license. This license is pre-installed on DRAGEN servers purchased after August 2022. To check if the license is already installed, run /opt/edico/bin/dragen_liccommand.
For servers connected to the Internet, install your software licenses as follows:
First, test and confirm that the server is connected to the Internet. Example: ping www.illumina.com
To install the license, enter: /opt/edico/bin/dragen_lic -i auto
For servers not connected to the internet, contact Illumina Customer Care at for license information.
After installing DRAGEN server licenses, generate a list of installed DRAGEN server licenses by running the following command: /opt/edico/bin/dragen_lic
If license installation is successful, the list should include TSOCombined.
If the expected licenses are not installed, contact Illumina Customer Care.
Docker
20.10 or greater
Docker 20.10.15
DRAGEN Software
v3.10.x where x is 17 or greater
DRAGEN Software 3.10.17