DRAGEN Application Manager

Overview

Dragen Application Manager is a framework for installing and running DRAGEN command line, and DRAGEN applications with Nextflow, in a containerized environment.

Features

Nextflow and DRAGEN versions exist independently. Only one version of DRAGEN need be installed on the OS, and compatible versions of DRAGEN can exist in containers.

Run an application or DRAGEN CLI through Dragen Application Manager with JSON, or command line arguments.

Integrated application help system.

The Dragen Application Manager CLI provides JSON responses for simplifid automation.

Keeps a history of past runs.

Installation and Maintenance

Prerequisites

• Oracle Linux 8, or 9

• Docker 26 to 28

• DRAGEN 4.4

System Maintenance

When performing system maintenance that may include updating Docker or restarting the system, it is recommended to wait until any in progress analysis is completed. The command line provides details about an in progress analysis if there is one.

dragen-app-manager run status

If there is an analysis in progress, wait until it's completed, and then stop the service, perform the maintenance, and then restart the service. Stopping and starting the service is accomplished with the following commands:

sudo systemctl stop dragen-app-manager
sudo systemctl start dragen-app-manager

Note that manually teminating the dragen-app-manager service, or any of its dependencies, while it is busy, may result in unintended outcomes.

Uninstallation Procedure

An uninstaller is included, and is the recommended way to remove the software. It is recommended to remove any installed applications and resources first if desired.

sudo uninstall_dragen_app_manager.sh

Docker Configuration

Official instructions can be found here: https://docs.docker.com/engine/install/linux-postinstall/

The minimal requirement for a Docker configuration is that it is running as a service, there is a Docker group, and users that will use Dragen Application Manager will be in that group.

To create the group:

sudo groupadd docker

Add a user to that group

sudo usermod -aG docker $USER

You may need to logout and login for the group changes to take effect.

Changing Docker File Locations

By default, Docker will place its data in /var. Depending on the number of applications and resources you plan to install, it may be preferable to change this setting to a location with more space available.

You can change this default location by creating or modifying the file /etc/docker/daemon.json with the following content.

sudo vim /etc/docker/daemon.json

Change the contents of deamon.json to include a new data-root setting.

{
  "data-root": "/staging/.docker"
}

Further documentation on this setting can be found at: https://docs.docker.com/reference/cli/dockerd/.

Dragen Application Manager Configuration

Data Directories

You have the option to change some settings in Dragen Application Manager. Upon changing these settings, the service must be restarted.

sudo systemctl restart dragen-app-manager

The configuration file is found at /etc/dragen-app-manager/config.toml. Editing the file requires sudo.

sudo vim /etc/dragen-app-manager/config.toml

A full list of settings can be seen in the Configuration section of the health check. In most cases, the default values do not need to be changed; however, your system configuration may require this. If changing directories, it is recommended to mimic the file permissions of the default directories.

The recommended process to change any settings is to:

1. Validate that Dragen Application Manager is not currently in use

2. Stop the service with "sudo stop dragen-app-manager"

3. Make changes to the configuration with "sudo vim /etc/dragen-app-manager/config.toml"

4. Move the contents of application, resources, and temp directories when appropriate

5. Start the service with "sudo start dragen-app-manager"

Setting	Default	Permissions
directory.applications	/var/illumina/dragen-app-manager/applications	0755
directory.resources	/var/illumina/dragen-app-manager/resources	0755
directory.temp	/var/illumina/dragen-app-manager/temp	0777

These settings can be verified from the health check.

Output Directories

If appropriate, consider implementing a disk quota on output directories.

Reserving CPU and Memory for the Host OS

To avoid an overuse of resources by a container, memory and CPU are reserved for the Host OS. By default, 4 CPUs and 6 GiB of memory are reserved. These values can be changed with the following configuration settings. This sets a hard limit on the resources an application can use inside a container based on the available memory at the time it starts.

[hardware]
reserveCPU=4.0
reserveMemory=6442450944

CPU is a decimal between 1 and one less than the number of logical CPU's. Memory is the amount of memory in bytes.

Applications can override these settings only for the containers they create directly.

CLI Usage

Dragen Application Manager, as with the DRAGEN executable, is intended to handle one command at a time. This means that if one user starts an analysis, a second user will be prevented from starting an analysis at the same time. This applies to all command line operations. In most cases, if Dragen Application Manager is busy, it will pause any additional requests, and handle them when the initial operation is completed.

If a Dragen Application Manager command does not succeed, it will return non-zero, and depending on the command and type of failure, may include JSON in the response, and may also send data to STDOUT and/or STDERR. A successful command will return 0, and send a JSON response to STDOUT, and may also send appropriate informational data to STDERR.

Providing a JSON response allows for easy, and reliable, extraction of specific data. In the case of wanting to view a formatted response, piping the output to "jq" is the preferred option. Examples of this will be provided.

Help

To start using Dragen Application Manager, the first command to become acquainted with is the "help" command.

dragen-app-manager help

With any command, you can add the "–help" flag to get further usage information. For example:

dragen-app-manager --help
dragen-app-manager help --help
dragen-app-manager run --help

If any applications are installed, a command to show additional usage information for that application will be displayed. For example:

> dragen-app-manager help
How to get application help.
 
[Application]
- Provider: Illumina
- Name: SimpleApp
- Version: 1.0.0
Usage:
dragen-app-manager help --provider Illumina --name SimpleApp --version 1.0.0

Running the command that specifies an application provides the following:

> dragen-app-manager help --provider Illumina --name SimpleApp --version 1.0.0
 
SimpleApp version 1.0.0 provided by Illumina
 
This requires the parameter "A" to be set with the value "B",
a Flag must be explicitly set to either true or false,
and a Count with a value greater than 0.
There is also an example of representing a number as a string.
 
[Environment]
 
--environment TZ=<value>
Description: Timezone
 
[Settings]
 
--setting simple=<value>
Description: A simple setting that is a filename
 
[Parameters]
 
--param.A
Description: A required parameter with an required value of B.
 
--param.Flag
Description: A flag must be explicitly set.
 
--param.Count
Description: A number.
 
--param.NumberString
Description: A number as a string
 
[Resources]
 
--resource opt=<value>
Description: the /opt directory
 
Usage:
dragen-app-manager dry-run --provider Illumina --name SimpleApp --version 1.0.0 --inputDirectory input --outputDirectory output --environment TZ=EST --setting simple=config.json --resource opt=/opt --param.A B --param.Flag true --param.Count 1 --param.NumberString '"1532554234"'

Install

This command installs applications and resources. If an application has any resource dependencies, they must be installed before the application can be installed. Installation of both applications and resources include file validation. The speed of this operation depends on the size of the files that are validated.

dragen-app-manager install --file ./application.iapp
dragen-app-manager install --file ./resource.ires

Remove

This command removes an application or resource. If a resource is required by an application, the application must be removed first.

dragen-app-manager remove application --provider Illumina -name SimpleApp -version 1.0.0
dragen-app-manager remove resource --provider Illumina -name SimpleResource -version 1.0.0

It is possible to force remove a resource that is a dependency for an application; however, once it is used, the resource should be immediately installed again.

Health

The health check provides general information about application health, settings, and system status. The health check will return a non-zero value if it is unable to perform the health check.

dragen-app-manager health
 
dragen-app-manager health | jq

This is an example of the most relevant parts of the response to a health check.

{
  "HostOS": {
    "Release": "Oracle Linux Server release 8.10",
    "Healthy": true,
    "Partitions": [
      {
        "Mount": "/staging",
        "Size": "11 TB",
        "Used": "263 GB",
        "Available": "11 TB",
        "AvailablePercent": "97.8 %"
      },
      {
        "Mount": "/var",
        "Size": "251 GB",
        "Used": "97 GB",
        "Available": "154 GB",
        "AvailablePercent": "61.3 %"
      }
    ]
  },
  "Dragen": {
    "Version": "07.031.773.4.4.2",
    "HashTableVersion": "10",
    "Healthy": true,
    "Status": "Okay",
    "FileSystem": {
      "Healthy": true
    }
  },
  "Docker": {
    "Healthy": true,
    "Info": {
      "Version": "27.5.1",
      "Security": [
        "name=seccomp,profile=builtin"
      ]
    },
    "Parameters": {
      "APIVersion": "1.47",
      "OSType": "linux",
      "Experimental": false,
      "BuilderVersion": "2"
    }
  },
...
}

List

This command will provide a list of all applications and resources.

dragen-app-manager list
 
dragen-app-manager list | jq
 
dragen-app-manager list --detailed | jq

This is an example response for the default list statement piped to "jq". It shows that the SimpleApp is installed, its Nextflow dependency, and a DRAGEN resource.

{
  "Applications": [
    {
      "Name": "SimpleApp",
      "Version": "1.0.0",
      "Provider": "Illumina",
      "Dependencies": {
        "Resources": [
          {
            "Name": "nextflow",
            "Version": "24.10.5",
            "Provider": "Illumina"
          }
        ]
      },
      "Type": "NEXTFLOW"
    }
  ],
  "Resources": [
    {
      "Name": "dragen",
      "Version": "4.4.4",
      "Provider": "Illumina",
      "Type": "IMAGE"
    },
    {
      "Name": "nextflow",
      "Version": "24.10.5",
      "Provider": "Illumina",
      "Type": "IMAGE"
    }
  ]
}

Dry-Run

The dry-run command provides a quick way to validate input before running an application. It is best used while creating the input for an application, be it command line arguments or a JSON payload. The help command for an application creates the dry-run command for you as a starting point. The input can be command line arguments, or Standard Input. If no arguments are given, and nothing is sent to standard input, you will be prompted to manually enter the payload. Ctrl-d will end the input in this situation.

dragen-app-manager dry-run --provider Illumina --name SimpleApp --version 1.0.0 --inputDirectory input --outputDirectory output --environment TZ=EST --setting simple=config.json --resource opt=/opt --param.A B --param.Flag true --param.Count 1 --param.NumberString '"1532554234"'
 
dragen-app-manager dry-run < payload.json
 
cat payload.json | dragen-app-manager run

Run

This command accepts the same input as the dry-run command.

There are two ways to run an application from the command line. The first is strictly with command line arguments, the second is with a JSON payload.

Once the dry-run command has validated the input, replace "dry-run" with "run" to begin an analysis. This is an example of having run the dry-run command, setting the input and output directory, and removing arguments based on the documentation.

dragen-app-manager run --provider Illumina --name SimpleApp --version 1.0.0 --inputDirectory /staging/data/input --outputDirectory /staging/data/output --param.A B

Based on the arguments, a JSON payload representation looks like this. If you prefer to use JSON instead of command line arguments, Dragen Application Manager will have a JSON version of the input for every run. That topic will be covered later.

payload.json

{
    "Application": {
        "Name": "SimpleApp",
        "Version": "1.0.0",
        "Provider": "Illumina"
    },
    "InputDirectory": "/staging/data/input",
    "OutputDirectory": "/staging/data/output",
    "Params": {
        "A": "B"
    }
}

The payload.json can be redirected into the run command. See help for the run command for more usage details.

dragen-app-manager run < payload.json
 
cat payload.json | dragen-app-manager run

Dragen Native

Dragen Native requires that DRAGEN 4.4 is installed on the host operating system. In addition to this, a DRAGEN IRES must also be installed.

With the "--DRAGEN" command line option, the following can be used to run native DRAGEN commands.

dragen-app-manager run --version 4.4.4 --inputDirectory test/input --outputDirectory output --DRAGEN --build-hash-table true --ht-reference {{.InputDirectory}}/refdir/8/hg19_chrM.fa --output-directory {{.OutputDirectory}}

The above command line options are equivalent to this payload.

{
    "InputDirectory": "test/input",
    "OutputDirectory": "output",
    "Application": {
        "Version": "4.4.4"
    },
    "CommandArguments": [
        "--build-hash-table",
        "true",
        "--ht-reference",
        "{{.InputDirectory}}/refdir/8/hg19_chrM.fa",
        "--output-directory",
        "{{.OutputDirectory}}"
    ]
}

Run Status

dragen-app-manager run status

Without a specified ID, this command is used to determine if an application is currently running. It will return 0 if there is a current run, non-zero if there isn't.

With an ID specified, this command will return details about a specific run.

run status --id 1cef740d-8fa5-4316-9f37-5b41457cccc5 | jq

The result provides details about a run. Payload, Stdout, and Stderr are binary data.

{
  "Start": "2025-03-14T20:40:00.00Z",
  "End": "2025-03-14T20:45:00.00Z",
  "Status": "COMPLETED",
  "Input": {
    "Application": {
      "Name": "SimpleApp",
      "Version": "1.0.0",
      "Provider": "Illumina"
    },
    "Payload": "eyJBcHBs...",
    "InputDirectory": "/staging/data/input",
    "OutputDirectory": "/staging/data/output",
    "UserId": "1001",
    "GroupId": "1001",
    "GroupIds": [
      "1001",
      "10",
      "3241",
      "6252",
      "988"
    ]
  },
  "Id": "1cef740d-8fa5-4316-9f37-5b41457cccc5",
  "ContainerId": "9b637ec...",
  "Stdout": "CiBOIEUgWCB...",
  "Stderr": ""
}

Binary data is encoded in base64, and can be pulled out manually with jq and piped to base64; however this can also be done with additional arguments. When, instead of using the command line, it is preferable to use a JSON payload to run an application, the payload, and the data provided by the status, can be used as a starting point. To automatically decode binary data, three flags are available: stdout, stderr, and payload.

run status --id 1cef740d-8fa5-4316-9f37-5b41457cccc5 --stdout --stderr --payload

When decoding the payload, it serves as a JSON template that can be reused by changing the input and output directories.

{
  "Application": {
    "Name": "SimpleApp",
    "Version": "1.0.0",
    "Provider": "Illumina"
  },
  "InputDirectory": "input",
  "OutputDirectory": "output",
  "Params": {
    "A": "B"
  }
}

Run History

This provides a list of archived runs no longer in progress. You may refer to the help screen for the active default settings:

dragen-app-manager run history --help

The default behavior is to provide a list of archived runs, over a short period of time, with the latest at the end of the list. The duration of time as well as the sort order is configurable based on command line arguments, and all dates are based on the start time. If there are conflicting arguments, only one will be chosen.

dragen-app-manager run status list --last 8h
dragen-app-manager run status list --last-days 3
dragen-app-manager run status list --since 2024-12-01T00:00:00Z --until 2025-01-01T00:00:00Z
dragen-app-manager run status list --descending --limit 1
dragen-app-manager run status list --last 8h | jq

Stop

This provides a way for a user to prematurely terminate a running analysis. It is best to always let an analysis to run to completion; however, it can be used when a run must be stopped early. This command initates a safe shutdown, and may take up to 10 minutes (or possibly longer) to complete. It is always recommended to use this to stop an analysis.

dragen-app-manager stop

Troubleshooting

Log Files

Log files are located in "/var/log/dragen-app-manager/"

You may also see some logged information with journalctl or systemctl:

sudo tail -f /var/log/dragen-app-manager/dragen-app-manager.log
systemctl status dragen-app-manager
journalctl -u dragen-app-manager

Health Check /dev/log is Missing

This happens when the logging service on the Host OS is missing the log socket. If an error appears duing these steps, it's usually okay.

sudo systemctl restart systemd-journald-dev-log.socket
sudo systemctl restart systemd-journald.socket

Access Denied

You may see Access Denied messages if your user account does not have appropriate file permissions for:

• input directories

• output directories

• read access to the applications, and resources on the file system

• full access to the temp directory

• Docker socket

Work with an administrator to obtain the necessary file permissions.

Error: dial unix dragen-app-manager.sock: connect: no such file or directory

This may indicate a few things:

• Dragen App Manager is under maintenance and is temporarily stopped

• Dragen App Manager is not running for another reason

• The socket file was removed

In all the above cases, the remedy is to restart the service with

sudo systemctl restart dragen-app-manager

Cannot Run or Stop An Analysis

Dragen App Manager will only interact with a Docker container if it knows for certain that it was the creator. If it becomes necessary to reset everything related to running an analysis, follow this procedure:

sudo systemctl stop dragen-app-manager
docker container stop DragenAppManager
docker container rm DragenAppManager

If containers cannot be removed from Docker, restart the Docker services.

sudo systemctl restart containerd.socket docker.socket

Start the service and check the health.

sudo systemctl start dragen-app-manager
dragen-app-manager health | jq

DRAGEN License Not Found

This can occur when running an application using DRAGEN on a machine without a license dongle, or if missing a required license key.