# Seqera Docs > Complete reference documentation for Seqera Platform, Nextflow, MultiQC, Fusion, and Wave. Use this file for deep technical lookups across all Seqera products. It contains the full content of every documentation page, including API references, configuration options, and CLI commands. # Seqera Platform Enterprise > Documentation for Seqera Platform Enterprise. This file contains all documentation content in a single document following the llmstxt.org standard. ## Admin panel As a root user, you can access a comprehensive overview of the organizations, workspaces, users, and teams in your account from the **Admin panel**. It also includes tabs for application event audit logs, administrative statistics, and system configuration options. The root user system role should only be assigned to a system administrator as it provides high-level visibility and configuration access to your account. :::tip See [Basic configuration](../enterprise/configuration/overview.mdx#basic-configuration) to learn how to add root users to your Seqera Enterprise deployment with the `TOWER_ROOT_USERS` environment variable. ::: ## Organizations :::note From version 23.2, organization owners and root users can edit organization names on the **Edit organization** page. ::: The **Organizations** tab lists all the organizations in your account. - Use the search function to find an organization by name and perform various operations with that organization. - Select **Add organization** to create a new organization. - Select an organization name from the table to edit or delete it. See [Organizations](../orgs-and-teams/organizations) for more information. ### Members From an organization's page, select the **Members of organization** tab to view a list of its members. Here you can list and search for all members and owners of the organization, change a member's role, remove a member from the organization, or add a new member to the organization. You can only add existing users to an organization. You can't remove the last owner of an organization until you promote another member to **Owner** first. See [Members](../orgs-and-teams/organizations#members) for more information. ## Workspaces The **Workspaces** tab lists all the workspaces in your account. - Use the search function to find a workspace by name to view and edit that workspace. - Select **Add workspace** to create a new workspace. Choose a workspace name that isn't already in use. If the new workspace name already exists in the system, the creation will fail. After the workspace is created, it's listed in the **Workspaces** tab. - Select **Edit** next to a workspace name to edit or delete the workspace. See [Workspaces](../orgs-and-teams/workspace-management) for more information. ## Users The **Users** tab lists all the users in your account. - Select **Add user** to create a new user. If the new user email already exists in the system, the user creation will fail. After the user is created, inform them that access has been granted. - Use the search function to find a user by name or email. - Select a username from the list or select **Edit** to view and update the user's details. - To disable a user's Platform login access, select **Disable user**. This action does not delete the user. - To reinstate a disabled user's Platform login access, select **Allow login**. This option is grayed out for active users. See [User roles](../orgs-and-teams/roles) for more information on organization and workspace user access roles. ## Teams The **Teams** tab lists all the teams in your account. - Use the organizations drop-down next to the search bar to filter teams by organization. - Use the search function to find a team by name and perform various operations. - Select **Add team** to create a new team. - Select **Edit** next to a team to edit the team's details, or select **Delete** to delete it. From the teams list, you have an overview of the number of members and the unique ID of each team. Select **Edit** to view a team's page, or select the number next to **Members:** to go to the **Members** tab of the team page. From the **Members of team** tab, you can list and search for all users that are members of the selected team, change a user's role, remove a member from the team, or add a new member to the team. See [Teams](../orgs-and-teams/organizations#teams) for more information. ## Audit logs View application event [audit logs](../monitoring/audit-logs). ## Encryption With [secret key rotation](../enterprise/configuration/overview.mdx#secret-key-rotation) configured in your Enterprise instance, the **Encryption** tab displays the status of encryption tasks as they complete. Encryption tasks complete with one of three statuses: - **Success**: Secret encryption with the new secret key has completed successfully. - **Error**: Secret encryption has failed, usually due to corrupted or missing data. **Encrypted data ID** displays the path to the secret or credential. - **Orphaned**: While secret data has been successfully encrypted, the secret is orphaned in the Platform database. This means that this secret data exists in an encrypted state in your Platform database without a corresponding secret or credential ID in a Platform workspace. **Encrypted data ID** displays the unique identifier for the orphaned entry in your Platform database. --- ## Authentication The Seqera CLI uses your Seqera Platform account to authenticate you with Co-Scientist. This page covers how to log in and out, authenticate in automated environments, connect to your Enterprise backend, and how token refresh works. :::info[**Prerequisites**]{#prerequisites} You will need the following to get started: - [Seqera CLI](./installation.mdx) - A user account on your Seqera Platform Enterprise deployment ::: ## Log in To authenticate with your Seqera Platform account, run: ```bash seqera login ``` This will: 1. Open your default browser to the Seqera login page. 1. Prompt you to sign in with your Seqera Platform credentials. 1. Automatically capture the authentication token. 1. Display a success message in your terminal. ``` [Login] Starting Seqera CLI authentication... [Login] ✓ Authentication successful! [Login] ✓ Organization set: ``` ## View session status To view your current session status, use the `/status` command inside the TUI: ``` /status ``` This shows your authentication status and organization details. ## Log out To sign out from the current session, run: ```bash seqera logout ``` This command revokes your current authentication token and removes locally stored credentials. You will need to re-authenticate on next use. ## Organization management The Seqera CLI manages your organization selection for billing. Use the `seqera org` commands to view and switch organizations: - `seqera org`: View your current organization - `seqera org list`: List all organizations - `seqera org switch`: Switch organization - `seqera org clear`: Clear organization selection ## Token refresh The Seqera CLI automatically refreshes your authentication token when needed. You are not required to log in again unless: - You explicitly log out - Your refresh token expires (typically after extended inactivity) - Your Seqera Platform account permissions change ## Add access tokens for automation For automated environments, you can provide a Seqera Platform access token directly using the `SEQERA_ACCESS_TOKEN` environment variable: ```bash export SEQERA_ACCESS_TOKEN= seqera ai ``` When this environment variable is set, the CLI skips the OAuth login flow and uses the provided token directly. ## Connect to an Enterprise backend Set the following environment variables before starting `seqera ai`: | Variable | Purpose | Example value | | --- | --- | --- | | `SEQERA_AI_BACKEND_URL` | Co-Scientist backend endpoint used by the CLI | `https://ai-api.platform.example.com` | | `SEQERA_AUTH_DOMAIN` | OIDC authority base URL. The CLI fetches OpenID configuration from this URL and opens the discovered authorization endpoint in your browser. | `https://platform.example.com/api` | | `SEQERA_AUTH_CLI_CLIENT_ID` | OAuth client ID for the Seqera CLI | `seqera_ai_cli` | | `TOWER_ACCESS_TOKEN` | Platform personal access token used instead of browser login | `` | Use the OAuth login flow: ```bash export SEQERA_AUTH_DOMAIN=https://platform.example.com/api export SEQERA_AUTH_CLI_CLIENT_ID=seqera_ai_cli export SEQERA_AI_BACKEND_URL=https://ai-api.platform.example.com seqera ai ``` Use a Platform personal access token instead of browser login: ```bash export SEQERA_AUTH_DOMAIN=https://platform.example.com/api export TOWER_ACCESS_TOKEN= export SEQERA_AI_BACKEND_URL=https://ai-api.platform.example.com seqera ai ``` Set `SEQERA_AUTH_CLI_CLIENT_ID` only for OAuth deployments that use a non-default CLI client ID. Current CLI builds still require `SEQERA_AUTH_DOMAIN` for Enterprise token-based authentication so the CLI can target the correct Platform authority. ## Learn more - [Co-Scientist](index.md): Co-Scientist overview - [Installation](./installation.mdx): Install, update, and configure the CLI - [Command approval](./command-approval.md): Control which commands run automatically - [Use cases](./use-cases.md): Co-Scientist use cases - [Usage and cost](./usage-and-cost.md): Co-Scientist usage in Enterprise deployments - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Coding agents The `seqera skill` command installs a skill file that lets your coding agent use Co-Scientist as a subagent. Once installed, the agent can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. ## Supported agents Co-Scientist installs as a skill into any of the following agents. Each guide covers installation, update, and the available `seqera skill` options for that agent: - [Claude Code](./skill-claude-code.md): Install the skill for [Claude Code](https://claude.ai/code) - [Codex](./skill-codex.md): Install the skill for [Codex](https://openai.com/codex) - [GitHub Copilot](./skill-github-copilot.md): Install the skill for [GitHub Copilot](https://github.com/features/copilot) - [Other coding agents](./skill-other-agents.md): Install the skill for Cursor, OpenCode, Pi, Windsurf, and others --- ## Command approval Co-Scientist can execute local commands and edit files in your environment. This page explains approval modes that control which operations run automatically versus which require your permission, including dangerous commands, workspace boundaries, and best practices. :::info Starting a persistent task with `/goal ` switches the session to `full` approval mode automatically so Co-Scientist can continue working without repeated prompts. ::: ## Approval prompts When a command requires approval, you will see a prompt similar to: ``` APPROVAL REQUIRED (default mode) Command: rm -rf ./build/ [1] Yes, approve this command [2] Always approve this session [3] No, reject Press 1, 2, or 3 to choose ``` You can: - **1**: Run the command once (or press Enter) - **2**: Run the command and auto-approve all commands for the rest of the session - **3**: Reject the command (or press Escape) ## Approval modes Approval modes control which local commands Co-Scientist can execute automatically and which require your explicit approval. This provides a balance between convenience and safety when working with local files and commands. There are three approval modes: | Mode | Description | Best for | |------|-------------|----------| | **basic** | Only safe, read-only commands run automatically | Maximum security | | **default** | Safe commands and workspace file edits run automatically | Typical development | | **full** | Everything except dangerous commands runs automatically | Experienced users | You can set the approval mode when starting the CLI: ```bash seqera ai --approval-mode full ``` Or change it during a session using the `/approval` TUI command: ``` /approval basic ``` ### Basic **Rule**: Only safe, read-only commands run automatically. Everything else requires approval. This is the most restrictive mode. The assistant can only auto-execute commands that view information without making changes. **Auto-executes**: - `cat` - View file contents - `ls` - List directory contents - `pwd` - Show current directory - `head` - View file beginning - `tail` - View file end - `tree` - Display directory tree - `echo` - Print text (without file redirection) - `date` - Show current date/time - `whoami` - Show current user - `env` - Display environment variables - `printenv` - Print environment variables - `stat` - Show file status - `uptime` - Show system uptime **Requires approval**: All other commands, including file edits, directory creation, and any other command execution. Safe commands that include file redirections (e.g., `echo "hello" > file.txt`) also require approval. **Use when**: You want maximum control and visibility over every action the assistant takes. **Examples**: ``` > Create a new file called test.txt with "hello world" APPROVAL REQUIRED (basic mode) Command: Write ./test.txt [1] Yes, approve this command [2] Always approve this session [3] No, reject ``` ### Default **Rule**: Safe commands and file operations within your workspace run automatically. All other commands require approval. This is the recommended mode for most users. It allows productive workflow while protecting system files and preventing destructive operations. **Auto-executes**: - All safe commands from basic mode (without file redirections) - File edits **within your current workspace**: - Creating files (`touch`, file creation) - Editing files (text modifications) - Creating directories (`mkdir`) - Copying files (`cp` within workspace) - Moving files (`mv` within workspace) **Requires approval**: - File operations **outside your workspace** - All dangerous commands (see below) - Commands with file redirects to paths outside workspace - All other commands (e.g., `curl`, `wget`, `git`, `npm`, `python`, etc.) **Use when**: You're doing typical development work and want convenience without compromising safety. **Examples**: ``` > Create a new file called test.txt with "hello world" Created ./test.txt ``` File creation in the workspace runs automatically. ``` > Edit /etc/hosts APPROVAL REQUIRED (default mode) Command: Edit /etc/hosts [1] Yes, approve this command [2] Always approve this session [3] No, reject ``` Editing outside the workspace requires approval. ### Full **Rule**: Everything runs automatically except explicitly dangerous commands. This is the most permissive mode. Use it when you fully trust the assistant's actions and want minimal interruption. **Auto-executes**: All commands except those on the dangerous list. **Requires approval**: Only dangerous commands (see below). **Use when**: You're an experienced user comfortable with automated command execution, or when working in an isolated/disposable environment. ## Dangerous commands These commands **always require approval** in any mode: | Command | Risk | |---------|------| | `rm` | Delete files/directories | | `chmod` | Change file permissions | | `chown` | Change file ownership | | `kill` | Terminate processes | | `killall` | Terminate multiple processes | | `pkill` | Kill processes by name | | `sudo` | Execute as superuser | | `dd` | Low-level data operations | | `mount` | Mount filesystems | | `umount` | Unmount filesystems | | `mkfs` | Create filesystems | | `reboot` | Restart system | | `shutdown` | Power off system | **Examples**: ``` > Create files and directories as needed Created ./src/utils.py Created ./tests/test_utils.py Created ./config/settings.json ``` Most operations run without prompts. ``` > Delete the build directory APPROVAL REQUIRED (full mode) Command: rm -rf ./build/ [1] Yes, approve this command [2] Always approve this session [3] No, reject ``` Dangerous commands still require approval. ## Workspace boundaries In **default** mode, the "workspace" is your current working directory and its subdirectories. File operations are evaluated as: - **Inside workspace**: `/path/to/workspace/src/file.txt` - auto-executes - **Outside workspace**: `/etc/config` or `~/other-project/file.txt` - requires approval The workspace is set to your current directory when you start the CLI: ```bash # Workspace is /home/user/my-project cd /home/user/my-project seqera ai ``` ## Best practices - **Start with default mode**: It provides a good balance for most workflows - **Use basic mode for unfamiliar projects**: When exploring new codebases - **Reserve full mode for trusted contexts**: Disposable environments or well-understood tasks - **Review dangerous command prompts carefully**: These commands can have significant impact ## Learn more - [Co-Scientist](index.md): Co-Scientist overview - [Installation](./installation): Detailed installation instructions - [Authentication](./authentication): Log in, log out, and session management - [Use cases](./use-cases.md): Co-Scientist use cases - [Usage and cost](./usage-and-cost.md): Co-Scientist usage in Enterprise deployments - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Using Co-Scientist Use Co-Scientist day to day: explore common tasks, switch between modes, manage sessions, add skills, control command approval, and organize your workspace. ## In this section - [Use cases](./use-cases.md): Common tasks you can do, with example prompts - [Modes](./modes.md): Work in build, plan, and goal modes - [Sessions](./sessions.md): Start, continue, resume, and exit sessions, and run non-interactively - [Skills configuration](./skills.md): Discover, create, and install skills - [Command approval](./command-approval.md): Control which commands run automatically - [Code intelligence](./nextflow-lsp.md): Language-server support for Nextflow, Python, and R - [Projects](./projects.md): Organize workspace resources into projects using Platform labels - [Usage and cost](./usage-and-cost.md): Co-Scientist usage in Enterprise deployments --- ## Co-Scientist in Seqera CLI Co-Scientist is Seqera's AI assistant for bioinformatics. You interact with it through the [Seqera CLI](./installation.mdx) (`seqera ai`) to build, run, and debug Nextflow pipelines, manage your data, and drive Seqera Platform from a single terminal session. It combines self-service bioinformatics, conversational intelligence, and autonomous execution in one experience. Co-Scientist works across three contexts: - **Your Seqera Platform workspace**: View and manage workflows, pipelines, and data through your authenticated account. - **Your local environment**: Run commands and edit files in your working directory, with configurable approval controls. - **AI capabilities**: Natural language understanding, code generation, and intelligent suggestions. ## Get started To get started with Co-Scientist: 1. Install Seqera CLI: ```bash npm install -g seqera ``` 1. Log in to Seqera: ```bash seqera login ``` 1. Start your first session: ```bash seqera ai ``` See [Installation](./installation.mdx) for prerequisites, updates, and development builds. Then see [Quickstart](./quickstart.md) to walk through your first session. ## What you can do Co-Scientist helps across the full pipeline lifecycle, from writing code to running it on Seqera Platform: ### Develop pipelines Generate Nextflow configurations and pipeline schemas, convert scripts from other languages (WDL, R) to Nextflow, and discover over 1,000 nf-core modules with ready-to-run commands. Build reproducible Wave containers from conda or pip packages without writing a Dockerfile. Real-time LSP code intelligence detects errors and powers AI navigation across Nextflow, Python, and R files. ### Run and debug on Platform Launch, monitor, and debug Nextflow workflows from your terminal with real-time status, logs, and run metrics. Browse cloud storage through data links, manage datasets, generate upload and download URLs, and access reference genomes. Co-Scientist has full access to your compute environments, datasets, and workspace. ### Work your way Interact in plain English, or use reusable [skills](./skills.md) exposed as slash commands in the `/` palette. Switch between [build, plan, and goal modes](./modes.md) to match execution, analysis, or long-running tasks. Resume earlier sessions with `seqera ai -c`, and organize workspace resources into [projects](./projects.md) using Platform labels. ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Installation The Seqera CLI runs in your terminal on macOS, Linux, or Windows (via WSL). It connects to Seqera Platform and to the Co-Scientist backend in your Enterprise deployment so you can build, run, and debug Nextflow pipelines from a single interactive session. This page covers how to install, update, and uninstall the CLI with npm, how to switch to a development build, and how to point the CLI at the Co-Scientist backend. Once the CLI is on your PATH, see the [Quickstart](./quickstart.md) to log in and start your first session. :::info[**Prerequisites**]{#prerequisites} You will need the following to get started: - Node.js 18 or later - macOS, Linux, or Windows with WSL - A user account on your Seqera Platform Enterprise deployment - Network access to the Co-Scientist backend ::: ## Install the CLI Once Platform is installed with agent-backend and portal-web enabled, use the install endpoint to install the CLI: ```bash curl -fsSL https:///install | bash curl -fsSL https://ai.platform.example.com/install | bash ``` Then confirm the CLI is on your PATH: ```bash seqera --version ``` To install the CLI globally with npm, run: ```bash npm install -g seqera ``` Then confirm the CLI is on your PATH: ```bash seqera --version ``` ### Install a development build To install the latest pre-release, use the development channel: ```bash curl -fsSL https://ai.platform.example.com/install | bash -s -- --channel dev ``` To install the latest pre-release, run: ```bash npm install -g seqera@dev ``` The `@dev` tag tracks the latest pre-release CLI. Use it only to test unreleased features. Otherwise install the default tag. ## Update the CLI To update the CLI, run the install endpoint again. The install script updates the CLI in place: ```bash curl -fsSL https://ai.platform.example.com/install | bash ``` To update the CLI to the latest published version, run: ```bash npm update -g seqera ``` If you use Co-Scientist as a skill for a coding agent, sync your installed skills with the new CLI version after upgrading: ```bash seqera skill check --update ``` This scans both local and global installations by default. Pass `--global` or `--local` to narrow the scope. ## Uninstall the CLI To remove the CLI from your system, run: ```bash rm ~/.config/seqera-ai/* rm ~/.seqera/bin/seqera ``` To remove the CLI from your system, run: ```bash npm uninstall -g seqera ``` ## Configure the Co-Scientist backend To configure the Co-Scientist backend, set the backend URL before starting Co-Scientist: ```bash export SEQERA_AI_BACKEND_URL=https://ai-api.platform.example.com ``` If your Enterprise deployment uses Platform OIDC, also set the OIDC authority base URL: ```bash export SEQERA_AUTH_DOMAIN=https://platform.example.com/api ``` The CLI fetches OpenID configuration from this URL and opens the discovered authorization endpoint in your browser. See [Authentication](./authentication.md#connect-to-an-enterprise-backend) for the complete environment variable reference and OAuth versus token-based examples. ## Learn more - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Coding agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Usage and cost](./usage-and-cost.md): Co-Scientist usage in Enterprise deployments --- ## Modes Co-Scientist offers three modes that control how much autonomy it has in a session. Choose the right level for each task with [Build mode](#build-mode), [Plan mode](#plan-mode), and [Goal mode](#goal-mode). ## Build mode Build mode is the default interactive mode. Co-Scientist can: - Read and search files - Execute commands - Edit or create files - Carry out workflow changes directly in your workspace Use build mode for implementation work, debugging, code generation, and file edits. ## Plan mode Plan mode is optimized for analysis and implementation planning. In plan mode, Co-Scientist focuses on: - Understanding the problem - Comparing approaches and trade-offs - Producing a step-by-step implementation plan - Reading files and searching code for context Plan mode blocks write and execution tools, including: - `execute_bash_local` - `write_file_local` - `edit_file_local` - `create_directory_local` If the assistant tries to use one of these tools, the request is rejected and the assistant is told to switch back to build mode. For example: ```text Compare whether I should add FastQC or fastp as the first QC step in this RNA-seq pipeline, including the workflow changes each option would require ``` ```text Plan the work to add GPU support to this pipeline ``` ```text Inspect this repository and outline the changes needed for Seqera Platform deployment ``` ## Switch between build mode and plan mode Toggle modes during a session with `Shift+Tab`. You can also: - Check the current mode in the composer footer. - Run `/status` to view the current mode alongside session and LSP status. - Use `/help` to see mode-aware command guidance. ## Goal mode Goal mode is a persistent workflow for longer tasks. Set a goal with: ```bash /goal ``` For example: ```text /goal migrate this pipeline to DSL2 and add nf-tests ``` ```text /goal update this workflow for AWS Batch and verify the config ``` When goal mode is active, Co-Scientist: - Keeps working toward the same objective over multiple model attempts. - Automatically continues if more work is needed. - Stops when the goal is complete or the goal attempt limit is reached. - Switches approval mode to `full` so work can continue without repeated prompts. Goal mode commands: - `/goal` - `/goal off` Run `/goal` without arguments to inspect the current goal. Run `/goal off` to disable goal mode. Co-Scientist currently gives goal mode up to **3 model attempts** before it stops and asks you to start a new goal. ## Keyboard shortcuts | Shortcut | Action | |----------|--------| | `Shift+Tab` | Toggle between build mode and plan mode. | | Ctrl+Enter | If your terminal supports it, interrupt the current response and send a queued follow-up immediately. | | `Esc` | Clear a queued follow-up or interrupt the current response. | ## Learn more - [Sessions](./sessions.md): Start, continue, resume, and exit sessions - [Skills configuration](./skills.md): Discover, create, and install skills - [Command approval](./command-approval.md): Control which commands run automatically - [Use cases](./use-cases.md): Seqera CLI use cases - [Usage and cost](./usage-and-cost.md): Co-Scientist usage in Enterprise deployments - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Code intelligence When you ask Co-Scientist to help with code in your workspace, it uses language server (LSP) context to provide: - Explanations for errors and warnings in your code. - Context-aware completions and suggestions. - Better navigation and understanding across project files. For Nextflow projects, this includes diagnostics and code intelligence for scripts and config files. ## Language support | LSP Server | Extensions | Requirements | |------------|------------|--------------| | Nextflow | `.nf`, `.config` | Java 17+ installed | | Python (Pyright) | `.py`, `.pyi` | Auto-installs | | R | `.r`, `.R`, `.rmd`, `.Rmd` | R runtime installed | LSP servers automatically start when you work with files that match these extensions. ## Workspace detection Co-Scientist detects the relevant language context from your active workspace and applies matching intelligence automatically. This means you can move between Nextflow, Python, and R files in the same project and get language-aware assistance without manual setup. See [Nextflow Language Server](https://github.com/nextflow-io/language-server) for advanced configuration details. ## Learn more - [Co-Scientist](./index.md): Co-Scientist overview - [Quickstart](./quickstart.md): Start using Co-Scientist - [Use cases](./use-cases.md): Seqera CLI use cases - [Usage and cost](./usage-and-cost.md): Co-Scientist usage in Enterprise deployments - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Prerequisites ## Overview Everything you need to have in place before installing Co-Scientist. Complete these requirements, then proceed to the Bedrock Setup Guide to configure your AWS account. :::caution Co-Scientist requires Seqera Platform Enterprise 25.3.6 or later. It is currently only available on AWS. ::: Co-Scientist enables users to interact with Seqera Platform through a conversational AI interface, available through both the web (portal) and the CLI. The following components are deployed in sequence: | Order | Component | Purpose | | ----- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | MCP server | Model Context Protocol server providing Platform-aware tools (workflows, datasets, compute environments). Deploy first — the agent backend connects to it at startup. | | 2 | MySQL database | Dedicated database for session state and conversation history. | | 3 | Redis | Caching and session management layer for the agent backend. | | 4 | Agent backend | FastAPI service that orchestrates AI interactions between the CLI/web, Bedrock, and MCP. | | 5 | Portal web interface | Browser-based interface for Co-Scientist. | ## Platform - Co-Scientist is in Early Access for Platform Enterprise and may require an Enterprise version upgrade. [Contact Seqera support](https://support.seqera.io) for more information. - **OIDC** configured in Platform for authentication. ## AWS account Co-Scientist uses Claude models via [Amazon Bedrock](https://aws.amazon.com/bedrock/). You need an AWS account with Bedrock available in your chosen region. ### Models The following Bedrock model access must be enabled in your account: | Role | Model ID | Used for | | ------- | --------------------------- | ------------------------------- | | Primary | `anthropic.claude-sonnet-4-6` | General AI interactions | | Fast | `anthropic.claude-haiku-4-5-20251001-v1:0` | Quick tasks (search, summaries) | | Deep | `anthropic.claude-opus-4-6-v1` | Complex planning tasks | ## Database - **MySQL 8.0+** for Co-Scientist session state and conversation history. - A dedicated schema, separate from the Seqera Platform schema. - A dedicated database host is **recommended**. Co-locating the Co-Scientist schema on the Platform's MySQL host is technically supported, but a separate host isolates resource usage, maintenance windows, and backups across Seqera products. - You will need the hostname, database name, username, and password ready for Helm configuration. ## Redis - **Redis 7.2+ or Valkey 7.2+** for caching, session state, and the automations task queue. - Redis 8.x is supported (the search/JSON/bloom modules moved into core in Redis 8.0). - Valkey 7.2+ and 8.x are supported for the default caching and task-queue workload. If you enable the optional Redis-backed knowledge index (off by default), Redis Stack 7.x or Redis 8+ is required — Valkey does not ship the `RediSearch` module. - Accessible from your cluster. - You will need the hostname and port ready for Helm configuration. ## Networking and DNS Three domains are required, each serving a different component: | Component | Example domain | Purpose | | -------------------- | ----------------------------- | ----------------------------------- | | Agent backend | `ai-api.platform.example.com` | API endpoint for the CLI and portal | | MCP server | `mcp.platform.example.com` | Model Context Protocol server | | Portal web interface | `ai.platform.example.com` | Browser-based UI | - TLS certificates for all three domains. - Ingress controller configured in your cluster. ## Encryption key Generate a Fernet encryption key for encrypting sensitive tokens at rest: ```bash # using uv Python package manager (installed if not available) uv --version >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh uv run --with cryptography python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" # using Python directly, cryptography dependency module must be installed in environment python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" ``` Store this as a Kubernetes secret. It will be referenced as `AGENT_BACKEND_TOKEN_ENCRYPTION_KEY` in the Helm values (this is the default key the `agent-backend` chart reads from `tokenEncryptionKeyExistingSecretName`). ## Kubernetes secrets Store the following values as Kubernetes secrets before installing the chart. Do not inline them in `values.yaml`. | Secret | Contains | Used by | | ------------------------------- | ------------------------------------------------------------------------ | -------------- | | Database password | `AGENT_BACKEND_DB_PASSWORD` | Agent backend | | Redis password (if applicable) | `AGENT_BACKEND_REDIS_PASSWORD` | Agent backend | | Token encryption key | `AGENT_BACKEND_TOKEN_ENCRYPTION_KEY` | Agent backend | | Anthropic API key | `ANTHROPIC_API_KEY` (direct Anthropic path only) | Agent backend | | MCP JWT seed | `MCP_OAUTH_JWT_SECRET` 32+ char random string, `openssl rand -base64 32` | MCP server | | MCP initial access token | `MCP_OAUTH_INITIAL_ACCESS_TOKEN` (standalone MCP deploys only) | MCP server | When MCP is deployed as a subchart of the Platform parent chart, the initial access token is wired automatically from the Platform backend secret - you do not need to create it separately. When deploying MCP standalone, copy the value out of the Platform backend secret (typically named `-backend`, e.g. `platform-backend`, under the data key `OIDC_CLIENT_REGISTRATION_TOKEN`) into a new secret and reference it via `oidcToken.existingSecretName`. The MCP container loads this value as `MCP_OAUTH_INITIAL_ACCESS_TOKEN` at runtime. Bedrock authentication uses AWS IAM credentials and no API key secret is needed for the Bedrock path. On EKS, **EKS Pod Identity is the recommended approach** but IRSA or static AWS credentials on the pod are also supported. ## Local tooling - [Helm v3](https://helm.sh/docs/intro/install) - [kubectl](https://kubernetes.io/docs/tasks/tools/) - [AWS CLI v2.34.1+](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) ## Container images Co-Scientist container images are hosted at `cr.seqera.io`. The exact repository paths are defined by each component's Helm chart. See the chart READMEs for the authoritative `image.registry` / `image.repository` defaults and for vendoring guidance: | Image | Chart | | -------------------- | -------------------------------------------------------------------------------------------------------------- | | Agent backend | [agent-backend chart](https://github.com/seqeralabs/helm-charts/tree/master/charts/platform/charts/agent-backend) | | MCP server | [mcp chart](https://github.com/seqeralabs/helm-charts/tree/master/charts/platform/charts/mcp) | | Portal web interface | [portal-web chart](https://github.com/seqeralabs/helm-charts/tree/master/charts/platform/charts/portal-web) | Ensure your cluster can pull from `cr.seqera.io`, or if your cluster runs in a restricted network, mirror these images to your own registry. --- ## Projects Projects in Co-Scientist group the pipelines, datasets, and workflow runs that belong to a single piece of work, so you can view and chat about them without the noise of the rest of the workspace. Projects are not created inside Co-Scientist. They are derived from **workspace labels in Seqera Platform** whose names start with `project_`. Each matching label surfaces in Co-Scientist as a separate project scope, with the Platform label acting as the source of truth for membership. :::note Projects are part of the Co-Scientist web interface. The portal must be deployed alongside Co-Scientist in your Enterprise installation. See [Install Co-Scientist](../enterprise/install-seqera-coscientist.mdx) for more information. ::: ## How projects are derived When you open a workspace in the Co-Scientist web interface: 1. Co-Scientist reads the list of workspace labels from the Seqera Platform API. 2. Any label whose name starts with `project_` becomes a project. 3. An **Entire workspace** view is always included alongside your projects so you can see every resource in the workspace. 4. Pipelines, datasets, and workflow runs are scoped to a project by matching on its `project_*` label. Because membership lives on the Platform label, adding or removing a resource from a project is the same action as applying or removing the label in Platform. ## Create a project To create a project: 1. In **Seqera Platform**, open the workspace where the project should live. 2. Go to **Labels** in workspace settings and create a new label with the `project_` prefix. For example: - `project_rnaseq` - `project_variant_calling` - `project_chip_seq` 3. Apply the label to the pipelines and datasets that belong to the project. 4. Open Co-Scientist. The new project appears on the **Projects** page and in the chat project selector on the next page load. :::tip Create the label in workspace settings **before** applying it to resources. This ensures the label has a Platform-assigned ID, which Co-Scientist needs to auto-attach the label when you upload new datasets into the project. ::: ## Display names Co-Scientist strips the `project_` prefix to produce the display name shown in the web interface: | Platform label | Co-Scientist display name | |-----------------------|-------------------------| | `project_rnaseq` | Project rnaseq | | `project_wgs` | Project wgs | | `project_single_cell` | Project single_cell | Choose descriptive names after the prefix so projects are easy to identify. ## Where projects appear Once a `project_*` label exists in the workspace and is applied to at least one resource, the project is used in the following places: - **Projects page**: one row per project, plus the **Entire workspace** row. - **Project details page**: the pipelines, datasets, and workflow runs filtered to that project's label. - **Chat project selector**: scopes the resources the AI can see and act on during a chat session. - **Dataset upload**: when you upload a dataset from inside a project, the project's label is auto-attached. ## Edge cases ### A resource carries a `project_*` label that isn't in the workspace label list If a pipeline has a `project_*` label but the label has not been created in workspace settings, Co-Scientist still surfaces the project, inferred from the pipeline. In this case: - The project has no Platform-assigned label ID. - Dataset uploads into the project cannot auto-attach the label. To avoid this, always create `project_*` labels in workspace settings first, then apply them. ### No `project_*` labels in the workspace When a workspace has no `project_*` labels: - The **Projects** page shows a **No projects configured yet** empty state. - The project selector is hidden in the chat header. - The workspace view shows a header-only empty state. Ask a workspace admin to create the first `project_*` label to enable projects for the workspace. ## Learn more - [Seqera Platform labels](https://docs.seqera.io/platform-cloud/labels/overview): Create and manage workspace labels - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Usage and cost](./usage-and-cost.md): Co-Scientist usage in Enterprise deployments - [Install Co-Scientist](../enterprise/install-seqera-coscientist.mdx): Deploy the agent backend, MCP server, and web interface in Enterprise --- ## Quickstart This page walks you through your first Co-Scientist session: log in, start a session, switch between build mode and plan mode, debug a Platform run with a built-in skill, and set a long-running goal. :::info[**Prerequisites**]{#prerequisites} You will need the following to get started: - [Seqera CLI](./installation.mdx) - A user account on your Seqera Platform Enterprise deployment - `SEQERA_AI_BACKEND_URL` set to your organization's agent backend (see [Installation](./installation.mdx#configure-the-co-scientist-backend)) ::: ## Step 1: Log in to Seqera Platform Authenticate the CLI against your Seqera Platform account: ```bash seqera login ``` This will: 1. Open your default browser to the Seqera login page. 1. Prompt you to sign in with your Seqera Platform credentials. 1. Automatically capture the authentication token. 1. Display a success message in your terminal: ```console [Login] Starting Seqera CLI authentication... [Login] ✓ Authentication successful! [Login] ✓ Organization set: ``` :::tip See [Authentication](./authentication.md) for more information about how to log in and out, authenticate in automated environments, and manage your organization. ::: ## Step 2: Start an interactive session Launch an interactive Co-Scientist session: ```bash seqera ai ``` The Co-Scientist prompt appears, with a footer showing the active mode (**build** by default). See [Modes](./modes.md) for more information. ## Step 3: List commands and skills Show the built-in commands and available skills: ``` /help ``` :::tip Type `/` to open command autocomplete. ::: ## Step 4: Switch between build and plan modes Co-Scientist runs in two modes that control what it can do: - **Build mode** (default): Executes commands, edits files, and launches workflows - **Plan mode**: Read-only analysis and planning, for exploring options before making changes Press `Shift+Tab` to switch between modes. The active mode appears in the composer footer, and `/status` prints a full readout. Try plan mode with a comparison prompt: ``` Compare whether I should add FastQC or fastp as the first QC step in this RNA-seq pipeline, including the workflow changes each option would require ``` ## Step 5: Debug a Seqera Platform run Run the built-in debugging skill against your most recent workspace run: ``` /debug-last-run-on-seqera ``` Co-Scientist fetches your most recent workspace run, inspects logs and exit codes, and walks through likely causes and fixes. You need at least one workflow run in the workspace for this skill to find something to debug. ## Step 6: Set a long-running goal Give Co-Scientist a goal to work toward across multiple turns: ``` /goal update this pipeline for AWS Batch and add nf-tests ``` Co-Scientist works across model turns until the goal completes or the attempt limit is reached. See [Use cases](./use-cases.md) for more example prompts. ## Learn more - [Skills configuration](./skills.md): Discover, create, and install skills - [Modes](./modes.md): Build, plan, and goal modes in depth - [Use cases](./use-cases.md): Seqera CLI use cases - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## CLI Reference for the `seqera` commands used with Co-Scientist. To install the CLI, see [Installation](../installation.mdx). For the slash commands available inside a session, see [Skills](./skills-reference.md). ## seqera login Authenticate the CLI against your Seqera Platform account through a browser login. ```bash seqera login ``` ## seqera logout Sign out of the current session, revoke the authentication token, and remove locally stored credentials. ```bash seqera logout ``` ## seqera ai Start an interactive Co-Scientist session. Pass an optional initial query to begin with a prompt. ```bash seqera ai [query] [options] ``` | Option | Description | |--------|-------------| | `[query]` | Optional initial prompt to start the session with | | `-c` | Continue your most recent session | | `-s ` | Resume a specific session by ID | | `--approval-mode ` | Set the approval mode for local commands, for example `basic` or `full` (see [Command approval](../command-approval.md)) | | `--headless` | Run non-interactively and send output to stdout | | `--show-thinking` | Include thinking messages in headless output | | `--show-tools` | Include tool calls in headless output | | `--sub-agent` | Run as a subagent with structured JSONL output | See [Sessions](../sessions.md) for usage examples. ## seqera org Manage your organization selection for billing. | Command | Description | |---------|-------------| | `seqera org` | View your current organization | | `seqera org list` | List all organizations | | `seqera org switch` | Switch organization | | `seqera org clear` | Clear organization selection | ## seqera skill install Install Co-Scientist as a skill or instruction file for a coding agent. ```bash seqera skill install [options] ``` | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## seqera skill check Verify that an installed skill matches your current CLI version. ```bash seqera skill check [options] ``` | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## seqera --version Print the installed CLI version. ```bash seqera --version ``` ## Learn more - [Installation](../installation.mdx): Install, update, and configure the CLI - [Sessions](../sessions.md): Start, continue, resume, and exit sessions - [Coding agents](../coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./skills-reference.md): Built-in skills, slash commands, and session limits - [Environment variables](./environment-variables.md): Variables for authenticating and configuring the CLI --- ## Environment variables The Seqera CLI reads the following environment variables for authentication and for connecting to your Enterprise agent backend. | Variable | Description | | --- | --- | | SEQERA_ACCESS_TOKEN | Platform access token for non-interactive use. When set, the CLI skips the browser login flow and uses this token directly. | | SEQERA_AI_BACKEND_URL | Co-Scientist agent backend endpoint used by the CLI. | | SEQERA_AUTH_DOMAIN | OIDC authority base URL. The CLI fetches OpenID configuration from this URL and opens the discovered authorization endpoint in your browser. | | SEQERA_AUTH_CLI_CLIENT_ID | OAuth client ID for the Seqera CLI. | | TOWER_ACCESS_TOKEN | Platform personal access token used instead of browser login. | :::note `SEQERA_AI_BACKEND_URL` and `SEQERA_AUTH_DOMAIN` point the CLI at your Enterprise agent backend. See [Authentication](../authentication.md#connect-to-an-enterprise-backend) for OAuth and token-based setup. ::: ## Learn more - [Authentication](../authentication.md): Log in, log out, and manage tokens - [Installation](../installation.mdx): Install, update, and configure the CLI - [CLI](./cli.md): Seqera CLI commands and options - [Skills](./skills-reference.md): Built-in skills, slash commands, and session limits --- ## Reference Look up Seqera CLI commands, environment variables, and the built-in skills and slash commands available in a Co-Scientist session. ## In this section - [CLI](./cli.md): Seqera CLI commands and options - [Environment variables](./environment-variables.md): Variables for authenticating and configuring the CLI - [Skills](./skills-reference.md): Built-in skills, slash commands, and session limits --- ## Skills This page lists the slash commands and built-in skills available in a Co-Scientist session. To learn how to discover, author, and install skills, see [Skills configuration](../skills.md). ## Slash commands Co-Scientist exposes two kinds of slash command in the `/` palette. TUI commands are handled locally by the CLI to control the session itself: | Command | Description | |---------|-------------| | `/help` | Show available commands | | `/exit` (`/quit`, `/q`) | Exit the application | | `/clear` | Clear conversation history | | `/thinking` | Toggle thinking display | | `/scroll` | Toggle auto-scroll | | `/org` | Show current organization | | `/lsp` | Show LSP server status | | `/status` | Show system status | | `/credits` | Show Enterprise usage ownership and administrator contact guidance | | `/approval` | Show or set approval mode | | `/feedback` | Open feedback form | | `/help-community` | Open community help | | `/stickers` | Get Seqera stickers | The second kind, AI commands, are backed by skills and sent to the AI backend. The built-in ones are listed below, and any skills your deployment exposes appear alongside them in `/` and `/help`. ## Built-in skills Your Co-Scientist deployment can expose built-in skills as slash commands. These appear in the `/` command palette and in `/help`. The CLI includes the following built-in skills by default: | Command | Description | |---------|-------------| | `/nextflow-config` | Generate and explain Nextflow configuration files | | `/nextflow-schema` | Generate `nextflow_schema.json` and sample sheet schema files | | `/debug-local-run` | Debug a local Nextflow pipeline run using `.nextflow.log`, work directories, and related artifacts | | `/debug-last-run-on-seqera` | Debug the last pipeline run on Seqera Platform | | `/convert-jupyter-notebook` | Convert Jupyter notebooks to Nextflow pipelines | | `/convert-python-script` | Convert Python scripts, including standalone scripts and Snakemake-style logic, to Nextflow | | `/convert-r-script` | Convert R scripts to Nextflow pipelines | | `/migrate-from-wdl` | Convert WDL to Nextflow | | `/write-nf-test` | Write nf-tests for your pipeline | | `/fix-strict-syntax` | Fix Nextflow strict syntax errors and help migrate pipelines to the v2 parser | | `/nf-aggregate` | Aggregate metrics from Nextflow runs on Seqera Platform using the `nf-aggregate` pipeline | | `/nf-data-lineage` | Explore Nextflow data lineage to trace which inputs and processes produced a result | | `/nf-pipeline-structure` | Analyze a local Nextflow pipeline structure, including processes, workflows, modules, and channel flow | | `/nf-run-history` | Analyze local Nextflow run history and summarize recent activity, progress, and recurring issues | | `/nf-schema-migration` | Migrate Nextflow pipelines from `nf-validation` to `nf-schema` v2 | | `/seqera-mcp` | Access Seqera Platform through MCP tools for structured, validated operations | | `/seqera-platform-api` | Query and manipulate Seqera Platform resources directly through the REST API | | `/seqerakit` | Write `seqerakit` YAML configuration for automating Seqera Platform setup | | `/simplify` | Review changed code for reuse, quality, and efficiency, then clean up issues found | :::note The exact built-in skills available in your environment may vary by deployment and release. Use `/help` or type `/` in the CLI to see the current list. ::: ## Payload limits To keep session payloads small, Co-Scientist caps discovered skill context at **5 KB**. The total session payload cap is **20 KB**. ## Learn more - [Installation](../installation.mdx): Install, update, and configure the CLI - [Quickstart](../quickstart.md): Run your first Co-Scientist session - [Authentication](../authentication.md): Log in, log out, and manage sessions - [Use cases](../use-cases.md): Seqera CLI use cases - [Using Co-Scientist](../configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](../coding-agents.md): Install Co-Scientist as a skill in your coding agent --- ## Sessions A session is one interactive conversation with Co-Scientist. Co-Scientist preserves your conversation history, so you can resume earlier sessions to continue your work. This page covers how to start, continue, and exit sessions, and how to run non-interactively. ## Start a session Launch an interactive session: ```bash seqera ai ``` Start with an initial query: ```bash seqera ai "list my pipelines" ``` Set the approval mode for local commands at launch: ```bash seqera ai --approval-mode full ``` See [Command approval](./command-approval.md) for the available modes. ## Continue or resume a session Continue your most recent session: ```bash seqera ai -c ``` Continue with a follow-up question: ```bash seqera ai -c "now run the pipeline with the test profile" ``` Resume a specific session by ID: ```bash seqera ai -s ``` ## Run in headless mode Run Co-Scientist in headless mode for scripting and automation. Output is sent to stdout instead of the interactive TUI. Run a query and pipe the output: ```bash seqera ai --headless "list my pipelines" ``` Include thinking messages in the output: ```bash seqera ai --headless --show-thinking "debug my pipeline" ``` Include tool calls in the output: ```bash seqera ai --headless --show-tools "list my workflows" ``` :::note Headless mode is also auto-detected when stdout is piped, for example `seqera ai "query" | grep "result"`. ::: ## Exit a session - Type `/exit`, `/quit`, or `/q` - Press `Ctrl+C` Your conversation history is preserved, so you can resume later with `seqera ai -c`. ## Learn more - [Modes](./modes.md): Work in build, plan, and goal modes - [Command approval](./command-approval.md): Control which commands run automatically - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Claude Code The `seqera skill` command installs a skill file that enables [Claude Code](https://claude.ai/code) to use Co-Scientist as a subagent. Once installed, Claude Code can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. This page covers how to install the skill into Claude Code and keep it in sync as you update the CLI. ## `seqera skill install` Use `seqera skill install` to add the Co-Scientist skill to Claude Code. Run it without options to launch an interactive installer that detects your setup and prompts for a location, or pass a flag to install directly to a specific path. Launch the interactive installer: ```bash seqera skill install ``` Install to the standard Claude Code location: ```bash seqera skill install --path .claude/skills/ ``` Install into the current repository root: ```bash seqera skill install --local ``` Or install to your home directory: ```bash seqera skill install --global ``` You can also auto-detect and update an existing installation: ```bash seqera skill install --detect ``` ### Usage ```bash seqera skill install [OPTIONS] ``` ### Options `seqera skill install` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## `seqera skill check` The skill file is tied to the version of the CLI that created it, so it can fall out of date when you upgrade. Use `seqera skill check` to confirm your installed skill still matches your current CLI version, and update it when it doesn't. Verify that your installed skill matches your current CLI version: ```bash seqera skill check ``` Update automatically if needed: ```bash seqera skill check --update ``` ### Usage ```bash seqera skill check [OPTIONS] ``` ### Options `seqera skill check` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Codex The `seqera skill` command installs a skill file that enables [Codex](https://openai.com/codex) to use Co-Scientist as a subagent. Once installed, Codex can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. This page covers how to install the skill into Codex and keep it in sync as you update the CLI. ## `seqera skill install` Use `seqera skill install` to add the Co-Scientist skill to Codex. Run it without options to launch an interactive installer that detects your setup and prompts for a location, or pass a flag to install directly to a specific path. Launch the interactive installer: ```bash seqera skill install ``` Install to your project `AGENTS.md` path: ```bash seqera skill install --path AGENTS.md ``` Install into the current repository root and let the CLI select the Codex format automatically: ```bash seqera skill install --local ``` Or install to your home directory: ```bash seqera skill install --global ``` You can also auto-detect and update an existing installation: ```bash seqera skill install --detect ``` ### Usage ```bash seqera skill install [OPTIONS] ``` ### Options `seqera skill install` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## `seqera skill check` The skill file is tied to the version of the CLI that created it, so it can fall out of date when you upgrade. Use `seqera skill check` to confirm your installed skill still matches your current CLI version, and update it when it doesn't. Verify that your installed skill matches your current CLI version: ```bash seqera skill check ``` Update automatically if needed: ```bash seqera skill check --update ``` ### Usage ```bash seqera skill check [OPTIONS] ``` ### Options `seqera skill check` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## GitHub Copilot The `seqera skill` command installs a skill file that enables [GitHub Copilot](https://github.com/features/copilot) to use Co-Scientist as a subagent. Once installed, GitHub Copilot can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. This page covers how to install the skill into GitHub Copilot and keep it in sync as you update the CLI. ## `seqera skill install` Use `seqera skill install` to add the Co-Scientist skill to GitHub Copilot. Run it without options to launch an interactive installer that detects your setup and prompts for a location, or pass a flag to install directly to a specific path. Launch the interactive installer: ```bash seqera skill install ``` Install to the standard Copilot instructions file: ```bash seqera skill install --path .github/copilot-instructions.md ``` Install into the current repository root: ```bash seqera skill install --local ``` Or install to your home directory: ```bash seqera skill install --global ``` You can also auto-detect and update an existing installation: ```bash seqera skill install --detect ``` ### Usage ```bash seqera skill install [OPTIONS] ``` ### Options `seqera skill install` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## `seqera skill check` The skill file is tied to the version of the CLI that created it, so it can fall out of date when you upgrade. Use `seqera skill check` to confirm your installed skill still matches your current CLI version, and update it when it doesn't. Verify that your installed skill matches your current CLI version: ```bash seqera skill check ``` Update automatically if needed: ```bash seqera skill check --update ``` ### Usage ```bash seqera skill check [OPTIONS] ``` ### Options `seqera skill check` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Other coding agents The `seqera skill` command installs a skill file that enables coding agents such as [Cursor](https://www.cursor.com/), [OpenCode](https://opencode.ai/), [Pi](https://github.com/badlogic/pi-mono), and [Windsurf](https://windsurf.com/) to use Co-Scientist as a subagent. Once installed, these agents can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. This page covers the agents the CLI supports, how to install the skill into one of them, and how to keep it in sync as you update the CLI. ## Supported agents The CLI can install the skill into the following agents, each in the format that agent expects: | Agent | Format | |-------|--------| | [Cursor](https://www.cursor.com/) | `.cursor/rules/` | | [OpenCode](https://opencode.ai/) | `.opencode/` | | [Pi](https://github.com/badlogic/pi-mono) | `.pi/` | | [Windsurf](https://windsurf.com/) | `.windsurf/rules/` | ## `seqera skill install` Use `seqera skill install` to add the Co-Scientist skill to your coding agent. Run it without options to launch an interactive installer that detects your setup and prompts for a location, or pass a flag to install directly to a specific path. Launch the interactive installer: ```bash seqera skill install ``` Install to a specific agent path: ```bash seqera skill install --path ``` Install into the current repository root: ```bash seqera skill install --local ``` Or install to your home directory: ```bash seqera skill install --global ``` You can also auto-detect and update an existing installation: ```bash seqera skill install --detect ``` ### Usage ```bash seqera skill install [OPTIONS] ``` ### Options `seqera skill install` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## `seqera skill check` The skill file is tied to the version of the CLI that created it, so it can fall out of date when you upgrade. Use `seqera skill check` to confirm your installed skill still matches your current CLI version, and update it when it doesn't. Verify that your installed skill matches your current CLI version: ```bash seqera skill check ``` Update automatically if needed: ```bash seqera skill check --update ``` ### Usage ```bash seqera skill check [OPTIONS] ``` ### Options `seqera skill check` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Skills configuration Skills are reusable instruction sets that extend Co-Scientist with domain-specific workflows, prompts, and operating guidance. Co-Scientist supports two skill workflows: - **Session skills**: `SKILL.md` files discovered from project and user skill directories and sent to the Co-Scientist backend as session context when you run `seqera ai` - **Agent integrations**: skill files installed by `seqera skill install` so other coding agents can invoke Co-Scientist as a subagent :::tip See [Skills](./reference/skills-reference.md) for a list of the available built-in skills and slash commands. ::: ## Use skills in the CLI When you start `seqera ai`, the CLI discovers available skills automatically. Backend-provided skills are also exposed as slash commands in the `/` command palette and `/help`. You can: - Type `/` to browse built-in commands and backend skills - Run `/help` to see commands and skill descriptions in the terminal - Add project-specific `SKILL.md` files so Co-Scientist starts each session with the right context ## Skill format Each skill lives in its own directory and includes a `SKILL.md` file with YAML frontmatter: ```text my-skill/ SKILL.md references/ ``` ```markdown --- name: my-skill description: Short description of what this skill does --- Detailed instructions, examples, and guidelines. ``` `name` and `description` are required. Skills missing either field are skipped. ## Discovery directories Co-Scientist searches these directories in order. The first directory to register a skill name takes precedence, and later skills with the same name are ignored. | Priority | Path | Scope | |----------|------|-------| | 1 | `/.agents/skills/` | project | | 2 | `/.seqera/skills/` | project | | 3 | `~/.agents/skills/` | user | | 4 | `~/.seqera/skills/` | user | | 5 | `~/.config/agents/skills/` | user | | 6 | `~/.config/seqera/skills/` | user | Project skills take priority over user skills, so you can override a global skill with a repository-specific version. ### Cross-agent compatibility `.agents/skills/` follows the [Agent Skills](https://agentskills.io) convention, which makes skills portable across coding agents. `.seqera/skills/` is Seqera-specific. ## Install skills into Co-Scientist You can add skills by creating the directory structure manually or by installing them from the [Agent Skills](https://agentskills.io) ecosystem: ```bash npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices ``` After adding a skill, restart `seqera ai` so the new skill is loaded into the session. ## Install Co-Scientist into coding agents Co-Scientist can install itself as a skill or instruction file so another coding agent can invoke it as a subagent. See [Coding agents](./coding-agents.md) for the supported agents and the `seqera skill install` and `seqera skill check` commands. ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Usage and cost Co-Scientist in Seqera Platform Enterprise runs in your self-hosted environment and uses your configured inference provider for Claude model access. Enterprise deployments do not use Seqera Cloud credit balances or the Cloud credit request flow. Instead, your organization manages inference access, limits, and costs through AWS Bedrock or Anthropic API. AWS Bedrock is recommended for Enterprise deployments. ## What users see In Enterprise deployments, Co-Scientist does not enforce Seqera Cloud credit balances. If your session is blocked because of usage limits, contact your Seqera Platform administrator. The administrator can verify the agent backend configuration and inference provider account. ## What administrators manage Administrators should manage: - AWS Bedrock model access, inference profiles, quotas, and IAM roles, when Bedrock is used. - Anthropic API keys, usage limits, and billing, when direct Anthropic API access is used. - Amazon Titan embedding access, if improved documentation search is enabled. - Any organization-specific policies for Co-Scientist availability. For deployment configuration, see [Co-Scientist](../enterprise/install-seqera-coscientist.mdx). ## Learn more - [Co-Scientist in the Seqera CLI](./index.md): Co-Scientist overview - [Authentication](./authentication.md): Log in, log out, and session management - [Use cases](./use-cases.md): Seqera CLI use cases --- ## Use cases Co-Scientist is an AI assistant for building, running, and managing bioinformatics workflows, available through the Seqera CLI. The sections below walk through common tasks with example prompts you can adapt to your own work: - [Develop and debug Nextflow pipelines](#develop-and-debug-nextflow-pipelines): Understand pipeline structure, generate config and schema files, debug runs, and convert scripts to Nextflow. - [Run pipelines on Seqera Platform](#run-pipelines-on-seqera-platform): Launch, monitor, and debug workflow runs in your workspace. - [Build containers with Wave](#build-containers-with-wave): Create containers from conda or pip packages without writing a Dockerfile. - [Work with data](#work-with-data): Browse data links, move files, and find reference datasets. - [Discover and run nf-core modules](#discover-and-run-nf-core-modules): Search over 1,000 nf-core modules and generate ready-to-run commands. - [Edit local project files](#edit-local-project-files): Make AI-assisted edits to files in your working directory. ## Develop and debug Nextflow pipelines Co-Scientist helps you develop, debug, and understand Nextflow pipelines with AI-powered analysis and code generation. The examples below are prompts you can adapt to your own pipeline. ### Understand your pipeline structure ``` > Show me the structure of main.nf ``` ``` > What processes are defined in this pipeline? ``` ``` > /nf-pipeline-structure ``` ### Generate configuration files ``` > /nextflow-config ``` ### Debug your pipeline ``` > /debug ``` ``` > Why is my pipeline failing? ``` ### Review local execution history ``` > /nf-run-history ``` Trace output provenance with data lineage: ``` > /nf-data-lineage ``` ### Generate schema files ``` > /nextflow-schema ``` ### Convert scripts to Nextflow ``` > /convert-python-script ``` ### Fix strict syntax ``` > /fix-strict-syntax ``` ### Migrate old schema definitions ``` > /nf-schema-migration ``` ## Run pipelines on Seqera Platform Use Seqera Platform capabilities to run and manage workflows at scale with AI assistance. The examples below are prompts you can adapt to your own workspace. ### List your workflows ``` > List my recent workflows ``` ### Launch a pipeline ``` > Launch the nf-core/rnaseq pipeline with the test profile ``` ### Debug failed runs ``` > Why did my last workflow fail? ``` ``` > Get the logs for the failed task in my last run ``` ### Debug your most recent run ``` > /debug-last-run-on-seqera ``` ## Build containers with Wave Co-Scientist can create containerized environments using Wave, without the need to write Dockerfiles. The examples below are prompts you can adapt to your own tools. ### Create a container with conda packages ``` > Create a container with samtools and bwa from bioconda ``` ### Create a container with pip packages ``` > Build a container with pandas, numpy, and scikit-learn ``` ### Get a container for a specific tool ``` > I need a container with FastQC version 0.12.1 ``` :::note Co-Scientist generates a Wave container URL that you can use directly in your Nextflow pipelines or pull with Docker. ::: ## Work with data Co-Scientist helps you manage data through Platform data links and access reference datasets. The examples below are prompts you can adapt to your own data. ### Browse data links ``` > List my data links ``` ``` > Show me the contents of my S3 data link ``` ### Download and upload files ``` > Generate a download URL for results/final_report.html ``` ``` > Upload my local results to the data link ``` ### Access reference data ``` > Find the human reference genome GRCh38 ``` ``` > Search for RNA-Seq test data ``` ## Discover and run nf-core modules Co-Scientist provides access to over 1,000 nf-core modules for common bioinformatics tasks. The examples below are prompts you can adapt to your own analysis. ### Search for modules ``` > Find nf-core modules for sequence alignment ``` ``` > What modules are available for variant calling? ``` ### Get module details ``` > Show me how to use the nf-core/bwa/mem module ``` ### Run a module ``` > Run FastQC on my FASTQ files ``` :::note Co-Scientist can generate the exact Nextflow command with the correct parameters for your data. ::: ## Edit local project files Co-Scientist can interact with files in your current working directory. The examples below are prompts you can adapt to your own project. ### Start from your project folder ```bash cd /path/to/your/project seqera ai ``` ### Ask for help with local tasks ``` > Show me the structure of main.nf ``` ``` > Add a new process to handle quality control ``` :::note Local file operations are controlled by [approval modes](./command-approval.md#approval-modes). By default, Co-Scientist asks for your approval before making changes outside your working directory or running potentially dangerous commands. ::: ## Learn more - [Modes](./modes.md): Work in build, plan, and goal modes - [Skills configuration](./skills.md): Discover, create, and install skills - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Command approval](./command-approval.md): Control which commands run automatically - [Code intelligence](./nextflow-lsp.md): Language-server support for Nextflow, Python, and R - [Projects](./projects.md): Organize workspace resources into projects using Platform labels --- ## AWS Batch :::tip This guide assumes you have an existing [Amazon Web Service (AWS)](https://aws.amazon.com/) account. The AWS Batch service quota for job queues is 50 per account. For more information on AWS Batch service quotas, see [AWS Batch service quotas](https://docs.aws.amazon.com/batch/latest/userguide/service_limits.html). ::: There are two ways to create a Seqera Platform compute environment for AWS Batch: - [**Automatically**](#automatic-configuration-of-batch-resources): this option lets Seqera automatically create the required AWS Batch resources in your AWS account, using an internal tool within Seqera Platform called "Forge". This removes the need to set up your AWS Batch infrastructure manually. Resources can also be automatically deleted when the compute environment is removed from Platform. - [**Manually**](#manual-configuration-of-batch-resources): this option lets Seqera use existing AWS Batch resources previously created. Both options require specific IAM permissions to function correctly, as well as access to an S3 bucket or EFS/FSx file system to store intermediate Nextflow files. ## S3 bucket creation AWS S3 (Simple Storage Service) is a type of **object storage**. To access input and output files using Seqera products like [Studios](../studios/overview) and [Data Explorer](../data/data-explorer) create one or more **S3 buckets**. An S3 bucket can also be used to store intermediate results of your Nextflow pipelines, as an alternative to using EFS or FSx file systems. :::note Using EFS or FSx as work directory is incompatible with Studios. ::: 1. Navigate to the [AWS S3 console](https://console.aws.amazon.com/s3/home). 1. In the top right of the page, select the same region where you plan to create your AWS Batch compute environment. 1. Select **Create bucket**. 1. Enter a unique name for your bucket. 1. Leave the rest of the options as default and select **Create bucket**. :::note S3 can be used by Nextflow for the storage of intermediate files. In production pipelines, this can amount to a lot of data. To reduce costs, consider using a retention policy when creating a bucket, such as automatically deleting intermediate files after 30 days. See the [AWS documentation](https://aws.amazon.com/premiumsupport/knowledge-center/s3-empty-bucket-lifecycle-rule/) for more information. ::: ## EFS or FSx file system creation [AWS Elastic File System (EFS)](https://aws.amazon.com/efs/) and [AWS FSx for Lustre](https://aws.amazon.com/fsx/lustre/) are types of **file storage** that can be used as a Nextflow work directory to store intermediate files, as an alternative to using S3 buckets. :::note Using EFS or FSx as work directory is incompatible with Studios. ::: To use EFS or FSx as your Nextflow work directory, create an EFS or FSx file system in the same region where you plan to create your AWS Batch compute environment. The creation of an EFS or FSx file system can be done automatically by Seqera when creating the AWS Batch compute environment, or manually by following the steps below. If you let Seqera create the file system automatically, it will also be deleted when the compute environment is removed from Platform, unless the "Dispose Resources" option is disabled in the advanced options. ### Creating an EFS file system To create a new EFS file system manually, visit the [EFS console](https://console.aws.amazon.com/efs/home). 1. Select **Create file system**. 1. Optionally give it a name, then select the VPC where your AWS Batch compute environment will be created. 1. Leave the rest of the options as default and select **Create file system**. ### Creating an FSx file system To create a new FSx for Lustre file system manually, visit the [FSx console](https://console.aws.amazon.com/fsx/home). 1. Select **Create file system**. 1. Select FSx for Lustre 1. Follow the prompts to configure the file system according to your requirements, then select **Next**. 1. Review the configuration and select **Create file system**. Make sure the [Lustre client](https://docs.aws.amazon.com/fsx/latest/LustreGuide/install-lustre-client.html) is available in the AMIs used by your AWS Batch compute environment to allow mounting FSx file systems. ## Required Platform IAM permissions To create and launch pipelines, explore buckets with Data Explorer or run Studio sessions with the AWS Batch compute environment, an IAM user with specific permissions must be provided. Some permissions are mandatory for the compute environment to be created and function correctly, while others are optional and used for example to provide list of values to pick from in the Platform UI. Permissions can be attached directly to an [IAM user](#iam-user-creation), or to an [IAM role](#iam-role-creation-optional) that the IAM user can assume when accessing AWS resources. A permissive and broad policy with all the required permissions is provided here for a quick start. However, we recommend following the principle of least privilege and only granting the necessary permissions for your use case, as shown in the following sections.
Full permissive policy (for reference) ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "BatchEnvironmentManagementCanBeRestricted", "Effect": "Allow", "Action": [ "batch:CreateComputeEnvironment", "batch:CreateJobQueue", "batch:DeleteComputeEnvironment", "batch:DeleteJobQueue", "batch:TagResource", "batch:UpdateComputeEnvironment", "batch:UpdateJobQueue" ], "Resource": [ "arn:aws:batch:*:*:compute-environment/TowerForge-*", "arn:aws:batch:*:*:job-queue/TowerForge-*" ] }, { "Sid": "BatchEnvironmentListing", "Effect": "Allow", "Action": [ "batch:DescribeComputeEnvironments", "batch:DescribeJobDefinitions", "batch:DescribeJobQueues", "batch:DescribeJobs" ], "Resource": "*" }, { "Sid": "BatchJobsManagementCanBeRestricted", "Effect": "Allow", "Action": [ "batch:CancelJob", "batch:RegisterJobDefinition", "batch:SubmitJob", "batch:TagResource", "batch:TerminateJob" ], "Resource": [ "arn:aws:batch:*:*:job-definition/*", "arn:aws:batch:*:*:job-queue/TowerForge-*", "arn:aws:batch:*:*:job/*" ] }, { "Sid": "LaunchTemplateManagement", "Effect": "Allow", "Action": [ "ec2:CreateLaunchTemplate", "ec2:DeleteLaunchTemplate", "ec2:DescribeLaunchTemplates", "ec2:DescribeLaunchTemplateVersions" ], "Resource": "*" }, { "Sid": "PassRolesToBatchCanBeRestricted", "Effect": "Allow", "Action": "iam:PassRole", "Resource": "*", "Condition": { "StringEquals": { "iam:PassedToService": [ "batch.amazonaws.com", "ec2.amazonaws.com" ] } } }, { "Sid": "CloudWatchLogsAccessCanBeRestricted", "Effect": "Allow", "Action": [ "logs:Describe*", "logs:FilterLogEvents", "logs:Get*", "logs:List*", "logs:StartQuery", "logs:StopQuery", "logs:TestMetricFilter" ], "Resource": "*" }, { "Sid": "OptionalS3PlatformDataAccessCanBeRestricted", "Effect": "Allow", "Action": [ "s3:Get*", "s3:List*", "s3:PutObject" ], "Resource": "*" }, { "Sid": "OptionalIAMManagementCanBeRestricted", "Effect": "Allow", "Action": [ "iam:AddRoleToInstanceProfile", "iam:AttachRolePolicy", "iam:CreateInstanceProfile", "iam:CreateRole", "iam:DeleteInstanceProfile", "iam:DeleteRole", "iam:DeleteRolePolicy", "iam:DetachRolePolicy", "iam:GetRole", "iam:ListAttachedRolePolicies", "iam:ListRolePolicies", "iam:PutRolePolicy", "iam:RemoveRoleFromInstanceProfile", "iam:TagInstanceProfile", "iam:TagRole" ], "Resource": [ "arn:aws:iam::*:role/TowerForge-*", "arn:aws:iam::*:instance-profile/TowerForge-*" ] }, { "Sid": "OptionalFetchOptimizedAMIMetadata", "Effect": "Allow", "Action": "ssm:GetParameters", "Resource": "arn:aws:ssm:*:*:parameter/aws/service/ecs/*" }, { "Sid": "OptionalEC2MetadataDescribe", "Effect": "Allow", "Action": [ "ec2:DescribeAccountAttributes", "ec2:DescribeImages", "ec2:DescribeInstanceTypeOfferings", "ec2:DescribeInstanceTypes", "ec2:DescribeKeyPairs", "ec2:DescribeSecurityGroups", "ec2:DescribeSubnets", "ec2:DescribeVpcs" ], "Resource": "*" }, { "Sid": "OptionalFSXManagementCanBeRestricted", "Effect": "Allow", "Action": [ "fsx:CreateFileSystem", "fsx:DeleteFileSystem", "fsx:DescribeFileSystems", "fsx:TagResource" ], "Resource": "*" }, { "Sid": "OptionalEFSManagementCanBeRestricted", "Effect": "Allow", "Action": [ "elasticfilesystem:CreateFileSystem", "elasticfilesystem:DeleteFileSystem", "elasticfilesystem:CreateMountTarget", "elasticfilesystem:DeleteMountTarget", "elasticfilesystem:DescribeFileSystems", "elasticfilesystem:DescribeMountTargets", "elasticfilesystem:UpdateFileSystem", "elasticfilesystem:PutLifecycleConfiguration", "elasticfilesystem:TagResource" ], "Resource": "*" }, { "Sid": "OptionalPipelineSecretsListing", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" }, { "Sid": "OptionalPipelineSecretsManagementCanBeRestricted", "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:DeleteSecret", "secretsmanager:CreateSecret" ], "Resource": "arn:aws:secretsmanager:*:*:secret:tower-*" } ] } ```
### AWS Batch management The first section of the policy allows Seqera to create, update and delete Batch compute environments ("CE"), job queues ("JQ") and jobs. If you are required to use manually created CEs and JQs or prefer to manage their lifecycle yourself, you can remove the permissions to manipulate CEs and JQs from the policy. The minimum permissions required are: - `batch:DescribeJobs` to report job status - `batch:DescribeJobDefinitions` to list existing job definitions - `batch:RegisterJobDefinition` to create new job definitions - `batch:CancelJob` to cancel jobs - `batch:SubmitJob` to submit jobs - `batch:TagResource` to tag jobs - `batch:TerminateJob` to terminate jobs You can use `batch:DescribeJobQueues` to list the existing job queues in a drop-down but it's not required if you're specifying manually created job queues. However, it is required when you let Seqera create and manage job queues automatically (using the Forge tool). In this case, the `batch:DescribeComputeEnvironments` permission must also be added. You can also restrict permissions based on resource tags. These are defined by users when they [set up a pipeline in Platform](https://docs.seqera.io/platform-enterprise/resource-labels/overview). ```json { "Sid": "BatchEnvironmentListing", "Effect": "Allow", "Action": [ "batch:DescribeJobDefinitions", "batch:DescribeJobs" ], "Resource": "*" }, { "Sid": "BatchJobsManagement", "Effect": "Allow", "Action": [ "batch:CancelJob", "batch:RegisterJobDefinition", "batch:SubmitJob", "batch:TagResource", "batch:TerminateJob" ], "Resource": [ "arn:aws:batch:::job-queue/MyCustomJQ", "arn:aws:batch:::job-definition/*", "arn:aws:batch:::job/*" ], "Condition": { "StringEqualsIfExists": { "aws:ResourceTag/MyCustomTag": "MyCustomValue" } } } ``` :::warning Restricting the `batch` actions using resource tags requires that you set the appropriate tags on each Seqera pipeline when configuring it in Platform. Forgetting to set the tag will cause the pipeline to fail to run. ::: The job definition and job name resources cannot be restricted to specific names, as Seqera creates job definitions and jobs with dynamic names. Therefore, the wildcard `*` must be used in the name of these resources. In addition, `batch:SubmitJob` requires permission on both job definitions and job queues, so make sure to include both ARNs in the `Resource` array. If you prefer to let Seqera manage Batch resources for you, you can still restrict the permissions to specific resources in your account ID and region; you can also restrict permissions based on Resource tag, as shown with the `Condition`s in the example above. :::note The quick start policy is expecting CE and JQ names automatically created by Seqera to start with the `TowerForge-` prefix, which is the default prefix used by Platform Enterprise. If you [customized it on your Enterprise installations](../enterprise/configuration/overview#compute-environments) with `TOWER_FORGE_PREFIX` adapt the policy to the new prefix. ::: ### Launch template management Seqera requires the ability to create and manage EC2 launch templates using optimized AMIs identified via AWS Systems Manager (SSM). :::note AWS does not support restricting IAM permissions on EC2 launch templates based on specific resource names or tags. As a result, permission to operate on any resource `*` must be granted. ::: ### Pass role to Batch The `iam:PassRole` permission allows Seqera to pass [execution IAM roles](https://docs.aws.amazon.com/batch/latest/userguide/execution-IAM-role.html#create-execution-role) to AWS Batch to run Nextflow pipelines. Permissions can be restricted to only allow passing the manually created roles or the roles created by Seqera automatically with the default prefix `TowerForge-` to the AWS Batch and EC2 services, in a specific account: ```json { "Sid": "PassRolesToBatch", "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam:::role/TowerForge-*", "Condition": { "StringEquals": { "iam:PassedToService": [ "batch.amazonaws.com", "ec2.amazonaws.com" ] } } } ``` ### CloudWatch logs access Seqera requires access to CloudWatch logs to display relevant log data in the web interface. The policy can be scoped down to limit access to the [specific log group](#advanced-options) defined on the compute environment in a specific account and region: ```json { "Sid": "CloudWatchLogsAccess", "Effect": "Allow", "Action": [ "logs:Describe*", "logs:FilterLogEvents", "logs:Get*", "logs:List*", "logs:StartQuery", "logs:StopQuery", "logs:TestMetricFilter" ], "Resource": "arn:aws:logs:::log-group:/aws/batch/job/*" } ``` ### S3 access (optional) Seqera automatically attempts to fetch a list of S3 buckets available in the AWS account connected to Platform, to provide them in a drop-down to be used as Nextflow working directory, and make the compute environment creation smoother. This feature is optional, and users can type the bucket name manually when setting up a compute environment. To allow Seqera to fetch the list of buckets in the account, the `s3:ListAllMyBuckets` action can be added, and it must have the `Resource` field set to `*`, as shown in the generic policy at the beginning of this document. The `s3:ListAllMyBuckets` action also allows Data Explorer to auto-discover the data repositories accessible to your workspace credentials. Seqera offers several products to manipulate data on AWS S3 buckets, such as [Studios](../studios/overview) and [Data Explorer](../data/data-explorer); if these features are not used the related permissions can be omitted. The IAM policy can be scoped down to only allow limited read/write permissions in certain S3 buckets used by Studios/Data Explorer. For each bucket you want to browse, upload to, or download from with Data Explorer, grant `s3:GetObject` and `s3:PutObject` on the bucket objects, and `s3:ListBucket`, `s3:GetBucketLocation`, `s3:GetBucketPolicy`, and `s3:GetBucketAcl` on the bucket itself. In addition, the policy must include permission to check the region and list the content of the S3 bucket used as Nextflow work directory. We also recommend granting the `s3:GetObject` permission on the work directory path to fetch Nextflow log files. :::note If you opted to create a separate S3 bucket only for Nextflow work directories, there is no need for the IAM user to have read/write access to it. If Seqera is allowed to manage resources (using Batch Forge) the IAM roles automatically created will have the necessary permissions. If you set up the compute environment manually, you can create the required IAM roles with the necessary permissions as detailed in the [manual AWS Batch setup documentation](../enterprise/advanced-topics/manual-aws-batch-setup). ::: ```json { "Sid": "S3CheckBucketWorkDirectory", "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::example-bucket-used-as-work-directory" ] }, { "Sid": "S3ReadOnlyNextflowLogFiles", "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::example-bucket-used-as-work-directory/path/to/work/directory/*" ] }, { "Sid": "S3ReadWriteBucketsForStudiosDataExplorer", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectTagging", "s3:GetBucketLocation", "s3:GetBucketPolicy", "s3:GetBucketAcl", "s3:ListBucket", "s3:PutObject", "s3:PutObjectTagging", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::example-bucket-read-write-studios", "arn:aws:s3:::example-bucket-read-write-studios/*", "arn:aws:s3:::example-bucket-read-write-data-explorer", "arn:aws:s3:::example-bucket-read-write-data-explorer/*" ] } ``` :::note `s3:GetBucketLocation` allows Data Explorer to resolve each bucket's region. `s3:GetBucketPolicy` and `s3:GetBucketAcl` allow it to inspect each bucket's access configuration when it lists and connects to data repositories. If you prefer not to enumerate individual actions, the `s3:Get*` and `s3:List*` wildcards shown in the full permissive policy above also cover these actions. ::: ### IAM roles for AWS Batch (optional) Seqera can automatically create the IAM roles needed to interact with AWS Batch and other AWS services. You can opt out of this behavior by creating the required IAM roles manually and providing their ARNs during compute environment creation in Platform: refer to the [documentation](../enterprise/advanced-topics/manual-aws-batch-setup) for more details on how to manually set up IAM roles. To allow Seqera to create IAM roles but restrict it to your specific account and the default IAM role prefix, use the following statement: ```json { "Sid": "IAMRoleAndProfileManagement", "Effect": "Allow", "Action": [ "iam:AddRoleToInstanceProfile", "iam:AttachRolePolicy", "iam:CreateInstanceProfile", "iam:CreateRole", "iam:DeleteInstanceProfile", "iam:DeleteRole", "iam:DeleteRolePolicy", "iam:DetachRolePolicy", "iam:GetRole", "iam:ListAttachedRolePolicies", "iam:ListRolePolicies", "iam:PutRolePolicy", "iam:RemoveRoleFromInstanceProfile", "iam:TagInstanceProfile", "iam:TagRole" ], "Resource": [ "arn:aws:iam:::role/TowerForge-*" "arn:aws:iam:::instance-profile/TowerForge-*" ] } ``` :::note The quick start policy is expecting role names automatically created by Seqera to start with the `TowerForge-` prefix, which is the default prefix used by Platform Enterprise. If you [customized it on your Enterprise installations](../enterprise/configuration/overview#compute-environments) with `TOWER_FORGE_PREFIX` adapt the policy to the new prefix. ::: ### AWS Systems Manager (optional) Seqera Platform can interact with AWS Systems Manager (SSM) to [identify ECS Optimized AMIs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/retrieve-ecs-optimized_AMI.html) for pipeline execution. This permission is optional, meaning that a [custom AMI ID](#advanced-options) can be provided at compute environment creation, removing the need for this permission. ### EC2 describe permissions (optional) Seqera can interact with EC2 to retrieve information about existing AWS resources in your account, including VPCs, subnets, and security groups. This data is used to populate drop-downs in the Platform UI when creating new compute environments. While these permissions are optional, they are recommended to enhance the user experience. Without these permissions, resource ARNs need to be manually entered in the interface by the user. :::note AWS does not support restricting IAM permissions on EC2 Describe actions based on specific resource names or tags. As a result, permission to operate on any resource `*` must be granted. ::: ### FSx file systems (optional) Seqera can manage [AWS FSx file systems](https://aws.amazon.com/fsx/), if needed by the pipelines. This section of the policy is optional and can be omitted if FSx file systems are not used by your pipelines. The describe actions cannot be restricted to specific resources, so permission to operate on any resource `*` must be granted. The management actions can be restricted to specific resources, like in the example below. ```json { "Sid": "FSxDescribe", "Effect": "Allow", "Action": [ "fsx:DescribeFileSystems" ], "Resource": "*" }, { "Sid": "FSxManagement", "Effect": "Allow", "Action": [ "fsx:CreateFileSystem", "fsx:DeleteFileSystem", "fsx:TagResource" ], "Resource": "arn:aws:fsx:::file-system/MyManualFSx" } ``` ### EFS file systems (optional) Seqera can manage [AWS EFS file systems](https://aws.amazon.com/efs/), if needed by the pipelines. This section of the policy is optional and can be omitted if EFS file systems are not used by your pipelines. The describe actions cannot be restricted to specific resources, so permission to operate on any resource `*` must be granted. The management actions can be restricted to specific resources, like in the example below. ```json { "Sid": "EFSDescribe", "Effect": "Allow", "Action": [ "elasticfilesystem:DescribeFileSystems", "elasticfilesystem:DescribeMountTargets" ], "Resource": "*" }, { "Sid": "EFSManagement", "Effect": "Allow", "Action": [ "elasticfilesystem:CreateFileSystem", "elasticfilesystem:DeleteFileSystem", "elasticfilesystem:CreateMountTarget", "elasticfilesystem:DeleteMountTarget", "elasticfilesystem:UpdateFileSystem", "elasticfilesystem:PutLifecycleConfiguration", "elasticfilesystem:TagResource" ], "Resource": "arn:aws:elasticfilesystem:::file-system/MyManualEFS" } ``` ### Pipeline secrets (optional) Seqera can synchronize [pipeline secrets](../secrets/overview) defined on the Platform workspace with AWS Secrets Manager, which requires additional permissions on the IAM user. If you do not plan to use pipeline secrets, you can omit this section of the policy. The listing of secrets cannot be restricted, but the management actions can be restricted to only allow managing secrets in a specific account and region, which must be the same region where the pipeline runs. Note that Seqera only creates secrets with the `tower-` prefix. ```json { "Sid": "PipelineSecretsListing", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" }, { "Sid": "PipelineSecretsManagementCanBeRestricted", "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:DeleteSecret", "secretsmanager:CreateSecret" ], "Resource": "arn:aws:secretsmanager:::secret:tower-*" } ``` #### Additional steps required to use secrets in a pipeline To successfully use pipeline secrets, the IAM roles manually created must follow the steps detailed in the [documentation](../secrets/overview#aws-secrets-manager-integration). ## Create the IAM policy The policy above must be created in the AWS account where the AWS Batch resources need to be created. 1. Open the [AWS IAM console](https://console.aws.amazon.com/iam) in the account where you want to create the AWS Batch resources. 1. From the left navigation menu, select **Policies** under **Access management**. 1. Select **Create policy**. 1. On the **Policy editor** section, select the **JSON** tab. 1. Following the instructions detailed in the [IAM permissions breakdown section](#required-platform-iam-permissions) replace the default text in the policy editor area under the **JSON** tab with a policy adapted to your use case, then select **Next**. 1. Enter a name and description for the policy on the **Review and create** page, then select **Create policy**. ## IAM user creation Seqera requires an Identity and Access Management (IAM) User to create and manage AWS Batch resources in your AWS account. We recommend creating a separate IAM policy rather an IAM User inline policy, as the latter only allows 2048 characters, which may not be sufficient for all the required permissions. In certain scenarios, for example when multiple users need to access the same AWS account and provision AWS Batch resources, an IAM role with the required permissions can be created instead, and the IAM user can assume that role when accessing AWS resources, as detailed in the [IAM role creation (optional)](#iam-role-creation-optional) section. Depending whether you choose to let Seqera automatically create the required AWS Batch resources in your account, or prefer to set them up manually, the IAM user must have specific permissions as detailed in the [Required Platform IAM permissions](#required-platform-iam-permissions) section. Alternatively, you can create an IAM role with the required permissions and allow the IAM user to assume that role when accessing AWS resources, as detailed in the [IAM role creation (optional)](#iam-role-creation-optional) section. ### Create an IAM user 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Users** in the left navigation menu, then select **Create User** at the top right of the page. 1. Enter a name for your user (e.g., _seqera_) and select **Next**. 1. Under **Permission options**, select **Attach policies directly**, then search for and select the policy created above, and select **Next**. * If you prefer to make the IAM user assume a role to manage AWS resources (see the [IAM role creation (optional)](#iam-role-creation-optional) section), create a policy with the following content (edit the AWS principal with the ARN of the role created) and attach it to the IAM user: ```json { "Sid": "AssumeRoleToManageBatchResources", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam:::role/", "Condition": { "StringEquals": { "sts:ExternalId": "" } } } ``` 1. On the last page, review the user details and select **Create user**. The user has now been created. The most up-to-date instructions for creating an IAM user can be found in the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). ### Obtain IAM user credentials To get the credentials needed to connect Seqera to your AWS account, follow these steps: 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Users** in the left navigation menu, then select the newly created user from the users table. 1. Select the **Security credentials** tab, then select **Create access key** under the **Access keys** section. 1. In the **Use case** dialog that appears, select **Command line interface (CLI)**, then tick the confirmation checkbox at the bottom to acknowledge that you want to proceed creating an access key, and select **Next**. 1. Optionally provide a description for the access key, like the reason for creating it, then select **Create access key**. 1. Save the **Access key** and **Secret access key** in a secure location as you will need to provide them when creating credentials in Seqera. ## IAM role creation (optional) Rather than attaching permissions directly to the IAM user, you can create an IAM role with the required permissions and allow the IAM user to assume that role when accessing AWS resources. This is useful when multiple IAM users are used to access the same AWS account: this way the actual permissions to operate on the resources are only granted to a single centralized role. 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Roles** in the left navigation menu, then select **Create role** at the top right of the page. 1. Select **Custom trust policy** as the type of trusted entity, provide the following policy and edit the AWS principal with the ARN of the IAM user created in the [IAM user creation](#iam-user-creation) section, then select **Next**. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam:::user/" ] }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } }, { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam:::user/" ] }, "Action": "sts:TagSession" } ] } ``` 1. On the **Permissions** page, search for and select the policy created in the [IAM user creation](#iam-user-creation) section, then select **Next**. 1. Give the role a name and optionally a description, review the details of the role, optionally provide tags to help you identify the role, then select **Create role**. Multiple users can be specified in the trust policy by adding more ARNs to the `Principal` section. :::note Seqera Platform generates the `External ID` value during AWS credential creation. For role-based credentials, use this exact value in your IAM trust policy (`sts:ExternalId`). ::: ### Role-based trust policy example (Seqera Enterprise) For role-based AWS credentials in Enterprise, use the AWS IAM role configured in your deployment (``) in your trust policy and enforce the `External ID` generated during credential creation: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } }, { "Effect": "Allow", "Principal": { "AWS": "" }, "Action": "sts:TagSession" } ] } ``` :::info In Seqera Enterprise, a jump role is optional. If you configure one, use your own jump role ARN as the trusted principal in the trust policy. The **Assume role** value in the credential form is the customer IAM role ARN in your AWS account. It is separate from any optional jump role configuration. ::: :::info To use role-based access with no External ID, set `TOWER_ALLOW_INSTANCE_CREDENTIALS=true` in your deployment [configuration](../enterprise/configuration/overview#compute-environments). Then create AWS credentials using an IAM role ARN only (no access key, secret key, or External ID), and remove the entire `Condition` block for `sts:ExternalId` from your trust policy. ::: ## AWS credential options AWS credentials can be configured in two ways: - **Key-based credentials**: Access key and secret key with direct IAM permissions. If you provide a role ARN in **Assume role**, the **Generate External ID** switch is displayed and External ID generation is optional. - **Role-based credentials (recommended)**: Use role assumption only (no static keys). Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. External ID is generated automatically when you save. Use the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. This field is available for both key-based and role-based credentials. It is optional for key-based credentials and required for role-based credentials. Existing credentials created before March 2026 continue to work without changes. `TOWER_ALLOW_INSTANCE_CREDENTIALS=true` configuration behavior remains unchanged. ## Automatic configuration of Batch resources :::caution AWS Batch creates resources that you may be charged for in your AWS account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: ### AWS Batch Seqera automates the configuration of an [AWS Batch](https://aws.amazon.com/batch/) compute environment and the queues required to deploy Nextflow pipelines. After your IAM user and S3 bucket have been set up, create a new **AWS Batch** compute environment in Seqera. #### Create a Seqera AWS Batch compute environment Seqera will create the head and compute [job queues](https://docs.aws.amazon.com/batch/latest/userguide/job_queues.html) and their respective [compute environments](https://docs.aws.amazon.com/batch/latest/userguide/compute_environments.html) where jobs will be executed. The job queues are configured with [job state limit actions](https://docs.aws.amazon.com/batch/latest/APIReference/API_JobStateTimeLimitAction.html) to automatically purge jobs that cannot be scheduled on any node type available for the compute environment. Depending on the provided configuration in the UI, Seqera might also create IAM roles for Nextflow head job execution, CloudWatch log groups, EFS or FSx filesystems, etc. 1. Select **Compute environments** from the navigation menu of the Seqera Workspace where you want to setup the CE. 1. Select **Add compute environment**. 1. Enter a descriptive name for this environment, e.g., _AWS Batch Spot (eu-west-1)_. 1. Select **AWS Batch** as the target platform. 1. From the **Credentials** drop-down, select existing AWS credentials, or select **+** to add new credentials. If you're using existing credentials, skip to step 9. :::note You can create multiple credentials in your Seqera environment. See [Credentials](../credentials/overview). ::: 1. Enter a name, e.g., _AWS Credentials_. 1. Under **AWS credential mode**, select **Keys** or **Role**. 1. For **Keys** mode: - Add the **Access key** and **Secret key** you [previously obtained](#obtain-iam-user-credentials). - Optionally paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - If you paste a role ARN in **Assume role**, the **Generate External ID** switch is displayed. Generating an External ID is optional in **Keys** mode. - If **Generate External ID** is selected, an External ID is automatically generated and shown after you save the credential. 1. For **Role** mode: - Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - External ID is generated automatically when you save the credential. :::note When using AWS keys without an assumed role, the associated AWS user must have been granted permissions to operate on the cloud resources directly. When an assumed role is provided, the IAM user keys are only used to retrieve temporary credentials impersonating the role specified: this could be useful when e.g. multiple IAM users are used to access the same AWS account, and the actual permissions to operate on the resources are only granted to the role. ::: 1. Select a **Region**, e.g., _eu-west-1 - Europe (Ireland)_. This region must match the location of the S3 bucket or EFS/FSx file system you plan to use as work directory. 1. In the **Pipeline work directory** field type or select from the drop-down the S3 bucket [previously created](#s3-bucket-creation), e.g., `s3://seqera-bucket`. The work directory can be customized to specify a folder inside the bucket where Nextflow intermediate files will be stored, e.g., `s3://seqera-bucket/nextflow-workdir`. The bucket must be located in the same region chosen in the previous step. :::note When you specify an S3 bucket as your work directory, this bucket is used for the Nextflow [cloud cache](https://docs.seqera.io/nextflow/cache-and-resume#cache-stores) by default. Seqera adds a `cloudcache` block to the Nextflow configuration file for all runs executed with this compute environment. This block includes the path to a `cloudcache` folder in your work directory, e.g., `s3://seqera-bucket/cloudcache/.cache`. You can specify an alternative cache location with the **Nextflow config file** field on the pipeline [launch](../launch/launchpad#launch-form) form. ::: Similarly you can specify a path in an EFS or FSx file system as your work directory. When using EFS or FSx, you'll need to scroll down to "EFS file system" or "FSx for Lustre" sections to specify either an existing file system ID or let Seqera create a new one for you automatically. Read the notes in steps 23 and 24 below on how to setup EFS or FSx. :::warning Using an EFS or FSx file system as your work directory is currently incompatible with [Studios](../studios/overview), and will result in errors with checkpoints and mounted data. Use an S3 bucket as your work directory when using Studios. ::: 1. Select **Enable Wave containers** to facilitate access to private container repositories and provision containers in your pipelines using the Wave containers service. See [Wave containers](https://docs.seqera.io/nextflow/wave) for more information. 1. Select **Enable Fusion v2** to allow access to your S3-hosted data via the [Fusion v2](https://docs.seqera.io/fusion) virtual distributed file system. This speeds up most data operations. The Fusion v2 file system requires Wave containers to be enabled. See [Fusion file system](../supported_software/fusion/overview) for configuration details.
Use Fusion v2 file system :::note The compute recommendations below are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. ::: We recommend using Fusion with AWS NVMe instances (fast instance storage) as this delivers the fastest performance when compared to environments using only AWS EBS (Elastic Block Store). 1. Use Seqera Platform version 23.1 or later. 1. Use an S3 bucket as the pipeline work directory. 1. Enable **Wave containers**, **Fusion v2**, and **fast instance storage**. 1. Select the **Batch Forge** config mode. 1. Fast instance storage requires an EC2 instance type that uses NVMe disks. Specify NVMe-based instance types in **Instance types** under **Advanced options**. If left unspecified, Platform selects instances from AWS NVMe-based instance type families. See [Instance store temporary block storage for EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html) for more information. :::note When enabling fast instance storage, do not select the `optimal` instance type families (c4, m4, r4) for your compute environment as these are not NVMe-based instances. Specify AWS NVMe-based instance types, or leave the **Instance types** field empty for Platform to select NVMe instances for you. ::: :::tip We recommend selecting 8xlarge or above for large and long-lived production pipelines: - A local temp storage disk of at least 200 GB and a random read speed of 1000 MBps or more. To work with files larger than 100 GB, increase temp storage accordingly (400 GB or more). - Dedicated networking ensures a guaranteed network speed service level compared with "burstable" instances. See [Instance network bandwidth](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-network-bandwidth.html) for more information. ::: When using Fusion v2 without fast instance storage, the following EBS settings are applied to optimize file system performance: - EBS boot disk size is increased to 100 GB - EBS boot disk type GP3 is selected - EBS boot disk throughput is increased to 325 MB/s Extensive benchmarking of Fusion v2 has demonstrated that the increased cost associated with these settings are generally outweighed by the costs saved due to decreased run time.
1. Select **Enable Fusion Snapshots (beta)** to enable Fusion to automatically restore jobs that are interrupted when an AWS Spot instance reclamation occurs. Requires Fusion v2. See [Fusion Snapshots](https://docs.seqera.io/fusion/guide/snapshots) for more information. 1. Set the **Config mode** to **Batch Forge** to allow Seqera Platform to manage AWS Batch compute environments using the Forge tool. 1. Select a **Provisioning model**. To minimize compute costs select **Spot**. You can specify an allocation strategy and instance types under [**Advanced options**](#advanced-options). If advanced options are omitted, Seqera Platform 23.2 and later versions default to `BEST_FIT_PROGRESSIVE` for On-Demand and `SPOT_PRICE_CAPACITY_OPTIMIZED` for Spot compute environments. :::note You can create a compute environment that launches either Spot or On-Demand instances. Spot instances can cost as little as 20% of On-Demand instances, and with Nextflow's ability to automatically relaunch failed tasks, Spot is almost always the recommended provisioning model. Note, however, that when choosing Spot instances, Seqera will also create a dedicated queue for running the main Nextflow job using a single On-Demand instance to prevent any execution interruptions. From Nextflow version 24.10, the default Spot reclamation retry setting changed to `0` on AWS and Google. By default, no internal retries are attempted on these platforms. Spot reclamations now lead to an immediate failure, exposed to Nextflow in the same way as other generic failures (returning for example, `exit code 1` on AWS). Nextflow will treat these failures like any other job failure unless you actively configure a retry strategy. For more information, see [Spot instance failures and retries](../troubleshooting_and_faqs/nextflow#spot-instance-failures-and-retries). ::: 1. Enter the **Max CPUs**, e.g., `64`. This is the maximum number of combined CPUs (the sum of all instances' CPUs) AWS Batch will provision at any time. 1. Select **EBS Auto scale (deprecated)** to allow the EC2 virtual machines to dynamically expand the amount of available disk space during task execution. This feature is deprecated, and is not compatible with Fusion v2. :::note When you run large AWS Batch clusters (hundreds of compute nodes or more), EC2 API rate limits may cause the deletion of unattached EBS volumes to fail. You should delete volumes that remain active after Nextflow jobs have completed to avoid additional costs. Monitor your AWS account for any orphaned EBS volumes via the EC2 console, or with a Lambda function. See [here](https://aws.amazon.com/blogs/mt/controlling-your-aws-costs-by-deleting-unused-amazon-ebs-volumes/) for more information. ::: 1. With the optional **Enable Fusion mounts (deprecated)** feature enabled, S3 buckets specified in **Pipeline work directory** and **Allowed S3 Buckets** are mounted as file system volumes in the EC2 instances carrying out the Batch job execution. These buckets can then be accessed at `/fusion/s3/`. For example, if the bucket name is `s3://imputation-gp2`, your pipeline will access it using the file system path `/fusion/s3/imputation-gp2`. **Note:** This feature has been deprecated. Consider using Fusion v2 (see above) for enhanced performance and stability. :::note You do not need to modify your pipeline or files to take advantage of this feature. Nextflow will automatically recognize and replace any reference to files prefixed with `s3://` with the corresponding Fusion mount paths. ::: 1. Select **Enable Fargate for head job** to run the Nextflow head job with the [AWS Fargate](https://aws.amazon.com/fargate/) container service and speed up pipeline launch. Fargate is a serverless compute engine that enables users to run containers without the need to provision servers or clusters in advance. AWS takes a few minutes to spin up an EC2 instance, whereas jobs can be launched with Fargate in under a minute (depending on container size). We recommend Fargate for most pipeline deployments, but EC2 is more suitable for environments that use GPU instances, custom AMIs, or that require more than 16 vCPUs. If you specify a custom AMI ID in the [Advanced options](#advanced-options) below, this will not be applied to the Fargate-enabled head job. See [here](https://docs.aws.amazon.com/batch/latest/userguide/fargate.html#when-to-use-fargate) for more information on Fargate's limitations. :::note Fargate requires the Fusion v2 file system and a **Spot** provisioning model. Fargate is not compatible with EFS and FSx file systems. ::: 1. Select **Enable GPUs** if you intend to run GPU-dependent workflows in the compute environment. See [GPU usage](./overview#aws-batch) for more information. :::note Seqera only supports NVIDIA GPUs. Select instances with NVIDIA GPUs for your GPU-dependent processes. ::: 1. Select **Use Graviton CPU architecture** to execute on Graviton-based EC2 instances (i.e., ARM64 CPU architecture). When enabled, `m6g`, `r6g`, and `c6g` instance types are used by default for compute jobs, but 3rd-generation Graviton [instances](https://www.amazonaws.cn/en/ec2/graviton/) are also supported. You can specify your own **Instance types** under [**Advanced options**](#advanced-options). :::note Graviton requires Fargate, Wave containers, and Fusion v2 file system to be enabled. This feature is not compatible with GPU-based architecture. ::: 1. Enter any additional **Allowed S3 buckets** that your workflows require to read input data or write output data. The **Pipeline work directory** bucket above is added by default to the list of **Allowed S3 buckets**. 1. To use an **EFS** file system in your pipeline, you can either select **Use existing EFS file system** and specify an existing EFS instance, or select **Create new EFS file system** to create one. To use the EFS file system as the work directory of the compute environment specify `/work` in the **Pipeline work directory** field (step 10 of this guide). - To use an existing EFS file system, enter the **EFS file system id** and **EFS mount path**. This is the path where the EFS volume is accessible to the compute environment. For simplicity, we recommend that you use `/mnt/efs` as the EFS mount path. - To create a new EFS file system, enter the **EFS mount path**. We advise that you specify `/mnt/efs` as the EFS mount path. - EFS file systems created by Batch Forge are automatically tagged in AWS with `Name=TowerForge-`, with `` being the compute environment ID. Any manually-added resource label with the key `Name` (capital N) will override the automatically-assigned `TowerForge-` label. - A custom EC2 security group needs to be configured to allow the compute environment to access the EFS file system. * Visit the [AWS Console for Security groups](https://console.aws.amazon.com/ec2/home?#SecurityGroups) and switch to the region where your workload will run. * Select **Create security group**. * Enter a relevant name like `seqera-efs-access-sg` and description, e.g., _EFS access for Seqera Batch compute environment_. * Empty both **Inbound rules** and **Outbound rules** sections by deleting default rules. * Optionally add **Tags** to the security group, then select **Create security group**. * After creating the security group, select it from the security groups list, then select the **Inbound rules** tab and select **Edit inbound rules**. * Select **Add rule** and configure the new rule as follows: - **Type**: `NFS` - **Source**: `Custom` and enter the security group ID that you're editing (you can search for it by name, e.g., `seqera-efs-access-sg`). This allows resources associated with the same security group to communicate with each other. * Select **Save rules** to finalize the inbound rule configuration. * Repeat the same steps to add an outbound rule to allow all outbound traffic: set type `All traffic` and destination `Anywhere-IPv4`/`Anywhere-IPv6`. * See the [AWS documentation about EFS security groups](https://docs.aws.amazon.com/efs/latest/ug/network-access.html) for more information. * The Security group then needs to be defined in the **Advanced options** below to allow the compute environment to access the EFS file system. :::warning EFS file systems cannot be used as work directory for [Studios](../studios/overview), but can be mounted and used by applications running in Studios. ::: 1. To use a **FSx for Lustre** file system in your pipeline, you can either select **Use existing FSx file system** and specify an existing FSx instance, or select **Create new FSx file system** to create one. To use the FSx file system as your work directory, specify `/work` in the **Pipeline work directory** field (step 10 of this guide). - To use an existing FSx file system, enter the **FSx DNS name** and **FSx mount path**. The FSx mount path is the path where the FSx volume is accessible to the compute environment. For simplicity, we recommend that you use `/mnt/fsx` as the FSx mount path. - To create a new FSx file system, enter the **FSx size** (in GB) and the **FSx mount path**. We advise that you specify `/mnt/fsx` as the FSx mount path. - FSx file systems created by Batch Forge are automatically tagged in AWS with `Name=TowerForge-`, with `` being the compute environment ID. Any manually-added resource label with the key `Name` (capital N) will override the automatically-assigned `TowerForge-` label. - A custom EC2 security group needs to be configured to allow the compute environment to access the FSx file system. * Visit the [AWS Console for Security groups](https://console.aws.amazon.com/ec2/home?#SecurityGroups) and switch to the region where your workload will run. * Select **Create security group**. * Enter a relevant name like `seqera-fsx-access-sg` and description, e.g., _FSx access for Seqera Batch compute environment_. * Empty both **Inbound rules** and **Outbound rules** sections by deleting default rules. * Optionally add **Tags** to the security group, then select **Create security group**. * After creating the security group, select it from the security groups list, then select the **Inbound rules** tab and select **Edit inbound rules**. * Select **Add rule** and configure the new rule as follows: - **Type**: `Custom TCP` - **Port range**: `988` - **Source**: `Custom` and enter the security group ID that you're editing (you can search for it by name, e.g., `seqera-fsx-access-sg`). This allows resources associated with the same security group to communicate with each other. * Repeat the step to add another rule with: - **Type**: `Custom TCP` - **Port range**: `1018-1023` - **Source**: `Custom`, same as above. * Select **Save rules** to finalize the inbound rule configuration. * Repeat the same steps to add an outbound rule to allow all outbound traffic: set type `All traffic` and destination `Anywhere-IPv4`/`Anywhere-IPv6`. * See the [AWS documentation about FSx security groups](https://docs.aws.amazon.com/fsx/latest/LustreGuide/limit-access-security-groups.html) for more information. * The Security group then needs to be defined in the **Advanced options** below to allow the compute environment to access the FSx file system. - You may need to install the `lustre` client in the AMI used by your compute environment to access FSx file systems. See [Installing the Lustre client](https://docs.aws.amazon.com/fsx/latest/LustreGuide/install-lustre-client.html) for more information. :::warning FSx file systems cannot be used as work directory for [Studios](../studios/overview), but can be mounted and used by applications running in Studios. ::: 1. Select **Dispose resources** to automatically delete all AWS resources created by Seqera Platform when you delete the compute environment, including EFS/FSx file systems. 1. Apply [**Resource labels**](../resource-labels/overview) to the cloud resources produced by this compute environment. Workspace default resource labels are prefilled. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options described in the next section, as needed. 1. Select **Create** to finalize the compute environment setup. It will take a few seconds for all the AWS resources to be created before you are ready to launch pipelines. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your AWS Batch compute environment. ::: ### Advanced options Seqera Platform compute environments for AWS Batch include advanced options to configure instance types, resource allocation, custom networking, and CloudWatch and ECS agent integration. #### Seqera AWS Batch advanced options - Specify the **Allocation strategy** and indicate any preferred **Instance types**. AWS applies quotas for the number of running and requested [Spot](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-limits.html) and [On-Demand](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-on-demand-instances.html#ec2-on-demand-instances-limits) instances per account. AWS will allocate instances from up to 20 instance types, based on those requested for the compute environment. AWS excludes the largest instances when you request more than 20 instance types. :::note If these advanced options are omitted, allocation strategy defaults are `BEST_FIT_PROGRESSIVE` for On-Demand and `SPOT_PRICE_CAPACITY_OPTIMIZED` for Spot compute environments. ::: :::caution Platform CLI (known as `tw`) v0.8 and earlier do not support the `SPOT_PRICE_CAPACITY_OPTIMIZED` allocation strategy in AWS Batch. You cannot currently use CLI to create or otherwise interact with AWS Batch Spot compute environments that use this allocation strategy. ::: - Configure a custom networking setup using the **VPC ID**, **Subnets**, and **Security groups** fields. * If not defined, the default VPC, subnets, and security groups for the selected region will be used. * When using EFS or FSx file systems, select the security group previously created to allow access to the file system. The VPC ID the security group belongs to needs to match the VPC ID defined for the Seqera Batch compute environment. - You can specify a custom **AMI ID**. :::note From version 24.2, Seqera supports Amazon Linux 2023 ECS-optimized AMIs, in addition to previously supported Amazon Linux-2 AMIs. AWS-recommended Amazon Linux 2023 AMI names start with `al2023-`. To learn more about approved versions of the Amazon ECS-optimized AMIs or creating a custom AMI, see [this AWS guide](https://docs.aws.amazon.com/batch/latest/userguide/compute_resource_AMIs.html#batch-ami-spec). If a custom AMI is specified and the **Enable GPU** option is also selected, the custom AMI will be used instead of the AWS-recommended GPU-optimized AMI. ::: - If you need to debug the EC2 instance provisioned by AWS Batch, specify a **Key pair** to log in to the instance via SSH. - You can set **Min CPUs** to be greater than `0`, in which case some EC2 instances will remain active. An advantage of this is that pipeline executions will initialize faster. :::note Setting Min CPUs to a value greater than 0 will keep the required compute instances active, even when your pipelines are not running. This will result in additional AWS charges. ::: - Use **Head job CPUs** and **Head job memory** to specify the hardware resources allocated for the Nextflow head job. The default head job memory allocation is 4096 MiB. :::warning Setting head job values will also limit the size of any Studio session that can be created in the compute environment. ::: - Use **Head job role** and **Compute job role** to grant fine-grained IAM permissions to the **Head job** and **Compute jobs**. - Add an execution role ARN to the **Batch execution role** field to grant permissions to make API calls on your behalf to the ECS container used by Batch. This is required if the pipeline launched with this compute environment needs access to the secrets stored in this workspace. This field can be ignored if you are not using secrets. - Specify an EBS block size (in GB) in the **EBS auto-expandable block size** field to control the initial size of the EBS auto-expandable volume. New blocks of this size are added when the volume begins to run out of free space. This feature is deprecated, and is not compatible with Fusion v2. - Enter the **Boot disk size** (in GB) to specify the size of the boot disk in the VMs created by this compute environment. - If you're using **Spot** instances, you can also specify the **Cost percentage**, which is the maximum allowed price of a **Spot** instance as a percentage of the **On-Demand** price for that instance type. Spot instances will not be launched until the current Spot price is below the specified cost percentage. - Use **AWS CLI tool path** to specify the location of the `aws` CLI. - Specify a **CloudWatch Log group** for the `awslogs` driver to stream the logs entry to an existing Log group in Cloudwatch. - Specify a custom **ECS agent configuration** for the ECS agent parameters used by AWS Batch. This is appended to the `/etc/ecs/ecs.config` file in each cluster node. :::note Altering this file may result in a malfunctioning Batch Forge compute environment. See [Amazon ECS container agent configuration](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html) to learn more about the available parameters. ::: ## Manual configuration of Batch resources This section is for users with a pre-configured AWS environment: follow the [AWS Batch queue and compute environment creation instructions](../enterprise/advanced-topics/manual-aws-batch-setup.mdx) to set up the required AWS Batch resources in your account. A [S3 bucket](#s3-bucket-creation) or EFS/FSx file system is required to store Nextflow intermediate files when using Seqera with AWS Batch. Refer to the [IAM user creation](#iam-user-creation) section to ensure that your IAM user has the necessary permissions to run pipelines in Seqera Platform. Remove any permissions that are not required for your use case. ### Seqera manual compute environment With your AWS environment and resources set up and your user permissions configured, create an AWS Batch compute environment in Seqera. :::caution AWS Batch creates resources that you may be charged for in your AWS account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: 1. After logging in to your Seqera installation and selecting a workspace from the drop-down at the top of the page, select **Compute environments** from the navigation menu. 1. Select **Add compute environment**. 1. Enter a descriptive name for this environment, e.g., _AWS Batch Spot (eu-west-1)_. 1. Select **AWS Batch** as the target platform. 1. From the **Credentials** drop-down, select existing AWS credentials, or select **+** to add new credentials. If you're using existing credentials, skip to step 9. :::note You can create multiple credentials in your Seqera environment. See [Credentials](../credentials/overview). ::: 1. Enter a name, e.g., _AWS Credentials_. 1. Under **AWS credential mode**, select **Keys** or **Role**. 1. For **Keys** mode: - Add the **Access key** and **Secret key** you [previously obtained](#obtain-iam-user-credentials). - Optionally paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - If you paste a role ARN in **Assume role**, the **Generate External ID** switch is displayed. Generating an External ID is optional in **Keys** mode. - If **Generate External ID** is selected, an External ID is automatically generated and shown after you save the credential. 1. For **Role** mode: - Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - External ID is generated automatically when you save the credential. :::note When using AWS keys without an assumed role, the associated AWS user must have been granted permissions to operate on the cloud resources directly. When an assumed role is provided, the IAM user keys are only used to retrieve temporary credentials impersonating the role specified: this could be useful when e.g. multiple IAM users are used to access the same AWS account, and the actual permissions to operate on the resources are only granted to the role. ::: 1. Select a **Region**, e.g., _eu-west-1 - Europe (Ireland)_. This region must match the region where your S3 bucket or EFS/FSx work directory is located to avoid high data transfer costs. 1. Enter or select from the drop-down the S3 bucket [previously created](#s3-bucket-creation) in the **Pipeline work directory** field, e.g., `s3://seqera-bucket`. This bucket must be in the same region chosen in the previous step to avoid incurring high data transfer costs. The work directory can be customized to specify a folder inside the bucket, e.g., `s3://seqera-bucket/nextflow-workdir`. :::note When you specify an S3 bucket as your work directory, this bucket is used for the Nextflow [cloud cache](https://docs.seqera.io/nextflow/cache-and-resume#cache-stores) by default. Seqera adds a `cloudcache` block to the Nextflow configuration file for all runs executed with this compute environment. This block includes the path to a `cloudcache` folder in your work directory, e.g., `s3://seqera-bucket/cloudcache/.cache`. You can specify an alternative cache location with the **Nextflow config file** field on the pipeline [launch](../launch/launchpad#launch-form) form. ::: Similarly you can specify a path in an EFS or FSx file system as your work directory. When using EFS or FSx, you'll need to scroll down to "EFS file system" or "FSx for Lustre" sections to specify either an existing file system ID or let Seqera create a new one for you automatically. Read the notes in steps 23 and 24 below on how to setup EFS or FSx. :::warning Using an EFS or FSx file system as your work directory is currently incompatible with [Studios](../studios/overview), and will result in errors with checkpoints and mounted data. Use an S3 bucket as your work directory when using Studios. ::: 1. Select **Enable Wave containers** to facilitate access to private container repositories and provision containers in your pipelines using the Wave containers service. See [Wave containers](https://docs.seqera.io/nextflow/wave) for more information. 1. Select **Enable Fusion v2** to allow access to your S3-hosted data via the [Fusion v2](https://docs.seqera.io/fusion) virtual distributed file system. This speeds up most data operations. The Fusion v2 file system requires Wave containers to be enabled. See [Fusion file system](../supported_software/fusion/overview) for configuration details.
Use Fusion v2 file system :::note The compute recommendations below are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. ::: We recommend using Fusion with AWS NVMe instances (fast instance storage) as this delivers the fastest performance when compared to environments using only AWS EBS (Elastic Block Store). 1. Use Seqera Platform version 23.1 or later. 1. Use an S3 bucket as the pipeline work directory. 1. Enable **Wave containers**, **Fusion v2**, and **fast instance storage**. 1. Select the **Batch Forge** config mode. 1. Fast instance storage requires an EC2 instance type that uses NVMe disks. Specify NVMe-based instance types in **Instance types** under **Advanced options**. If left unspecified, Platform selects instances from AWS NVMe-based instance type families. See [Instance store temporary block storage for EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html) for more information. :::note When enabling fast instance storage, do not select the `optimal` instance type families (c4, m4, r4) for your compute environment as these are not NVMe-based instances. Specify AWS NVMe-based instance types, or leave the **Instance types** field empty for Platform to select NVMe instances for you. ::: :::tip We recommend selecting 8xlarge or above for large and long-lived production pipelines: - A local temp storage disk of at least 200 GB and a random read speed of 1000 MBps or more. To work with files larger than 100 GB, increase temp storage accordingly (400 GB or more). - Dedicated networking ensures a guaranteed network speed service level compared with "burstable" instances. See [Instance network bandwidth](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-network-bandwidth.html) for more information. ::: When using Fusion v2 without fast instance storage, the following EBS settings are applied to optimize file system performance: - EBS boot disk size is increased to 100 GB - EBS boot disk type GP3 is selected - EBS boot disk throughput is increased to 325 MB/s Extensive benchmarking of Fusion v2 has demonstrated that the increased cost associated with these settings are generally outweighed by the costs saved due to decreased run time.
1. Select **Enable Fusion Snapshots (beta)** to enable Fusion to automatically restore jobs that are interrupted when an AWS Spot instance reclamation occurs. Requires Fusion v2. See [Fusion Snapshots](https://docs.seqera.io/fusion/guide/snapshots) for more information. 1. Set the **Config mode** to **Manual**. 1. Enter the **Head queue** created following the [instructions](../enterprise/advanced-topics/manual-aws-batch-setup.mdx), which is the name of the AWS Batch queue that the Nextflow main job will run. 1. Enter the **Compute queue**, which is the name of the AWS Batch queue where tasks will be submitted. 1. Apply [**Resource labels**](../resource-labels/overview) to the cloud resources produced by this compute environment. Workspace default resource labels are prefilled. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options described in the next section, as needed. 1. Select **Create** to finalize the compute environment setup. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your AWS Batch compute environment. ::: ### Advanced options Seqera compute environments for AWS Batch include advanced options to configure resource allocation, execution roles, custom AWS CLI tool paths, and CloudWatch integration. - Configure a custom networking setup using the **VPC ID**, **Subnets**, and **Security groups** fields. * If not defined, the default VPC, subnets, and security groups for the selected region will be used. * When using EFS or FSx file systems, select the security group previously created to allow access to the file system. The VPC ID the security group belongs to needs to match the VPC ID defined for the Seqera Batch compute environment. - Use **Head job CPUs** and **Head job memory** to specify the hardware resources allocated for the Nextflow head job. The default head job memory allocation is 4096 MiB. - Use **Head job role** and **Compute job role** to grant fine-grained IAM permissions to the head job and compute jobs, - Add an execution role ARN to the **Batch execution role** field to grant permissions to make API calls on your behalf to the ECS container used by Batch. This is required if the pipeline launched with this compute environment needs access to the secrets stored in this workspace. This field can be ignored if you are not using secrets. - Use **AWS CLI tool path** to specify the location of the `aws` CLI. - Specify a **CloudWatch Log group** for the `awslogs` driver to stream the logs entry to an existing Log group in Cloudwatch. :::caution Seqera is designed to terminate compute resources when a Nextflow pipeline completes or is canceled. However, due to external factors — including user-defined workflow logic, transient cloud faults, or abnormal pipeline exits — residual resources may persist. While Seqera provides visibility to detect and resolve these states, customers are responsible for final resource cleanup and ensuring compute environments operate according to Platform expectations. From Nextflow v24.10+, compute jobs are identifiable by Seqera workflow ID. If you search your AWS console/CLI/API for jobs prefixed by a given workflow ID, you can check the status and perform additional cleanup in edge case scenarios. ::: --- ## AWS Cloud :::note This compute environment type is currently in public preview. Please consult this guide for the latest information on recommended configuration and limitations. This guide assumes you already have an AWS account with a valid AWS subscription. ::: The current implementation of compute environments for cloud providers all rely on the use of batch services such as AWS Batch, Azure Batch, and Google Batch for the execution and management of submitted jobs, including pipelines and Studio session environments. Batch services are suitable for large-scale workloads, but they add management complexity. In practical terms, the currently used batch services result in some limitations: - **Long launch delay**: When you launch a pipeline or Studio in a batch compute environment, there's a delay of several minutes before the pipeline or Studio session environment is in a running state. This is caused by the batch services that need to provision the associated compute service to run a single job. - **Complex setup**: Standard batch services require complex identity management policies and configuration of multiple services, including compute environments, job queues, job definitions, etc. - **Allocation constraints**: AWS Batch and other cloud batch services have strict resource quotas. For example, a hard limit of 50 job queues per account per region. This means that no new compute environment can be created when this quota limit is reached. The AWS Cloud compute environment addresses these pain points with: - **Faster startup time**: Nextflow pipelines reach a `Running` status and Studio sessions connect in under a minute (a 4x improvement compared to classic AWS Batch compute environments). - **Simplified configuration**: Fewer configurable options, with opinionated defaults, provide the best Nextflow pipeline and Studio session execution environment, with both Wave and Fusion enabled. - **Fewer AWS dependencies**: Only one IAM role in AWS is required. IAM roles are subject to a 1000 soft limit per account. - **Spot instances**: Studios can be launched on a Spot instance. This type of compute environment is best suited to run Studios and small to medium-sized pipelines. It offers more predictable compute pricing, given the fixed instance type. It spins up a standalone EC2 instance and executes a Nextflow pipeline or Studio session with a local executor on the EC2 machine. At the end of the execution, the instance is terminated. ## Limitations - The Nextflow pipeline will run entirely on a single EC2 instance. If the instance does not have sufficient resources, the pipeline execution will fail. For this reason, the number of tasks Nextflow can execute in parallel is limited by the number of cores of the instance type selected. If you need more computing resources, you must create a new compute environment with a larger instance type. This makes the compute environment less suited for larger, more complex pipelines. ## Supported regions The following regions are currently supported: - `eu-west-1` - `us-east-1` - `us-west-2` - `eu-west-2` - `us-east-2` - `eu-central-1` - `us-west-1` - `eu-west-3` - `ap-southeast-1` ## Requirements ### Platform credentials To create and launch pipelines or Studio sessions with this compute environment type, you must attach Seqera credentials for the cloud provider. Some permissions are mandatory for the compute environment to be created and function correctly; others are optional and used to pre-fill options in Platform. AWS credentials can be configured in two ways: - **Key-based credentials**: Access key and secret key with direct IAM permissions. If you provide a role ARN in **Assume role**, the **Generate External ID** switch is displayed and External ID generation is optional. - **Role-based credentials (recommended)**: Use role assumption only (no static keys). Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. External ID is generated automatically when you save. Use the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. This field is available for both key-based and role-based credentials. It is optional for key-based credentials and required for role-based credentials. Existing credentials created before March 2026 continue to work without changes. `TOWER_ALLOW_INSTANCE_CREDENTIALS=true` configuration behavior remains unchanged. ### Role-based trust policy example (Seqera Enterprise) For role-based AWS credentials in Enterprise, use the AWS IAM role configured in your deployment (``) in your trust policy and enforce the `External ID` generated during credential creation: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } }, { "Effect": "Allow", "Principal": { "AWS": "" }, "Action": "sts:TagSession" } ] } ``` :::info In Seqera Enterprise, a jump role is optional. If you configure one, use your own jump role ARN as the trusted principal in the trust policy. The **Assume role** value in the credential form is the customer IAM role ARN in your AWS account. It is separate from any optional jump role configuration. ::: :::info To use role-based access with no External ID, set `TOWER_ALLOW_INSTANCE_CREDENTIALS=true` in your deployment [configuration](../enterprise/configuration/overview#compute-environments). Then create AWS credentials using an IAM role ARN only (no access key, secret key, or External ID), and remove the entire `Condition` block for `sts:ExternalId` from your trust policy. ::: ### Required permissions #### Compute environment creation The following permissions are required to provision resources in the AWS account. Only IAM roles that will be assumed by the EC2 instance must be provisioned: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AwsCloudCreate", "Effect": "Allow", "Action": [ "iam:CreateRole", "iam:AddRoleToInstanceProfile", "iam:CreateInstanceProfile", "iam:AttachRolePolicy", "iam:PutRolePolicy", "iam:PassRole", "iam:TagRole", "iam:TagInstanceProfile" ], "Resource": "*" } ] } ``` ### Compute environment validation The following permissions are required to validate the compute environment at creation time. Seqera validates the input provided and that the resource ARNs exist in the target AWS account: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AwsCloudValidate", "Effect": "Allow", "Action": [ "ec2:DescribeInstanceTypes", "ec2:DescribeImages", "ec2:DescribeSubnets", "ec2:DescribeSecurityGroups" ], "Resource": "*" } ] } ``` #### Pipeline and Studio session management The following permissions are required to launch pipelines, run Studio sessions, fetch live execution logs from CloudWatch, download logs from S3, and stop the execution: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AwsCloudLaunch", "Effect": "Allow", "Action": [ "ec2:RunInstances", "ec2:DescribeInstances", "ec2:CreateTags", "ec2:TerminateInstances", "ec2:DeleteTags", "logs:GetLogEvents", "s3:GetObject" ], "Resource": "*" } ] } ``` #### Compute environment termination and resource disposal The following permissions are required to remove resources created by Seqera when the compute environment is deleted: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AwsCloudDelete", "Effect": "Allow", "Action": [ "iam:GetRole", "iam:ListAttachedRolePolicies", "iam:ListRolePolicies", "iam:DeleteRole", "iam:DeleteInstanceProfile", "iam:RemoveRoleFromInstanceProfile", "iam:DetachRolePolicy", "iam:DeleteRolePolicy" ], "Resource": "*" } ] } ``` #### Optional permissions The following permissions enable Seqera to populate values for drop-down fields. If missing, the input fields will not be auto-populated but can still be manually entered. Though optional, these permissions are recommended for a smoother and less error-prone user experience. The `s3:ListAllMyBuckets` action also allows Data Explorer to auto-discover the data repositories accessible to your workspace credentials: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AwsCloudRead", "Effect": "Allow", "Action": [ "ec2:DescribeInstanceTypes", "ec2:DescribeKeyPairs", "ec2:DescribeVpcs", "ec2:DescribeImages", "ec2:DescribeSubnets", "ec2:DescribeSecurityGroups", "s3:ListAllMyBuckets" ], "Resource": "*" } ] } ``` ## Seqera Intelligent Compute :::info[Private preview] Seqera Intelligent Compute is in private preview. [Contact us](https://seqera.io/intelligent-compute/) to request access. ::: Seqera Intelligent Compute is an optional capability that executes Nextflow tasks on a Seqera-managed Amazon ECS cluster instead of running them entirely on the head EC2 instance. The AWS Cloud compute environment scales beyond the resources of a single instance while preserving its fast startup behavior. When you enable Seqera Intelligent Compute, Seqera provisions and manages all ECS infrastructure on your behalf, including clusters, capacity providers, task definitions, IAM roles, and (optionally) Auto Scaling Groups for spot and on-demand capacity. All managed resources use the `seqera-sched-` prefix and are torn down automatically when no longer needed. ### Additional IAM permissions :::info[Private preview] Seqera Intelligent Compute is in private preview. [Contact us](https://seqera.io/intelligent-compute/) to request access. ::: To enable Seqera Intelligent Compute, attach an additional IAM policy (beyond the [Required permissions](#required-permissions)) to the same IAM user or role that Seqera uses to access your AWS account. The policy scopes ARN-eligible actions to the `seqera-sched-*` resource prefix, except for CloudWatch Logs actions, which are scoped to the `/seqera/*` log-group prefix (Seqera writes logs to groups such as `/seqera/platform`). The remaining `Resource: "*"` entries correspond to AWS APIs that do not support resource-level permissions, such as EC2 `Describe*`, ECR authorization tokens, and Cost Explorer.
Seqera Intelligent Compute policy ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ECSScopedOperations", "Effect": "Allow", "Action": [ "ecs:CreateCluster", "ecs:DeleteCluster", "ecs:DescribeClusters", "ecs:PutClusterCapacityProviders", "ecs:CreateCapacityProvider", "ecs:DeleteCapacityProvider", "ecs:DescribeCapacityProviders", "ecs:RunTask", "ecs:StopTask", "ecs:DescribeTasks", "ecs:DescribeContainerInstances", "ecs:TagResource" ], "Resource": "arn:aws:ecs:*:*:*/seqera-sched-*" }, { "Sid": "ECSUnscopedOperations", "Effect": "Allow", "Action": [ "ecs:RegisterTaskDefinition", "ecs:DeregisterTaskDefinition", "ecs:DescribeTaskDefinition", "ecs:ListTaskDefinitions", "ecs:ListTaskDefinitionFamilies", "ecs:ListTasks" ], "Resource": "*" }, { "Sid": "IAMRoleManagement", "Effect": "Allow", "Action": [ "iam:CreateRole", "iam:GetRole", "iam:DeleteRole", "iam:PutRolePolicy", "iam:DeleteRolePolicy", "iam:ListRolePolicies", "iam:AttachRolePolicy", "iam:DetachRolePolicy", "iam:ListAttachedRolePolicies", "iam:CreateInstanceProfile", "iam:GetInstanceProfile", "iam:AddRoleToInstanceProfile", "iam:ListInstanceProfilesForRole", "iam:RemoveRoleFromInstanceProfile", "iam:DeleteInstanceProfile" ], "Resource": [ "arn:aws:iam::*:role/seqera-sched-*", "arn:aws:iam::*:instance-profile/seqera-sched-*" ] }, { "Sid": "PassRoleToECS", "Effect": "Allow", "Action": "iam:PassRole", "Resource": [ "arn:aws:iam::*:role/seqera-sched-*", "arn:aws:iam::*:role/TowerForge-*" ], "Condition": { "StringEquals": { "iam:PassedToService": [ "ecs-tasks.amazonaws.com", "ecs.amazonaws.com", "ec2.amazonaws.com" ] } } }, { "Sid": "ServiceLinkedRoles", "Effect": "Allow", "Action": "iam:CreateServiceLinkedRole", "Resource": "arn:aws:iam::*:role/aws-service-role/*", "Condition": { "StringEquals": { "iam:AWSServiceName": [ "ecs.amazonaws.com", "ecs-compute.amazonaws.com", "autoscaling.amazonaws.com", "spot.amazonaws.com" ] } } }, { "Sid": "CloudWatchLogs", "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:DeleteLogGroup", "logs:PutRetentionPolicy", "logs:DescribeLogStreams", "logs:GetLogEvents", "logs:TagResource" ], "Resource": "arn:aws:logs:*:*:log-group:/seqera/*" }, { "Sid": "EC2NetworkDiscovery", "Effect": "Allow", "Action": [ "ec2:DescribeImages", "ec2:DescribeVpcs", "ec2:DescribeSubnets", "ec2:DescribeSecurityGroups", "ec2:DescribeRouteTables", "ec2:DescribeVpcEndpoints", "ec2:DescribeInstances", "ec2:CreateSecurityGroup", "ec2:CreateVpcEndpoint", "ec2:AuthorizeSecurityGroupEgress", "ec2:CreateTags" ], "Resource": "*" }, { "Sid": "ECRAccess", "Effect": "Allow", "Action": [ "ecr:GetAuthorizationToken", "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage" ], "Resource": "*" }, { "Sid": "S3Access", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket", "s3:ListAllMyBuckets" ], "Resource": "*" }, { "Sid": "ASGEC2Operations", "Effect": "Allow", "Action": [ "ec2:DescribeInstanceTypes", "ec2:CreateLaunchTemplate", "ec2:DeleteLaunchTemplate", "ec2:RunInstances" ], "Resource": "*" }, { "Sid": "ASGManagement", "Effect": "Allow", "Action": [ "autoscaling:CreateAutoScalingGroup", "autoscaling:UpdateAutoScalingGroup", "autoscaling:DeleteAutoScalingGroup", "autoscaling:CreateOrUpdateTags" ], "Resource": "arn:aws:autoscaling:*:*:*/seqera-sched-*" }, { "Sid": "ASGDescribe", "Effect": "Allow", "Action": "autoscaling:DescribeAutoScalingGroups", "Resource": "*" }, { "Sid": "SSMECSOptimizedAmi", "Effect": "Allow", "Action": "ssm:GetParameter", "Resource": "arn:aws:ssm:*:*:parameter/aws/service/ecs/optimized-ami/*" }, { "Sid": "CostExplorer", "Effect": "Allow", "Action": "ce:GetCostAndUsage", "Resource": "*" } ] } ``` Some statements in the policy above are conditional and can be omitted depending on your deployment: - The `ASGEC2Operations` and `ASGManagement` statements are required only if you enable Auto Scaling Group-backed clusters (managed instances). Omit them for Fargate-only deployments. - The `CreateECSServiceLinkedRole` is required only if the Service Role is not already created. - The `CostExplorer` statement is only required if you enable Cost Analysis.
## Managed Amazon Machine Image (AMI) The AWS Cloud compute environment uses an AMI maintained by Seqera, and the pipeline launch procedure assumes that some basic tooling is already present in the image itself. If you want to provide your own AMI, it must include at least the following: - Docker engine, configured to run at startup. - CloudWatch agent. - The ability to shut down with the `shutdown` command. If this is missing, EC2 instances will keep running and accumulate additional costs. ## Advanced options - **Instance Type**: The EC2 instance type used by the compute environment. Choosing the instance type will directly allocate the CPU and memory available for computation. See [EC2 instance types](https://aws.amazon.com/ec2/instance-types/) for a comprehensive list of instance types and their resource limitations. - **Graviton architecture**: Enable the use of Graviton instances. AWS Graviton processors, based on the ARM64 architecture, tend to offer a better performance-to-price ratio, however, the tooling used by your pipelines must be compatible with ARM architecture. - **AMI ID**: The ID of the AMI that will be used to launch the EC2 instance. Use Seqera-maintained AMIs for best performance. - **Key pair**: The [EC2 key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) to enable SSH connectivity to the running instance. If unspecified, no SSH key will be present in the running EC2 instance. - **VPC ID**: The ID of the VPC where the EC2 instance will be launched. If unspecified, the default VPC will be used. - **Subnets**: The list of VPC subnets where the EC2 instance will run. If unspecified, all the subnets of the VPC will be used. - **Security groups**: The security groups the EC2 instance will be a part of. If unspecified, no security groups will be used. - **Instance Profile**: The ARN of the `InstanceProfile` used by the EC2 instance to assume a role while running. If unspecified, Seqera will provision one with enough permissions to run. See [Custom instance profile](#custom-instance-profile) for the minimum permissions required if you provide your own. - **Boot disk size**: The size of the EBS boot disk for the EC2 instance. If undefined, a default 50 GB `gp3` volume will be used. ### Custom instance profile When you specify a custom **Instance Profile** ARN in Advanced options, the IAM role attached to that instance profile must include the following minimum permissions. These mirror what Seqera provisions automatically when no instance profile is specified. #### Trust policy The role must be assumable by the EC2 service: ```json { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRole", "Principal": { "Service": "ec2.amazonaws.com" } } } ``` #### AWS managed policies Attach the following AWS managed policies to the role: | Policy | Purpose | |--------|---------| | `arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy` | Push metrics and logs to CloudWatch | | `arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess` | Read-only access to S3 (required by Fusion and Nextflow) | | `arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly` | Pull container images from private ECR repositories | #### Inline policies In addition to the managed policies, attach the following inline policies: **S3 read/write** — grants full object access on the compute environment work directory bucket. Add one statement per bucket if you configure additional buckets under **Allow buckets**: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ListObjectsInBucket", "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": "arn:aws:s3:::" }, { "Sid": "AllObjectActions", "Effect": "Allow", "Action": "s3:*Object", "Resource": "arn:aws:s3:::/*" }, { "Sid": "AllowObjectTagging", "Effect": "Allow", "Action": ["s3:PutObjectTagging", "s3:GetObjectTagging"], "Resource": "arn:aws:s3:::/*" } ] } ``` **Secrets Manager** — grants access to the pipeline secrets Seqera stores in AWS Secrets Manager under the `tower-` prefix. Seqera creates each referenced secret when a pipeline launches and deletes it on completion: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "secretsmanager:CreateSecret", "secretsmanager:DeleteSecret" ], "Resource": ["arn:aws:secretsmanager::*:secret:tower-*"] }, { "Effect": "Allow", "Action": ["secretsmanager:ListSecrets"], "Resource": ["*"] } ] } ``` **KMS for S3** — required if any of the S3 buckets used by the compute environment are encrypted with a customer-managed KMS key (SSE-KMS): ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "KmsS3Read", "Effect": "Allow", "Action": ["kms:Decrypt", "kms:DescribeKey"], "Resource": "arn:aws:kms:*:*:key/*", "Condition": { "StringLike": { "kms:ViaService": "s3.*.amazonaws.com" } } }, { "Sid": "KmsS3Write", "Effect": "Allow", "Action": ["kms:Encrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*"], "Resource": "arn:aws:kms:*:*:key/*", "Condition": { "StringLike": { "kms:ViaService": "s3.*.amazonaws.com" } } } ] } ``` :::note If your AWS account enforces EBS volume encryption at the account level (either via account default encryption settings or an SCP that requires `encrypted=true` on `RunInstances`), the EC2 instance will use a KMS key to encrypt its boot volume. In this case, the instance role must also have `kms:Decrypt`, `kms:GenerateDataKey`, `kms:CreateGrant`, and `kms:DescribeKey` permissions on the relevant KMS key — these are not included in the KMS for S3 policy above, which is scoped to S3 only. Contact your AWS administrator to identify the correct KMS key ARN and add permissions accordingly. ::: When you use a custom instance profile, note that Seqera will not create or manage the IAM role — you are responsible for keeping it up to date as requirements change. --- ## AWS Spot interruption management In AWS Batch environments that use Spot instances, tasks can be interrupted when instances are reclaimed, and this is a normal part of how Spot instances operate. The frequency of interruptions can be highly variable, based on factors including the wider demand on AWS services. AWS offers an insight into the frequency of Spot reclamations with their **instance-advisor** service which you can find [here](https://aws.amazon.com/ec2/spot/instance-advisor/). In Seqera Platform, Spot reclamations will sometimes manifest with logging messages like `Host EC2 (instance i-0282b396e52b4c95d) terminated` and will produce non-specific exit codes such as `143 (representing `SIGTERM`) or even no exit code at all (`-`), depending on the order in which the underlying AWS components have been destroyed. If you're seeing unexpected task failures with one or more of these features, especially with no obvious application error, it's worth reviewing your Spot configuration and retry strategy. This guide outlines best practices for mitigating the impact of Spot interruptions and ensuring critical tasks can retry or recover reliably. ## Recommended mitigations ### Use an On-Demand compute environment For workflows with a significant proportion of long-running processes, the costs of, and mitigations necessary for working with Spot may outweigh the benefits. You may find it simpler and even, possibly, cheaper to simply run those workloads in On-Demand compute environments. ### Move long-running tasks to On-Demand Tasks with long runtimes are particularly vulnerable to Spot termination. In Platform, you can explicitly assign critical or long-duration tasks to On-Demand queues and leave other tasks to run in a default Spot queue by default: ```bash process { withName: 'run_bcl2fastq' { queue = 'TowerForge-MyOnDemandQueue' } } ``` If you don’t already have one, you may need to create an On-Demand compute environment in the Seqera Platform. Once it’s available, you can find the corresponding On-Demand queue name by navigating to **Compute Environments** in the Platform UI. Locate the configuration for your specific On-Demand environment, then scroll down to the **Manual Config Attributes** section. This section lists key configuration details, including queue names. Look for the queue name prefixed with `TowerForge-` if it was created by Forge. ### Use retry strategies for Spot Interruptions #### Handle retries in Nextflow by setting `errorStrategy` and `maxRetries` A simple generic retry strategy at the Nextflow level can be more appropriate where run times are sufficiently low that retries are likely to succeed. This can be configured as follows: ```bash process { errorStrategy = 'retry' maxRetries = 3 } ``` This example configuration will apply to all types of job failure. Because Spot reclamations do not produce diagnostic exit codes, it is currently not possible to configure retries at the Nextflow level specifically for reclamations. Note that, given the escalating costs of repeated retries, an On-Demand queue is likely a more cost-effective option than very large numbers of retries. If you still see failures after applying configuration like this, solutions involving On-Demand queues are likely to be more effective at limiting costs and runtimes. #### Handle retries in AWS by setting `aws.batch.maxSpotAttempts` If all processes in your workflow have runtimes short enough to feasibly complete before reclamation, you can consider configuring automatic retries in case of interruption: `aws.batch.maxSpotAttempts = 3` This is a global setting (not configurable per process) that in this example allows a job to retry up to three times on a new Spot instance if the original instance is reclaimed. Retries happen automatically within AWS and restart the task from the beginning. Because this occurs behind the scenes, you won't see any evidence of the retries within the Platform. In fact, as far as Nextflow (and Platform) is concerned, only one attempt has occurred, and it will submit the task again to AWS, up to any `maxRetries` configuration you have in place (see above). The total number of retries in that case will be `maxRetries` * `aws.batch.maxSpotAttempts`. For a long running process being pre-empted repeatedly, this can represent very significant costs in time and compute. :::note Starting with Nextflow version 24.08.0-edge, the default value for this setting has been changed to `0` to help avoid unexpected expenses, and you should be careful when activating this setting. ::: ### Implement Spot-to-On-Demand fallback logic If you prefer to optimize for cost but ensure task reliability, consider a hybrid fallback pattern: ```bash process { withName: 'run_bcl2fastq' { errorStrategy = 'retry' maxRetries = 2 queue = { task.attempt > 1 ? 'TowerForge-MyOnDemandQueue' : 'TowerForge-MySpotQueue' } } } ``` With this setup, the first attempt of a task is sent to the Spot queue, while any retries are directed to the On-Demand queue, where they won't be preempted. This helps avoid repeated preemption of longer-running tasks and can serve as a useful default strategy. However, longer-running jobs should still be submitted directly to an On-Demand queue whenever possible, to avoid the unnecessary cost of the initial preemption. ### Consider enabling Fusion Snapshots (preview feature) Fusion Snapshots can help mitigate interruption risk by checkpointing task state before termination. This is currently in preview and best suited for compute-intensive or long-running tasks. If you're interested in testing this feature, reach out to our support team at https://support.seqera.io and we will be happy to assist you. --- ## Azure Batch :::note This guide assumes you already have an Azure account with a valid Azure Subscription. For details, visit [Azure Free Account][azure-free]. Ensure you have sufficient permissions to create resource groups, an Azure Storage account, and an Azure Batch account. ::: ## Azure concepts #### Regions Azure regions are specific geographic locations around the world where Microsoft has established data centers to host its cloud services. Each Azure region is a collection of data centers that provide users with high availability, fault tolerance, and low latency for cloud services. Each region offers a wide range of Azure services that can be chosen to optimize performance, ensure data residency compliance, and meet regulatory requirements. Azure regions also enable redundancy and disaster recovery options by allowing resources to be replicated across different regions, enhancing the resilience of applications and data. #### Resource groups An Azure resource group is a logical container that holds related Azure resources such as virtual machines, storage accounts, databases, and more. A resource group serves as a management boundary to organize, deploy, monitor, and manage the resources within it as a single entity. Resources in a resource group share the same lifecycle, meaning they can be deployed, updated, and deleted together. This also enables easier access control, monitoring, and cost management, making resource groups a foundational element in organizing and managing cloud infrastructure in Azure. #### Accounts Azure uses accounts for each service. For example, an [Azure Storage account][azure-storage-account] will house a collection of blob containers, file shares, queues, and tables. An Azure subscription can have multiple Azure Storage and Azure Batch accounts - however, a Platform compute environment can only use one of each. Multiple compute environments can be created to use separate credentials, Azure Storage accounts, and Azure Batch accounts. At a minimum, you will require an Azure Batch account and an Azure storage account to run pipelines with Azure Batch with Seqera. This is because Azure uses accounts for each service. #### Service principals An Azure service principal is an identity created specifically for applications, hosted services, or automated tools to access Azure resources. It acts like a user identity with a defined set of permissions, enabling resources authenticated through the service principal to perform actions within the Azure account. Seqera can utilize an Azure service principal to authenticate and access Azure Batch for job execution and Azure Storage for data management. ## Create Azure resources ### Resource group Create a resource group to link your Azure Batch and Azure Storage account: :::note A resource group can be created while creating an Azure Storage account or Azure Batch account. ::: 1. Log in to your Azure account, go to the [Create Resource group][azure-create-rg] page, and select **Create new resource group**. 2. Enter a name for the resource group, such as *seqeracompute*. 3. Choose the preferred region. 4. Select **Review and Create** to proceed. 5. Select **Create**. ### Storage account After creating a resource group, set up an [Azure Storage account][azure-storage-account]: 1. Log in to your Azure account, go to the [Create storage account][azure-create-storage] page, and select **Create a storage account**. :::note If you haven't created a resource group, you can do so now. ::: 2. Enter a name for the storage account, such as *seqeracomputestorage*. 3. Choose the preferred region. This must be the same region as the Batch account. 4. Platform supports all performance or redundancy settings. Select the most appropriate settings for your use case. 5. Select **Next: Advanced**. 6. Enable *storage account key access*. 7. Select **Next: Networking**. - Enable public access from all networks. You can enable public access from selected virtual networks and IP addresses, but you will be unable to use Forge to create compute resources. Disabling public access is not supported. 8. Select **Data protection**. - Configure appropriate settings. All settings are supported by Platform. 9. Select **Encryption**. - Only Microsoft-managed keys (MMK) are supported. 10. In **tags**, add any required tags for the storage account. 11. Select **Review and Create**. 12. Select **Create** to create the Azure Storage account. - You will need at least one Blob Storage container to act as a working directory for Nextflow. 13. Go to your new storage account and select **+ Container** to create a new Blob Storage container. A new container dialog will open. Enter a suitable name, such as *seqeracomputestorage-container*. 14. Go to the **Access Keys** section of your new storage account (*seqeracomputestorage* in this example). 15. Store the access keys for your Azure Storage account, to be used when you create a compute environment. :::caution Blob container storage credentials are associated with the Batch pool configuration. Avoid changing these credentials in Platform after you have created the compute environment. ::: ### Batch account After you have created a resource group and Storage account, create a [Batch account][azure-batch-account]: 1. Log in to your Azure account and select **Create a batch account** on [this page][azure-create-batch]. 2. Select the existing resource group or create a new one. 3. Enter a name for the Batch account, such as *seqeracomputebatch*. 4. Choose the preferred region. This must be the same region as the Storage account. 5. Select **Advanced**. 6. For **Pool allocation mode**, select **Batch service**. 7. For **Authentication mode**, select *Shared Key*. - Microsoft Entra ID is now the recommended credential mechanism for Azure authentication where supported. Use Shared Key here only if your setup requires it for compute environment configuration. 8. Select **Networking**. Ensure networking access is sufficient for Platform and any additional required resources. 9. Add any **Tags** to the Batch account, if needed. 10. Select **Review and Create**. 11. Select **Create**. 12. Go to your new Batch account, then select **Access Keys**. 13. Store the access keys for your Azure Batch account, to be used when you create a Seqera compute environment. :::caution A newly-created Azure Batch account may not be entitled to create virtual machines without making a service request to Azure. See [Azure Batch service quotas and limits][azure-batch-quotas] for more information. ::: 14. Select the **+ Quotas** tab of the Azure Batch account to check and increase existing quotas if necessary. 15. Select **+ Request quota increase** and add the quantity of resources you require. Here is a brief guideline: - **Active jobs and schedules**: Each Nextflow process will require an active Azure Batch job per pipeline while running, so increase this number to a high level. See [here][azure-batch-jobs] to learn more about jobs in Azure Batch. - **Pools**: Each platform compute environment requires at least one Azure Batch pool. Batch Forge creates two pools by default (one for the head job and one for compute tasks). Each pool is composed of multiple machines of one virtual machine size. - **Batch accounts per region per subscription**: Set this to the number of Azure Batch accounts per region per subscription. Only one is required. - **Spot/low-priority vCPUs**: Platform does not support spot or low-priority machines when using Forge, so when using Forge this number can be zero. When manually setting up a pool, select an appropriate number of concurrent vCPUs here. - **Total Dedicated vCPUs per VM series**: See the Azure documentation for [virtual machine sizes][azure-vm-sizes] to help determine the machine size you need. We recommend the latest version of the ED series available in your region as a cost-effective and appropriately-sized machine for running Nextflow. However, you will need to select alternative machine series that have additional requirements, such as those with additional GPUs or faster storage. Increase the quota by the number of required concurrent CPUs. In Azure, machines are charged per cpu minute so there is no additional cost for a higher number. ### Credentials There are two types of Azure credentials available: access keys and Entra service principals. Access keys are simple to use but have several limitations: - Access keys are long-lived. - Access keys provide full access to the Azure Storage and Azure Batch accounts. - Azure allows only two access keys per account, making them a single point of failure. - Access keys do not support VNet/subnet configuration. Entra service principals are accounts which can be granted access to Azure Batch and Azure Storage resources: - Service principals enable role-based access control with more precise permissions. - Service principals map to a many-to-many relationship with Azure Batch and Azure Storage accounts. - Some Azure Batch features, such as VNet/subnet configuration, are only available when using a service principal. Both credential types support Batch Forge and Manual compute environment modes. :::note The two Azure credential types use different authentication methods. You can add more than one credential to a workspace, but Platform compute environments use only one credential at any given time. While separate credentials can be used by separate compute environments concurrently, they are not cross-compatible — access granted by one credential will not be shared with the other. ::: #### Access keys To create an access key: 1. Navigate to the Azure Portal and sign in. 2. Locate the Azure Batch account and select **Keys** under **Account management**. The Primary and Secondary keys are listed here. Copy one of the keys and save it in a secure location for later use. 3. Locate the Azure Storage account and, under the **Security and Networking** section, select **Access keys**. Key1 and Key2 options are listed here. Copy one of them and save it in a secure location for later use. 4. In your Platform workspace **Credentials** tab, select the **Add credentials** button and complete the following fields: - Enter a **Name** for the credentials - **Provider**: Azure - Select the **Shared key** tab - Add the **Batch account** and **Blob Storage account** names and access keys to the relevant fields. 5. Delete the copied keys from their temporary location after they have been added to a credential in Platform. #### Entra service principal and managed identity To use Entra for authentication, you must create a service principal and managed identity. Seqera uses the service principal to authenticate to Azure Batch and Azure Storage. It submits a Nextflow task as the head process to run Nextflow, which authenticates to Azure Batch and Storage using the managed identity attached to the node pool. Therefore, you must create both an Entra service principal and a managed identity: 1. Add the service principal details as credentials in Seqera Platform. 2. Assign the managed identity to each Azure Batch node pool with the relevant permissions. 3. When using Batch Forge, provide the managed identity resource ID for each managed identity. Seqera Platform assigns the identity to each pool during creation. :::note Entra service principal credentials support both Batch Forge and Manual compute environments. Some features, such as VNet/subnet configuration and managed identities, require Entra credentials. When using Entra credentials, a managed identity is recommended for best security practices, but is not mandatory. ::: ##### Service principal See [Create a service principal][azure-create-sp] for more details. To create an Entra service principal: 1. In the Azure Portal, navigate to **Microsoft Entra ID**. Under **App registrations**, select **New registration**. 2. Provide a name for the application. The application will automatically have a service principal associated with it. 3. Assign roles to the service principal: 1. Go to the Azure Storage account. Under **Access Control (IAM)**, select **Add role assignment**. 2. Select the **Storage Blob Data Contributor** role. 3. Select **Members**, then **Select Members**. Search for your newly created service principal and assign the role. 4. Repeat the same process for the Azure Batch account, using the **Azure Batch Data Contributor** role. This role is sufficient for pool creation and is narrower than the general **Azure Batch Account Contributor** role. 5. If you create a managed identity (recommended), also assign the **Managed Identity Operator** role to the service principal on each managed identity. Without this role, Seqera cannot attach the managed identity to a Batch pool. 6. If you plan to deploy Batch pools into a private VNet (by specifying a Subnet ID when creating the compute environment), also assign the Network Contributor role (or a custom role granting `Microsoft.Network/virtualNetworks/subnets/join/action`) to the service principal on the VNet. Only the service principal needs VNet permissions (the head and pool managed identities do not). 4. Platform will need credentials to authenticate as the service principal: 1. Navigate back to the app registration. On the **Overview** page, save the **Application (client) ID** value for use in Platform. 2. Select **Certificates & secrets**, then **New client secret**. A new secret is created containing a value and secret ID. Save both values securely for use in Platform. 5. In your Platform workspace **Credentials** tab, select the **Add credentials** button and complete the following fields: - Enter a **Name** for the credentials - **Provider**: Azure - Select the **Entra** tab - Complete the remaining fields: **Batch account name**, **Blob Storage account name**, **Tenant ID** (Directory (tenant) ID in Azure), **Client ID** (Application (client) ID in Azure), **Client secret** (Client secret value in Azure). 6. Delete the ID and secret values from their temporary location after they have been added to a credential in Platform. ##### Managed identity :::info To use managed identities, Platform requires Nextflow version 24.06.0-edge or later. ::: Nextflow can authenticate to Azure services using a managed identity. This method offers enhanced security compared to access keys, but it must run on Azure infrastructure and requires Entra service principal credentials. Pool creation with a managed identity attached uses the Azure Batch management plane, which only accepts Entra (AAD) tokens, so shared-key credentials cannot create pools with managed identities. When you use a compute environment with a managed identity attached to the Azure Batch pool, Nextflow uses this managed identity for authentication. Seqera still uses the Entra service principal to submit the initial Nextflow task; that task then proceeds with the managed identity for subsequent authentication. When you don't attach a head managed identity, Platform passes the service principal credentials to the head job so it can authenticate to Azure Storage and Azure Container Registry at runtime. This places a long-lived secret on the compute node. Attaching a user-assigned managed identity removes that secret — the VM obtains short-lived tokens from the Azure Instance Metadata Service instead. For this reason, a managed identity is recommended for production deployments. The same applies to the worker pool managed identity used by compute tasks. 1. In Azure, create a user-assigned managed identity. See [Manage user-assigned managed identities][azure-managed-identity] for detailed steps. Take note of both the **client ID** and the **resource ID** of the managed identity when you create it. 2. Assign the following roles to the managed identity: - **Storage Blob Data Contributor** on the Azure Storage account, so the pool VMs can read inputs and write outputs. - **AcrPull** on any Azure Container Registry the pipeline pulls images from. Without this role, container pulls fail when the pool VM authenticates via the managed identity. See [Required role assignments][nf-azure-roles] for more information. 3. Associate the user-assigned managed identity with the Azure Batch pool. See [Set up managed identity in your Batch pool][azure-batch-mi-pool] for more information. :::note When you use separate head and worker pools, you can assign a different managed identity to each pool. Typically, the head managed identity needs broader Batch and storage permissions, while the worker managed identity only needs storage and `AcrPull` access. ::: 4. When you set up the Seqera compute environment, provide the managed identity details in the specified fields. The form has four managed identity fields — a **client ID** and a **resource ID** for both the head pool and the worker pool: - **Resource IDs** are the full ARM paths of the managed identities (e.g., `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}`). Seqera passes these to Azure Batch at pool-create time to attach the managed identity to the head pool and worker pool VMs respectively. Resource IDs are required when using Batch Forge. - **Client IDs** are passed to Nextflow, Fusion, and AzCopy on the pool VMs. The Azure Instance Metadata Service uses the client ID to mint a token for the correct managed identity. A VM can have multiple managed identities attached, so the consumer must specify which one to use. You can use the same managed identity for both head and worker pools by entering the same values in both pairs of fields, but separate identities are recommended so that worker RBAC can stay narrower than head RBAC. The four fields work for both single-pool and dual-pool topologies: - **Single-pool** (head pool only): both managed identities are attached to the same VMs. The client IDs are required to disambiguate which managed identity each consumer authenticates as — when a VM has more than one user-assigned managed identity, the Azure Instance Metadata Service (IMDS) does not pick a default, so each consumer must pass its UAMI's `client_id` on the IMDS request. - **Dual-pool** (separate head and worker pools): each pool has only its own managed identity attached, so disambiguation is implicit at the VM level. The client IDs are still required so that consumers know which managed identity is theirs. When you submit a pipeline to this compute environment, Nextflow authenticates using the managed identity associated with the Azure Batch node it runs on, rather than relying on access keys. :::caution If a managed identity is misconfigured (e.g., invalid client ID or missing RBAC roles), the pipeline fails with an explicit error. Seqera does not silently fall back to the service principal at runtime. ::: ## Add compute environment There are two ways to create an Azure Batch compute environment in Platform: - [**Batch Forge**](#batch-forge): Automatically creates Azure Batch resources. - [**Manual**](#manual): For using existing Azure Batch resources. ### VM size considerations Azure Batch requires you to select an appropriate VM size for your compute environment. There are a number of considerations when selecting VM sizes. See [Sizes for virtual machines in Azure][azure-vm-sizes-overview] for more information. 1. **Family**: The first letter of the VM size name indicates the machine family. For example, `Standard_E16d_v5` is a member of the E family. - *A*: Economical machines, low power machines. - *B*: Burstable machines which use credits for cost allocation. - *D*: General purpose machines suitable for most applications. - *DC*: D machines with additional confidential compute capabilities. - *E*: The same as D but with more memory. These are generally the best machines for bioinformatics workloads. - *EC*: The same as E but with additional confidential compute capabilities. - *F*: Compute optimized machines which come with a faster CPU compared to D-series machines. - *M*: Memory optimized machines which come with extremely large and fast memory layers, typically more than is needed for bioinformatics workloads. - *L*: Storage optimized machines which come with large locally attached NVMe storage drives. Note that these need to be configured before you can use them with Azure Batch. - *N*: Accelerated computing machines which come with FPGAs, GPUs, or custom ASICs. - *H*: High performance machines which come with the fastest processors and memory. In general, we recommend using the E family of machines for bioinformatics workloads since these are cost-effective, widely available, and sufficiently fast. 1. **vCPUs**: The machine's number of vCPUs. This is the main factor in determining the speed of the machine. 2. **features**: Additional machine features. For example, some machines come with a local SSD. - d: A local storage disk. Azure Batch can use this disk automatically instead of the operating system disk. - s: The VM supports a [premium storage account][azure-premium-storage]. - a: AMD CPUs instead of Intel. - p: ARM-based CPUs, such as Azure Cobalt. - l: Reduced memory with a large cost reduction. 3. **Version**: The version of the VM size. This is the generation of the machine. Typically, more recent is better but availability can vary between regions. In the Azure Portal on the page for your Azure Batch account, request an appropriate quota for your desired VM size. See [Azure Batch service quotas and limits][azure-batch-quotas] for more information. ### Batch Forge :::caution Batch Forge automatically creates resources that you may be charged for in your Azure account. See [Cloud costs][cloud-costs] for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: Create a Batch Forge Azure Batch compute environment: 1. In a workspace, select **Compute Environments > New Environment**. 2. Enter a descriptive name, such as *Azure Batch (east-us)*. 3. Select **Azure Batch** as the target platform. 4. Choose existing Azure credentials or add a new credential. :::note Both access keys and Entra service principal credentials are supported for Batch Forge. Some features, such as VNet/subnet configuration, require Entra credentials. ::: 5. Add the **Batch account** and **Blob Storage** account names and access keys. 6. Select a **Region**, such as *eastus*. 7. In the **Work directory** field, enter the Azure blob container created previously. For example, `az://seqeracomputestorage-container/work`. :::note When you specify a Blob Storage bucket as your work directory, this bucket is used for the Nextflow [cloud cache][nf-cloud-cache] by default. You can specify an alternative cache location with the **Nextflow config file** field on the pipeline [launch][launch-form] form. ::: 8. Select **Enable Wave containers** to facilitate access to private container repositories and provision containers in your pipelines using the Wave containers service. See [Wave containers][wave] for more information. 9. Select **Enable Fusion v2** to allow access to your Azure Blob Storage data via the [Fusion v2][fusion] virtual distributed file system. This speeds up most data operations. The Fusion v2 file system requires Wave containers to be enabled. See [Fusion file system][fusion-overview] for configuration details.
Use Fusion v2 :::note The compute recommendations below are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. ::: Azure virtual machines include fast SSDs and require no additional storage configuration for Fusion. For optimal performance, use VMs with sufficient local storage to support Fusion's streaming data throughput. 1. Use Seqera Platform version 23.1 or later. 2. Use an Azure Blob storage container as the work directory. 3. Enable **Wave containers** and **Fusion v2**. 4. Select the **Batch Forge** config mode. 5. Specify suitable VM sizes under **VMs type**. A `Standard_E16d_v5` VM or larger is recommended for production use. :::tip We recommend selecting machine types with a local temp storage disk of at least 200 GB and a random read speed of 1000 MBps or more for large and long-lived production pipelines. To work with files larger than 100 GB, increase temp storage accordingly (400 GB or more). The suffix `d` after the core number (e.g., `Standard_E16*d*_v5`) denotes a VM with a local temp disk. Select instances with Standard SSDs — Fusion does not support Azure network-attached storage (Premium SSDv2, Ultra Disk, etc.). Larger local storage increases Fusion's throughput and reduces the chance of overloading the machine. See [Sizes for virtual machines in Azure][azure-vm-sizes-overview] for more information. :::
10. (Optional) Enter a **Subnet ID** to connect the Batch pool nodes to a private Azure VNet. Enter the full Azure ARM subnet resource ID in the following format: ``` /subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Network/virtualNetworks/{vnetName}/subnets/{subnetName} ``` :::note VNet/subnet configuration requires Entra credentials. This field is only available when Entra credentials are selected. If no subnet ID is provided, default networking is used. The service principal must have the **Network Contributor** role (or `Microsoft.Network/virtualNetworks/subnets/join/action`) on the VNet, otherwise pool creation fails. ::: 11. Set the **Config mode** to **Batch Forge**. 12. Enter the default **VMs type** for compute tasks, depending on your quota limits set previously. The default is _Standard_D4_v3_. 13. Enter the **VMs count**. If autoscaling is enabled (default), this is the maximum number of VMs the compute pool will scale up to. If autoscaling is disabled, this is the fixed number of virtual machines in the compute pool. 14. (Optional) Configure **Head job resources** to control the VM type and resources allocated to the Nextflow head job: - **Head VM type**: The VM size for the head node pool. If not specified, the same VM type as the compute pool is used. - **Head job CPUs**: The number of CPUs allocated to the Nextflow head job. - **Head job memory**: The amount of memory allocated to the Nextflow head job. 15. Enable **Autoscale** to scale the compute pool up and down automatically, based on the number of pipeline tasks. The number of VMs will vary from **0** to **VMs count**. 16. Enable **Dispose resources** for Seqera to automatically delete the Batch pools if the compute environment is deleted on the platform. :::info Batch Forge creates separate Azure Batch pools for the Nextflow head job and compute tasks by default (named `tower-pool-{envId}-head` and `tower-pool-{envId}-worker`). This prevents the head node from competing for resources with compute tasks and allows independent sizing of each pool. See [Batch service quotas and limits](https://learn.microsoft.com/en-us/azure/batch/batch-quota-limit) for information about limits when running multiple compute environments. ::: 17. Select or create [**Container registry credentials**][azure-registry-credentials] to authenticate a registry (used by the [Wave containers][nf-wave] service). It is recommended to use an [Azure Container registry][azure-container-registry] within the same region for maximum performance. 18. Apply [**Resource labels**][resource-labels]. This will populate the **Metadata** fields of the Azure Batch pools and jobs. 19. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts][pre-post-run-scripts] that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file][nf-config-file] for more information on configuration priority. ::: 20. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 21. Configure any advanced options you need: - Use **Max wallclock time** to set the maximum duration a job can run. The default is 7 days. Accepts human-readable duration syntax (e.g., `7d`, `12h`, `1d6h30m`). The maximum allowed by Azure Batch is 180 days. Existing compute environments without this setting use Nextflow's default of 30 days. - **Job cleanup toggles** control how Nextflow process jobs are managed on completion. Active jobs consume the quota of your Azure Batch account. Three independent toggles are available: | Toggle | Default | Description | |--------|---------|-------------| | **Delete jobs on completion** | Off | Permanently deletes all jobs and their tasks from Azure Batch when the workflow finishes. | | **Delete tasks on completion** | On | Deletes individual tasks from jobs when they complete successfully. Failed tasks are preserved for debugging. | | **Terminate jobs on completion** | On | Sets jobs to terminate when all their tasks complete. Jobs remain in "completed" state but are no longer active. | Existing compute environments retain their current cleanup behavior. - Use **Token duration** to control the duration of the SAS token generated by Nextflow. This must be as long as the longest period of time the pipeline will run. 22. Select **Add** to finalize the compute environment setup. It will take a few seconds for all the resources to be created before the compute environment is ready to launch pipelines. :::info See [Launch pipelines][launch-pipelines] to start executing workflows in your Azure Batch compute environment. ::: ### Manual You can configure Seqera Platform to use a pre-existing Azure Batch pool. This allows the use of more advanced Azure Batch features, such as custom VM images and private networking. See [Azure Batch security best practices][azure-batch-security] for more information. :::caution Your Seqera compute environment uses resources that you may be charged for in your Azure account. See [Cloud costs][cloud-costs] for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: #### Create a Nextflow-compatible Azure Batch pool If not described below, use the default settings: 1. **Account**: You must have an existing Azure Batch account. Ideally, you should already have tested whether you can run an Azure Batch task within this account. Any type of account is compatible. 2. **Quota**: You must check you have sufficient quota for the number of pools, jobs, and vCPUs per series. See [Azure Batch service quotas and limits][azure-batch-quotas] for more information. 3. On the Azure Batch page of the Azure Portal, select **Pools** and then **+ Add**. 4. **Name**: Enter a **Pool ID** and **Display Name**. This ID will be used by Seqera and Nextflow. 5. **Identity**: Select **User assigned** to use a managed identity for the pool. Select **Add** for the user-assigned managed identity and select the managed identity with the correct permissions to the Azure Storage and Batch accounts. 6. **Operating System**: You can use any Linux-based image here, but it is recommended to use it with a Microsoft Azure Batch-provided image. Note that there are two generations of Azure Virtual Machine images, and certain VM series are only available in one generation. See [Azure Virtual Machine series][azure-vm-gen2] for more information. For default settings, select the following: - **Publisher**: `microsoft-dsvm` - **Offer**: `ubuntu-hpc` - **Sku**: `2204` - **Security type**: `standard` 7. **OS disk storage account type**: Certain VM series only support a specific Storage account type. See [Azure managed disk types][azure-disk-types] and [Azure Virtual Machine series][azure-vm-gen2] for more information. In general, a VM series with the suffix *s* supports a *Premium LRS* Storage account type. For example, a `standard_e16ds_v5` supports `Premium_LRS` but a `standard_e16d_v5` does not. Premium LRS offers the best performance. 8. **OS disk size**: The size of the OS disk in GB. This must be sufficient to hold every Docker container the VM will run, plus any logging or further files. If you are not using a machine with attached storage, you must increase this disk size to accommodate task files (see VM type below). If you are using a machine with attached storage, this setting can be left at the OS default size. 9. **Container configuration**: Container configuration must be turned on. Do this by switching it from **None** to **Custom**. The type is **Docker compatible** which should be the only available option. This will enable the VM to use Docker images and is sufficient. However, you can add further options: - Under **Container image names** you can add containers for the VM to grab at startup time. Add a list of fully qualified Docker URIs, such as `quay.io/seqeralabs/nf-launcher:j17-23.04.2`. - Under **Container registries**, you can add any container registries that require additional authentication. Select **Container registries**, then **Add**. Here, you can add a registry username, password, and registry server. If you attached the managed identity earlier, select this as an authentication method so you don't have to enter a username and password. 10. **VM size**: This is the size of the VM. See [Sizes for virtual machines in Azure][azure-vm-sizes] for more information. 11. **Scale**: Azure Node pools can be fixed in size or autoscale based on a formula. Autoscaling is recommended to enable scaling your resources down to zero when not in use. Select **Auto scale** and change the **AutoScale evaluation interval** to 5 minutes - this is the minimum period between evaluations of the autoscale formula. For **Formula**, you can use any valid formula — See [Create a formula to automatically scale compute nodes in a Batch pool][azure-autoscale] for more information. This is the default autoscaling formula, with a maximum of 8 VMs: ``` // Get pool lifetime since creation. lifespan = time() - time("2024-10-30T00:00:00.880011Z"); interval = TimeInterval_Minute * 5; // Compute the target nodes based on pending tasks. // $PendingTasks == The sum of $ActiveTasks and $RunningTasks $samples = $PendingTasks.GetSamplePercent(interval); $tasks = $samples < 70 ? max(0, $PendingTasks.GetSample(1)) : max( $PendingTasks.GetSample(1), avg($PendingTasks.GetSample(interval))); $targetVMs = $tasks > 0 ? $tasks : max(0, $TargetDedicatedNodes/2); targetPoolSize = max(0, min($targetVMs, 8)); // For first interval, deploy 1 node, for other intervals scale up/down as per tasks. $TargetDedicatedNodes = lifespan < interval ? 1 : targetPoolSize; $NodeDeallocationOption = taskcompletion; ``` 12. **Start task**: This is the task that will run on each VM when it joins the pool. This can be used to install additional software on the VM. When using Batch Forge, this is used to install `azcopy` for staging files onto and off of the node. Select **Enabled** and add the following command line to install `azcopy`: ```shell bash -c "chmod +x azcopy && mkdir $AZ_BATCH_NODE_SHARED_DIR/bin/ && cp azcopy $AZ_BATCH_NODE_SHARED_DIR/bin/" ``` Select **Resource files** then select **Http url**. For the **URL**, add `https://nf-xpack.seqera.io/azcopy/linux_amd64_10.8.0/azcopy` and for **File path** enter `azcopy`. Every other setting can be left default. :::note When not using Fusion, every node **must** have `azcopy` installed. ::: 13. **Task Slots**: Set task slots to the machine's number of vCPUs. For example, select `4` for a `Standard_D4_v3` VM size. 14. **Task scheduling policy**: This can be set to `Pack` or `Spread`. `Pack` will attempt to schedule tasks from the same job on the same VM, while `Spread` will attempt to distribute tasks evenly across VMs. 15. **Virtual Network**: If you are using a virtual network, you can select it here. Be sure to select the correct virtual network and subnet. The VMs require: - Access to container registries (such as quay.io and docker.io) to pull containers. - Access to Azure Storage to copy data using `azcopy`. - Access to any remote files required by the pipeline, such as AWS S3 storage. - Communication with the head node that runs Nextflow and Seqera to relay logs and information. Note that overly-restrictive networking may prevent pipelines from running successfully. 16. **Mount configuration**: Nextflow *only* supports Azure File Shares. Select `Azure Files Share`, then add: - **Source**: URL in format `https://${accountName}.file.core.windows.net/${fileShareName}` - **Relative mount path**: Path where the file share will be mounted on the VM - **Storage account name** and **Storage account key** (managed identity is not supported) Leave the node pool to start and create a single Azure VM. Monitor the VM to ensure it starts correctly. If any errors occur, check and correct them - you may need to create a new Azure node pool if issues persist. The following settings can be modified after creating a pool: - Autoscale formula - Start task - Application packages - Node communication - Metadata #### Create a manual Seqera Azure Batch compute environment 1. In a workspace, select **Compute Environments**, then **Add compute environment**. 2. Enter a descriptive name for this environment, such as *Azure Batch (east-us)*. 3. For **Provider**, select **Azure Batch**. 4. Select your existing Azure credentials (access keys or Entra service principal) or select **+** to add new credentials. :::note Both access keys and Entra service principal credentials are supported. Some features, such as VNet/subnet configuration, require Entra credentials. To use Entra with a managed identity, see [Managed identity](#managed-identity) below. ::: 5. Select a **Region**, such as *eastus (East US)*. 6. In the **Work directory** field, add the Azure blob container created previously. For example, `az://seqeracomputestorage-container/work`. :::note When you specify a Blob Storage bucket as your work directory, this bucket is used for the Nextflow [cloud cache][nf-cloud-cache] by default. You can specify an alternative cache location with the **Nextflow config file** field on the pipeline [launch][launch-form] form. ::: 7. Select **Enable Wave containers** to facilitate access to private container repositories and provision containers in your pipelines using the Wave containers service. See [Wave containers][wave] for more information. 8. Select **Enable Fusion v2** to allow access to your Azure Blob Storage data via the [Fusion v2][fusion] virtual distributed file system. This speeds up most data operations. The Fusion v2 file system requires Wave containers to be enabled. See [Fusion file system][fusion-overview] for configuration details.
Use Fusion v2 :::note The compute recommendations below are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. ::: Azure virtual machines include fast SSDs and require no additional storage configuration for Fusion. For optimal performance, use VMs with sufficient local storage to support Fusion's streaming data throughput. 1. Use Seqera Platform version 23.1 or later. 2. Use an Azure Blob storage container as the work directory. 3. Enable **Wave containers** and **Fusion v2**. 4. Specify suitable VM sizes under **VMs type**. A `Standard_E16d_v5` VM or larger is recommended for production use. :::tip We recommend selecting machine types with a local temp storage disk of at least 200 GB and a random read speed of 1000 MBps or more for large and long-lived production pipelines. To work with files larger than 100 GB, increase temp storage accordingly (400 GB or more). The suffix `d` after the core number (e.g., `Standard_E16*d*_v5`) denotes a VM with a local temp disk. Select instances with Standard SSDs — Fusion does not support Azure network-attached storage (Premium SSDv2, Ultra Disk, etc.). Larger local storage increases Fusion's throughput and reduces the chance of overloading the machine. See [Sizes for virtual machines in Azure][azure-vm-sizes-overview] for more information. :::
9. (Optional) Enter a **Subnet ID** to connect the Batch pool nodes to a private Azure VNet. Enter the full Azure ARM subnet resource ID in the following format: ``` /subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Network/virtualNetworks/{vnetName}/subnets/{subnetName} ``` :::note VNet/subnet configuration requires Entra credentials. This field is only available when Entra credentials are selected. If no subnet ID is provided, default networking is used. The service principal must have the **Network Contributor** role (or `Microsoft.Network/virtualNetworks/subnets/join/action`) on the VNet, otherwise pool creation fails. ::: 10. Set the **Config mode** to **Manual**. 11. Enter the **Head Pool name**. This is the name of the Azure Batch pool for the Nextflow head job. 12. (Optional) Enter a **Compute Pool name** for worker tasks. If not specified, the head pool is used for both head and compute tasks (single-pool mode). :::tip Using separate pools for head and compute nodes allows you to right-size each pool independently. For example, you can use a smaller VM for the Nextflow head job and larger VMs for compute-intensive tasks. ::: 13. Enter user-assigned **Managed identity client IDs** (and optionally **resource IDs**), if managed identities are attached to your Azure Batch pools. In dual-pool mode, you can specify separate managed identities for the head and compute pools. See [Managed Identity](#managed-identity) below. 14. Apply [**Resource labels**][resource-labels]. This will populate the **Metadata** fields of the Azure Batch pools and jobs. 15. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts][pre-post-run-scripts] that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file][nf-config-file] for more information on configuration priority. ::: 16. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 17. Configure any advanced options you need: - Use **Max wallclock time** to set the maximum duration a job can run. The default is 7 days. Accepts human-readable duration syntax (e.g., `7d`, `12h`, `1d6h30m`). The maximum allowed by Azure Batch is 180 days. Existing compute environments without this setting use Nextflow's default of 30 days. - **Job cleanup toggles** control how Nextflow process jobs are managed on completion. Active jobs consume the quota of your Azure Batch account. Three independent toggles are available: | Toggle | Default | Description | |--------|---------|-------------| | **Delete jobs on completion** | Off | Permanently deletes all jobs and their tasks from Azure Batch when the workflow finishes. | | **Delete tasks on completion** | On | Deletes individual tasks from jobs when they complete successfully. Failed tasks are preserved for debugging. | | **Terminate jobs on completion** | On | Sets jobs to terminate when all their tasks complete. Jobs remain in "completed" state but are no longer active. | Existing compute environments retain their current cleanup behavior. - Use **Token duration** to control the duration of the SAS token generated by Nextflow. This must be as long as the longest period of time the pipeline will run. 18. Select **Add** to complete the compute environment setup. The creation of resources will take a few seconds, after which you can launch pipelines. :::info See [Launch pipelines][launch-pipelines] to start executing workflows in your Azure Batch compute environment. ::: ## Fusion on Azure Batch with Ubuntu 24.04 The `ubuntu-hpc` image in Azure Batch now defaults to Ubuntu 24.04, whose kernel and AppArmor policy block the unprivileged user namespaces and FUSE mounts Fusion needs. Running Fusion on Ubuntu 24.04+ pools therefore requires an AppArmor profile that permits Fusion mounts to be loaded on every node, plus a matching `--security-opt` on each task container. **Forge compute environments** Seqera Platform handles everything automatically. No action required. **Manual compute environments** When Fusion is enabled and the pool's image SKU is 2404 or higher, Seqera Platform will automatically append the options below to the generated Nextflow configuration: `process.containerOptions = '--security-opt apparmor=seqera-fusionfs-container'` ### Install the AppArmor profile on pool nodes A Fusion-specific seqera-fusionfs-container AppArmor profile must be loaded into the kernel on every node before any Fusion tasks run. The contents of the profile are as follows: ``` abi , include profile seqera-fusionfs-container flags=(default_allow) { userns, mount fstype=fuse.fusion -> /fusion/, mount fstype=fuse.fusion -> /fusion/**, umount, include include include if exists } ``` The profile can be delivered into the nodes by any suitable mechanism: for example, it can be embedded in a custom VM image, distributed via configuration management, or written during node bootstrap. Note that the profile name (`seqera-fusionfs-container`) is mandatory because Seqera Platform code will refer to it, but its location and load mechanism are flexible. Here are some common ways to get the profile loaded: - Drop the file at `/etc/apparmor.d/seqera-fusionfs-container` in a custom VM image. Ubuntu's apparmor.service will automatically load profiles from `/etc/apparmor.d/` at boot, so no explicit loading is needed. - Place the profile anywhere and call `apparmor_parser -r ` to load the profile during node bootstrap (pool start task, cloud-init, configuration management run). This is what Seqera Platform does for Forge-provisioned compute environments. - Place the profile in a subdirectory and configure a boot-time `systemd` unit that runs `apparmor_parser -r` against it on every boot. This is useful if the profile lives in a non-standard location to ensure the profile is re-loaded after every reboot. ### Caveat: overriding `process.containerOptions` A `process.containerOptions` value explicitly set in a compute environment's Nextflow config field will override the one Platform injects. For these cases, including `seqera-fusionfs-container` as a Docker `security-opt` is mandatory: `process.containerOptions = '--security-opt apparmor=seqera-fusionfs-container '` ### Troubleshooting Run the following checks by SSHing into a pool node: ``` # 1.Is the profile loaded into the kernel on this node? aa-status | grep seqera-fusionfs-container # 2. Is the profile applied to a running task container? docker inspect --format '{{.AppArmorProfile}}' ``` | Symptom | Likely cause | |--------|---------| | Workflow task fails with `Operation not permitted` on `/fusion/`, host `dmesg` / `/var/log/kern.log` shows `apparmor="DENIED" ... profile="docker-default"` | The AppArmor profile is loaded on the node, but `--security-opt apparmor=seqera-fusionfs-container` is not being applied. Check whether `process.containerOptions` is overridden in the compute environment's Nextflow config | | `apparmor="DENIED" ... profile="unconfined"` or `aa-status` does not list `seqera-fusionfs-container` | The profile is not loaded on this node. Re-run `apparmor_parser -r ` or fix the boot-time mechanism that should load it. | | `apparmor_parser` itself fails with a syntax error | The profile contents were corrupted in transit (check for stray indentation or encoding changes). Compare against the canonical version above. | | Task container shows `AppArmorProfile: seqera-fusionfs-container` but Fusion still fails to mount | AppArmor is not the issue. Check the Fusion logs and that the FUSE device (`/dev/fuse`) is available inside the container. | [azure-free]: https://azure.microsoft.com/en-us/free/ [azure-storage-account]: https://learn.microsoft.com/en-us/azure/storage/common/storage-account-overview [azure-create-rg]: https://portal.azure.com/#create/Microsoft.ResourceGroup [azure-create-storage]: https://portal.azure.com/#create/Microsoft.StorageAccount-ARM [azure-batch-account]: https://learn.microsoft.com/en-us/training/modules/create-batch-account-using-azure-portal/ [azure-create-batch]: https://portal.azure.com/#create/Microsoft.BatchAccount [azure-batch-quotas]: https://docs.microsoft.com/en-us/azure/batch/batch-quota-limit#view-batch-quotas [azure-batch-jobs]: https://learn.microsoft.com/en-us/azure/batch/jobs-and-tasks [azure-vm-sizes]: https://learn.microsoft.com/en-us/azure/virtual-machines/sizes [azure-vm-sizes-overview]: https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/overview [azure-premium-storage]: https://learn.microsoft.com/en-us/azure/virtual-machines/premium-storage-performance [azure-create-sp]: https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal [azure-managed-identity]: https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities [azure-batch-mi-pool]: https://learn.microsoft.com/en-us/troubleshoot/azure/hpc/batch/use-managed-identities-azure-batch-account-pool#set-up-managed-identity-in-your-batch-pool [azure-batch-security]: https://learn.microsoft.com/en-us/azure/batch/security-best-practices [azure-vm-gen2]: https://learn.microsoft.com/en-us/azure/virtual-machines/generation-2 [azure-disk-types]: https://learn.microsoft.com/en-us/azure/virtual-machines/disks-types [azure-autoscale]: https://learn.microsoft.com/en-us/azure/batch/batch-automatic-scaling [azure-container-registry]: https://azure.microsoft.com/en-gb/products/container-registry [nf-azure-roles]: https://docs.seqera.io/nextflow/azure#required-role-assignments [nf-cloud-cache]: https://docs.seqera.io/nextflow/cache-and-resume#cache-stores [nf-wave]: https://docs.seqera.io/nextflow/wave [nf-config-file]: https://docs.seqera.io/platform-enterprise/launch/advanced#nextflow-config-file [wave]: https://docs.seqera.io/wave [fusion]: https://docs.seqera.io/fusion [fusion-overview]: https://docs.seqera.io/platform-enterprise/supported_software/fusion/overview [cloud-costs]: https://docs.seqera.io/platform-enterprise/monitoring/cloud-costs [launch-pipelines]: https://docs.seqera.io/platform-enterprise/launch/launchpad [launch-form]: https://docs.seqera.io/platform-enterprise/launch/launchpad#launch-form [pre-post-run-scripts]: https://docs.seqera.io/platform-enterprise/launch/advanced#pre-and-post-run-scripts [resource-labels]: https://docs.seqera.io/platform-enterprise/resource-labels/overview [azure-registry-credentials]: https://docs.seqera.io/platform-enterprise/credentials/azure_registry_credentials --- ## Azure Cloud :::note This compute environment type is currently in public preview. Please consult this guide for the latest information on recommended configuration and limitations. This guide assumes you already have an Azure account with a valid Azure subscription. ::: Many of the current implementations of compute environments for cloud providers rely on the use of batch services such as AWS Batch, Azure Batch, and Google Batch for the execution and management of submitted jobs, including pipelines and Studio session environments. Batch services are suitable for large-scale workloads, but they add management complexity. In practical terms, the currently used batch services result in some limitations: - **Complex setup**: Azure Batch compute environments require users to independently configure their own Batch accounts. - **Long-lived credentials**: Azure Batch uses access keys to authenticate with Batch and Storage accounts. These credentials are long-lived, and Azure has hard limits on the number of access keys that can be created per resource type. - **Quotas**: Azure Batch accounts have limits for jobs, pools, and compute resources. If these limits are exceeded, no additional pipelines can run until the existing resources are removed. The Azure Cloud compute environment addresses these pain points with: - **Simplified configuration**: Fewer configurable options, with opinionated defaults, provide the best Nextflow pipeline and Studio session execution environment, with both [Wave](https://docs.seqera.io/wave) and [Fusion](https://docs.seqera.io/fusion) enabled. - **More secure credentials**: Authenticate exclusively via [Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/what-is-entra). This provides enhanced security by default, with automatic configuration for the user. This type of compute environment is best suited to run Studios and small to medium-sized pipelines. It offers more predictable compute pricing, given the fixed instance types. It spins up a standalone virtual machine and executes a Nextflow pipeline or Studio session with a local executor on the virtual machine. At the end of the execution, the instance is terminated. ## Limitations - The Nextflow pipeline will run entirely on a single virtual machine. If the instance does not have sufficient resources, the pipeline execution will fail. For this reason, the number of tasks Nextflow can execute in parallel is limited by the number of cores of the instance type selected. If you need more computing resources, you must create a new compute environment with a larger instance type. This makes the compute environment less suited for larger, more complex pipelines. - There is a considerable delay before streaming logs can be queried. This means that if your pipeline completes in under a minute, you might not see streaming logs during the execution. ## Created resources Seqera will create the following resources in Azure when creating the compute environment: - One Azure resource group: The container for all other created resources. - One Azure managed identity: The Entra identity connected to the Virtual Machine, enabling Nextflow to authenticate to Azure services. - One Azure role: The role attached to the managed identity, which grants the necessary permissions. - One log analytics workspace: Used to collect and query execution logs. - One data collection rule: To route execution logs to the appropriate Log Analytics table. - One data collection endpoint: The endpoint that receives logs, tied to the data collection rule. - One virtual network: The network in which virtual machines are launched. When virtual machines are launched, other resources are provisioned for each machine and tied to the machine lifecycle: - One network interface - One OS disk While the workflow is running, logs are streamed to the `Nextflow_log_CL` table in the Log Analytics workspace for the compute environment. You can query logs for your specific workflow ID with this expression: ``` Nextflow_log_CL | where workflowId == "" ``` The table retains logs for 7 days. Nextflow uploads log files to Azure Storage for long-term storage. ## Requirements ### Platform credentials To create and launch pipelines or Studio sessions with Azure Cloud compute environments, you must attach Seqera credentials with an Entra client ID/client secret pair. These credentials must also include your Azure subscription ID and Storage account configuration. See [Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) and [Add and manage application credentials in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret) for more information. ### Required permissions For granular control over the permissions granted to Seqera, use [Azure custom roles](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles) and [assign](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal) them to the service principal. The full role JSON definition is: ```json { "properties": { "roleName": "seqera-azure-cloud", "description": "Role assumed by Seqera Platform to create Azure Cloud compute environments", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Compute/virtualMachines/read", "Microsoft.Compute/virtualMachines/write", "Microsoft.Compute/virtualMachines/delete", "Microsoft.Compute/virtualMachines/deallocate/action", "Microsoft.Compute/virtualMachines/attachDetachDataDisks/action", "Microsoft.Resources/subscriptions/resourceGroups/write", "Microsoft.Resources/subscriptions/resourceGroups/read", "Microsoft.Resources/subscriptions/resourceGroups/delete", "Microsoft.Network/virtualNetworks/read", "Microsoft.Network/virtualNetworks/write", "Microsoft.Network/virtualNetworks/delete", "Microsoft.Network/virtualNetworks/subnets/read", "Microsoft.Network/virtualNetworks/subnets/write", "Microsoft.Network/virtualNetworks/subnets/delete", "Microsoft.Network/virtualNetworks/subnets/join/action", "Microsoft.Network/networkInterfaces/delete", "Microsoft.Network/networkInterfaces/write", "Microsoft.Network/networkInterfaces/read", "Microsoft.Network/networkInterfaces/join/action", "Microsoft.ManagedIdentity/userAssignedIdentities/read", "Microsoft.ManagedIdentity/userAssignedIdentities/write", "Microsoft.ManagedIdentity/userAssignedIdentities/delete", "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action", "Microsoft.Authorization/roleAssignments/read", "Microsoft.Authorization/roleAssignments/write", "Microsoft.Authorization/roleAssignments/delete", "Microsoft.Authorization/roleDefinitions/read", "Microsoft.Authorization/roleDefinitions/write", "Microsoft.Authorization/roleDefinitions/delete", "Microsoft.Insights/DataCollectionRules/Read", "Microsoft.Insights/DataCollectionRules/Write", "Microsoft.Insights/DataCollectionRules/Delete", "Microsoft.Insights/DataCollectionEndpoints/Write", "Microsoft.Insights/DataCollectionEndpoints/Delete", "Microsoft.OperationalInsights/workspaces/write", "Microsoft.OperationalInsights/workspaces/read", "Microsoft.OperationalInsights/workspaces/delete", "Microsoft.OperationalInsights/workspaces/sharedkeys/action", "Microsoft.OperationalInsights/workspaces/tables/read", "Microsoft.OperationalInsights/workspaces/tables/write", "Microsoft.OperationalInsights/workspaces/tables/delete", "Microsoft.OperationalInsights/workspaces/query/read", "Microsoft.OperationalInsights/workspaces/query/Tables.Custom/read", "Microsoft.Storage/storageAccounts/blobServices/containers/read", "Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action" ], "notActions": [], "dataActions": [ "Microsoft.Insights/Telemetry/Write", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/read", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/write", "Microsoft.OperationalInsights/workspaces/tables/data/read" ], "notDataActions": [] } ] } } ``` See [Start from JSON](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles-portal#start-from-json) to create this custom role in the Azure Portal. This role definition can be applied as-is for convenience, or it can be broken down into smaller roles. The purpose for each permission is outlined in the following sections. #### Compute environment creation The following permissions are required to provision resources in the Azure account when first creating the compute environment: ```json { "properties": { "roleName": "seqera-azure-cloud-create", "description": "Role assumed by Seqera Platform to create Azure Cloud compute environments", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Resources/subscriptions/resourceGroups/read", "Microsoft.Resources/subscriptions/resourceGroups/write", "Microsoft.Storage/storageAccounts/blobServices/containers/read", "Microsoft.Network/virtualNetworks/read", "Microsoft.Network/virtualNetworks/write", "Microsoft.Network/virtualNetworks/subnets/read", "Microsoft.Network/virtualNetworks/subnets/write", "Microsoft.ManagedIdentity/userAssignedIdentities/read", "Microsoft.ManagedIdentity/userAssignedIdentities/write", "Microsoft.Authorization/roleAssignments/read", "Microsoft.Authorization/roleAssignments/write", "Microsoft.Authorization/roleDefinitions/read", "Microsoft.Authorization/roleDefinitions/write", "Microsoft.Insights/DataCollectionRules/Read", "Microsoft.Insights/DataCollectionRules/Write", "Microsoft.Insights/DataCollectionEndpoints/Write", "Microsoft.OperationalInsights/workspaces/read", "Microsoft.OperationalInsights/workspaces/write", "Microsoft.OperationalInsights/workspaces/tables/write" ], "notActions": [], "dataActions": [], "notDataActions": [] } ] } } ``` #### Pipeline and Studio launch The following permissions are required to launch pipelines and Studios: ```json { "properties": { "roleName": "seqera-azure-cloud-launch", "description": "Role assumed by Seqera Platform to launch Studios and pipelines on Azure Cloud compute environments", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Compute/virtualMachines/read", "Microsoft.Compute/virtualMachines/write", "Microsoft.Compute/virtualMachines/delete", "Microsoft.Compute/virtualMachines/deallocate/action", "Microsoft.Compute/virtualMachines/attachDetachDataDisks/action", "Microsoft.Network/networkInterfaces/read", "Microsoft.Network/networkInterfaces/write", "Microsoft.Network/networkInterfaces/join/action", "Microsoft.Network/virtualNetworks/subnets/join/action", "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action", "Microsoft.Insights/DataCollectionRules/Write", "Microsoft.Insights/DataCollectionEndpoints/Write" ], "notActions": [], "dataActions": [ "Microsoft.Insights/Telemetry/Write" ], "notDataActions": [] } ] } } ``` #### Live stream log fetching The following permissions are required to fetch logs for the pipeline execution while the task is running: ``` json { "properties": { "roleName": "seqera-azure-cloud-logs", "description": "Role to be assumed by Seqera Platform to read live-streamed logs for Azure Cloud compute environments", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.OperationalInsights/workspaces/query/read", "Microsoft.OperationalInsights/workspaces/query/Tables.Custom/read" ], "notActions": [], "dataActions": [ "Microsoft.OperationalInsights/workspaces/tables/data/read" ], "notDataActions": [] } ] } } ``` #### Data-links The following permissions are required to work with [Data Explorer](../data/data-explorer) data-links on Azure: ```json { "properties": { "roleName": "seqera-azure-cloud-data-links", "description": "Role assumed by Seqera Platform to access data-links in Azure Cloud compute environments", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Storage/storageAccounts/blobServices/containers/read", "Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action" ], "notActions": [], "dataActions": [ "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/read", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/write" ], "notDataActions": [] } ] } } ``` #### Compute environment termination and resource disposal The following permissions are required to delete the resources created for the compute environment: ```json { "properties": { "roleName": "seqera-azure-cloud-dispose", "description": "Role assumed by Seqera Platform to delete Azure Cloud compute environment resources", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Resources/subscriptions/resourceGroups/delete", "Microsoft.Network/virtualNetworks/delete", "Microsoft.Network/virtualNetworks/subnets/delete", "Microsoft.Network/networkInterfaces/delete", "Microsoft.ManagedIdentity/userAssignedIdentities/delete", "Microsoft.Authorization/roleAssignments/delete", "Microsoft.Authorization/roleDefinitions/delete", "Microsoft.Insights/DataCollectionRules/Delete", "Microsoft.Insights/DataCollectionEndpoints/Delete", "Microsoft.OperationalInsights/workspaces/delete", "Microsoft.OperationalInsights/workspaces/tables/delete" ], "notActions": [], "dataActions": [], "notDataActions": [] } ] } } ``` ## Add Azure Cloud credentials ### Create a custom role in Microsoft Entra First, you must create a custom role with the permissions required for Seqera to manage Azure resources. 1. Save the relevant permissions from the preceding sections to a local JSON file. Replace `` in the `assignableScopes` field of each permission with your Azure subscription ID. 1. In the Azure Portal, go to **Subscriptions** and select your subscription. 1. To create a custom role, select **Access control (IAM)**, then **Add** in the **Create a custom role** section. 1. Provide the following details: - **Custom role name**: e.g., `seqera-azure-cloud` - **Description**: e.g., `Role for Seqera Platform to manage Azure Cloud compute environments` - **Baseline permissions**: Select **Start from JSON** - **File**: Select the local JSON file you saved earlier. 1. Select **Next** and review the permissions to ensure all have been included correctly. 1. Select **Next** and confirm that the assignable scope is your subscription ID. 1. Select **Next**. If you found errors in the previous step, you can edit the JSON file here. 1. Select **Next** and then **Create** to save the role. ### Register an application in Microsoft Entra ID Create an application for Seqera to use for authentication: 1. In the Azure Portal, go to **App registrations** and select **New registration**. 1. Give the app a descriptive name, such as `SeqeraPlatformApp`. 1. Select `Single tenant` for the supported account types. 1. Create a client secret for the application. Seqera will use this value to authenticate to Azure, so keep it secret and store it securely. 1. Under **Certificates & secrets**, select **New client secret** and give it a description such as `SeqeraPlatformSecret`. Set the expiration to a duration that matches your security policy. Select **Add**. After registration, you'll be taken to the application overview page. Copy and save the following values: - **Application (client) ID**: This is your Client ID - **Directory (tenant) ID**: This is your Tenant ID ### Assign the custom role to the service principal Grant the service principal the necessary permissions by assigning the custom role. 1. In the Azure Portal, navigate to **Subscriptions** and select your subscription. Then select **Access control (IAM)** and **Add role assignment** in the **Grant access to this resource** section. 1. Select the **Privileged administrator roles** tab and select the role you created earlier, then select **Next**. 1. Choose **Select members** and search for the application name (`SeqeraPlatformApp`). Then choose **Select**, then **Next**. 1. Select **Review + assign**, **Review**, and then **Assign**. 1. Under **What user can do**, select **Allow user to assign all roles except privileged administrator roles Owner, UAA, RBAC (Recommended)**, then select **Next**. 1. Check the final details and select **Review + assign**. ### Configure Seqera Platform credentials Add the service principal credentials to Seqera: 1. Sign in to your Seqera workspace and navigate to the **Credentials** tab. 1. Select **Add credentials**, select **Azure** as the provider, and select the **Cloud** tab for Microsoft Entra ID authentication. 1. Enter the details of the credentials you saved earlier: - **Name**: Provide a descriptive name, such as `AzureCloudCredentials` - **Subscription ID**: Your Azure subscription ID - **Tenant ID**: Your Directory (tenant) ID from the [Register an application in Microsoft Entra ID](#register-an-application-in-microsoft-entra-id) instructions - **Client ID**: Your Application (client) ID from the [Register an application in Microsoft Entra ID](#register-an-application-in-microsoft-entra-id) instructions - **Client secret**: Your client secret value from the [Register an application in Microsoft Entra ID](#register-an-application-in-microsoft-entra-id) instructions - **Blob Storage account name**: Your Azure Storage account name 1. Review the details, then select **Add** to save the credentials. ### Create a compute environment Create a compute environment in Seqera using the credentials: 1. In your Seqera workspace, navigate to the **Compute Environments** tab and select **Add Compute Environment**. 1. Select **Azure Cloud** as the target platform. 1. From the **Credentials** drop-down, select the credentials you created previously. 1. Enter a name for the compute environment. 1. Enter or select a **Location** for the compute environment. 1. Select the **Work directory** as the Azure blob container you plan to use as the Nextflow working directory. The container must be in the same **Location** as selected in the previous step. 1. (Optional) Under **Advanced options**, specify an **Instance Type**. If left blank, the default virtual machine used is a `Standard_D2ds_v4`. 1. Select **Create** to save the compute environment. ## Advanced options - (Optional) **Subscription ID**: The ID of the subscription where resources must be deployed. If not specified, the subscription ID of the credentials is used. - **Instance Type**: The virtual machine type used by the compute environment. Choosing the instance type will directly allocate the CPU and memory available for computation. See [virtual machine sizes](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/overview) for a comprehensive list of instance types and their resource limitations. - **Virtual network**: An existing Azure virtual network (VNet) in the configured location. The drop-down is populated with VNets discovered in your Azure account for the selected location. When specified, Platform uses this network for all VMs launched in this compute environment and skips network provisioning. Leave blank to let Platform provision a dedicated VNet automatically. :::note The VNet must exist in the same location as the compute environment. Specifying a VNet that does not exist in the location, or a subnet that does not belong to the selected VNet, causes compute environment creation to fail. ::: - **Subnets**: One or more subnet addresses within the selected VNet. VMs are placed in the first listed subnet at launch time. Leave blank to use the first available subnet on the VNet. This field has no effect when no VNet is specified. Any [network security groups (NSGs)](https://learn.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview) attached to the selected subnet are applied to VMs launched in this compute environment. --- ## Amazon EKS [Amazon EKS](https://aws.amazon.com/eks/) provides managed Kubernetes clusters that enable the execution of containerized workloads at scale. Seqera Platform offers native support for Amazon EKS clusters as Compute Environments for Nextflow pipelines. ## Requirements - Seqera Platform needs an IAM User to obtain details about the EKS cluster, and to fetch log files from the S3 bucket, if one is used as work directory. This user must have the permissions detailed in the [Required Platform IAM permissions](#required-platform-iam-permissions) section. Optionally, permissions can instead be granted to an IAM role that the IAM user can assume when accessing AWS resources. - To use Fusion (recommended) to access data hosted on S3, including writing files to the Nextflow work directory, you need an IAM role that allows the EKS Service Account that Seqera pods use to interact with AWS resources. Refer to section [Configure EKS Service Account IAM role for Fusion v2](#configure-eks-service-account-iam-role-for-fusion-v2) for details. Create a separate IAM role from the optional one assumed by the IAM user to separate the permissions needed by the EKS Service Account from those needed by the IAM user. If you plan to use legacy storage instead of Fusion, you can skip this step. :::tip Seqera Platform assumes an EKS cluster already exists. Follow the [cluster preparation](./k8s) instructions to create the resources required by Seqera. Some administrative privileges are also needed to allow the IAM User to access the cluster, as detailed in the [EKS access](#allow-an-iam-user-or-role-access-to-eks) section. ::: Once you meet all the prerequisites, configure an [Amazon EKS Compute Environment](#amazon-eks-compute-environment) in Seqera. ## Required Platform IAM permissions Seqera Platform requires an IAM user with specific permissions to launch pipelines, explore buckets with Data Explorer, and run Studio sessions on the AWS EKS compute environment. Some permissions are mandatory for the compute environment to function correctly, while others are optional and enable features like populating drop-down lists in the Platform UI. Attach permissions directly to an [IAM user](#iam-user-creation), or to an [IAM role](#iam-role-creation-optional) that the IAM user can assume. A permissive and broad policy with all the required permissions is provided here for a quick start. However, we recommend following the principle of least privilege and only granting the necessary permissions for your use case, as shown in the following sections.
Full permissive policy (for reference) ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "EKSClusterAccessCanBeRestricted", "Effect": "Allow", "Action": [ "eks:DescribeCluster", "eks:ListClusters" ], "Resource": "*" }, { "Sid": "OptionalS3PlatformDataAccessCanBeRestricted", "Effect": "Allow", "Action": [ "s3:Get*", "s3:List*", "s3:PutObject", "s3:PutObjectTagging", "s3:DeleteObject" ], "Resource": "*" } ] } ```
### EKS cluster access Seqera needs permissions to list EKS clusters in the selected region and to describe the selected cluster to retrieve its connection details. The `eks:ListClusters` action cannot be restricted to specific resources, but the `eks:DescribeCluster` action can be restricted to the specific cluster used as compute environment. ```json { "Sid": "EKSClusterListing", "Effect": "Allow", "Action": [ "eks:ListClusters" ], "Resource": "*" }, { "Sid": "EKSClusterDescription", "Effect": "Allow", "Action": [ "eks:DescribeCluster" ], "Resource": "arn:aws:eks:::cluster/" } ``` No other permissions are required for the IAM user to launch pipelines on the EKS compute environment, as the Service Account created in the [cluster preparation](./k8s) phase performs the actual management of pods and resources, which the IAM user can access via EKS authentication, detailed [in the EKS access section below](#allow-an-iam-user-or-role-access-to-eks). ### S3 access (optional) Seqera automatically attempts to fetch a list of S3 buckets available in the AWS account connected to Platform, to provide them in a drop-down to be used as Nextflow working directory, and make the compute environment creation smoother. This feature is optional, and users can type the bucket name manually when setting up a compute environment. To allow Seqera to fetch the list of buckets in the account, the `s3:ListAllMyBuckets` action can be added, and it must have the `Resource` field set to `*`. The `s3:ListAllMyBuckets` action also allows Data Explorer to auto-discover the data repositories accessible to your workspace credentials. Seqera offers several products to manipulate data on AWS S3 buckets, such as [Studios](../studios/overview) and [Data Explorer](../data/data-explorer); if these features are not needed the related permissions can be omitted. The IAM policy can be scoped down to only allow limited read/write permissions in certain S3 buckets used by Studios/Data Explorer. For each bucket you want to browse, upload to, or download from with Data Explorer, grant `s3:GetObject` and `s3:PutObject` on the bucket objects, and `s3:ListBucket`, `s3:GetBucketLocation`, `s3:GetBucketPolicy`, and `s3:GetBucketAcl` on the bucket itself. In addition, the policy must include permission to check the region and list the content of the S3 bucket used as Nextflow work directory. We also recommend granting the `s3:GetObject` permission on the work directory path to fetch Nextflow log files. :::note If you opted to create a separate S3 bucket only for Nextflow work directories, the IAM user or the Role it assumes only need read access to it. The IAM role used by the EKS Service Account (detailed in the [separate section](#configure-eks-service-account-iam-role-for-fusion-v2)) must have full read/write access to the work directory bucket to allow Fusion to operate correctly. ::: ```json { "Sid": "S3CheckBucketWorkDirectory", "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::example-bucket-used-as-work-directory" ] }, { "Sid": "S3ReadOnlyNextflowLogFiles", "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::example-bucket-used-as-work-directory/path/to/work/directory/*" ] }, { "Sid": "S3ReadWriteBucketsForStudiosDataExplorer", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectTagging", "s3:GetBucketLocation", "s3:GetBucketPolicy", "s3:GetBucketAcl", "s3:ListBucket", "s3:PutObject", "s3:PutObjectTagging", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::example-bucket-read-write-studios", "arn:aws:s3:::example-bucket-read-write-studios/*", "arn:aws:s3:::example-bucket-read-write-data-explorer", "arn:aws:s3:::example-bucket-read-write-data-explorer/*" ] } ``` :::note `s3:GetBucketLocation` allows Data Explorer to resolve each bucket's region. `s3:GetBucketPolicy` and `s3:GetBucketAcl` allow it to inspect each bucket's access configuration when it lists and connects to data repositories. If you prefer not to enumerate individual actions, the `s3:Get*` and `s3:List*` wildcards shown in the full permissive policy also cover these actions. ::: ## Create the IAM policy The policy above must be created in the AWS account where the EKS and S3 resources are located. 1. Open the [AWS IAM console](https://console.aws.amazon.com/iam). 1. From the left navigation menu, select **Policies** under **Access management**. 1. Select **Create policy**. 1. On the **Policy editor** section, select the **JSON** tab. 1. Following the instructions detailed in the [IAM permissions breakdown section](#required-platform-iam-permissions) replace the default text in the policy editor area under the **JSON** tab with a policy adapted to your use case, then select **Next**. 1. Enter a name and description for the policy on the **Review and create** page, then select **Create policy**. ## IAM user creation Seqera requires an Identity and Access Management (IAM) User to describe EKS clusters and S3 buckets in your AWS account. We recommend creating a separate IAM policy rather an IAM User inline policy, as the latter only allows 2048 characters, which may not be sufficient for all the required permissions. In certain scenarios, for example when multiple users need to access the same AWS account, an IAM role with the required permissions can be created instead, and the IAM user allowed to assume the role, as detailed in the [IAM role creation (optional)](#iam-role-creation-optional) section. ### Create an IAM user 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Users** in the left navigation menu, then select **Create User** at the top right of the page. 1. Enter a name for your user (e.g., _seqera_) and select **Next**. 1. Under **Permission options**, select **Attach policies directly**, then search for and select the policy created above, and select **Next**. * If you instead prefer to make the IAM user assume a role to manage AWS resources (see the [IAM role creation (optional)](#iam-role-creation-optional) section), create a policy with the following content (edit the AWS principal with the ARN of the role created) and attach it to the IAM user: ```json { "Sid": "AssumeRole", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam:::role/", "Condition": { "StringEquals": { "sts:ExternalId": "" } } } ``` 1. On the last page, review the user details and select **Create user**. The user has now been created. For more details see the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). ### Obtain IAM user credentials To get the credentials needed to connect Seqera to your AWS account, follow these steps: 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Users** in the left navigation menu, then select the newly created user from the users table. 1. Select the **Security credentials** tab, then select **Create access key** under the **Access keys** section. 1. In the **Use case** dialog that appears, select **Command line interface (CLI)**, then tick the confirmation checkbox at the bottom to acknowledge that you want to proceed creating an access key, and select **Next**. 1. Optionally provide a description for the access key, like the reason for creating it, then select **Create access key**. 1. Save the **Access key** and **Secret access key** in a secure location as they are needed when configuring credentials in Seqera. ## IAM role creation (optional) Rather than attaching permissions directly to the IAM user, you can create an IAM role with the required permissions and allow the IAM user to assume that role when accessing AWS resources. This is useful when multiple IAM users are used to access the same AWS account: this way the actual permissions to operate on the resources are only granted to a single centralized role. 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Roles** in the left navigation menu, then select **Create role** at the top right of the page. 1. Select **Custom trust policy** as the type of trusted entity, provide the following policy and edit the AWS principal with the ARN of the IAM user created in the [IAM user creation](#iam-user-creation) section, then select **Next**. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam:::user/" ] }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } }, { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam:::user/" ] }, "Action": "sts:TagSession" } ] } ``` 1. On the **Permissions** page, search for and select the policy created in the [IAM user creation](#iam-user-creation) section, then select **Next**. 1. Give the role a name and optionally a description, review the details of the role, optionally provide tags to help you identify the role, then select **Create role**. Multiple users can be specified in the trust policy by adding more ARNs to the `Principal` section. :::note Seqera Platform generates the `External ID` value during AWS credential creation. For role-based credentials, use this exact value in your IAM trust policy (`sts:ExternalId`). ::: ### Role-based trust policy example (Seqera Enterprise) For role-based AWS credentials in Enterprise, use the AWS IAM role configured in your deployment (``) in your trust policy and enforce the `External ID` generated during credential creation: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } }, { "Effect": "Allow", "Principal": { "AWS": "" }, "Action": "sts:TagSession" } ] } ``` :::info In Seqera Enterprise, a jump role is optional. If you configure one, use your own jump role ARN as the trusted principal in the trust policy. The **Assume role** value in the credential form is the customer IAM role ARN in your AWS account. It is separate from any optional jump role configuration. ::: :::info To use role-based access with no External ID, set `TOWER_ALLOW_INSTANCE_CREDENTIALS=true` in your deployment [configuration](../enterprise/configuration/overview#compute-environments). Then create AWS credentials using an IAM role ARN only (no access key, secret key, or External ID), and remove the entire `Condition` block for `sts:ExternalId` from your trust policy. ::: ## AWS credential options AWS credentials can be configured in two ways: - **Key-based credentials**: Access key and secret key with direct IAM permissions. If you provide a role ARN in **Assume role**, the **Generate External ID** switch is displayed and External ID generation is optional. - **Role-based credentials (recommended)**: Use role assumption only (no static keys). Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. External ID is generated automatically when you save. Use the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. This field is available for both key-based and role-based credentials. It is optional for key-based credentials and required for role-based credentials. Existing credentials created before March 2026 continue to work without changes. `TOWER_ALLOW_INSTANCE_CREDENTIALS=true` configuration behavior remains unchanged. ## Configure EKS Service Account IAM role for Fusion v2 To use [Fusion v2](https://docs.seqera.io/fusion) in your Amazon EKS compute environment, an AWS S3 bucket must be used as work directory and both the head and compute Service Accounts (if separate) must have access to the S3 bucket specified as the work directory. If you do not plan to use Fusion in favor of legacy storage, you can skip this section. 1. Create an IAM role with the following permissions: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::" ] }, { "Action": [ "s3:GetObject", "s3:PutObject", "s3:PutObjectTagging", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::/*" ], "Effect": "Allow" } ] } ``` Replace `` with the bucket name used as work directory. 1. The IAM role must also have a trust relationship with the Kubernetes service account (or accounts) that Seqera uses to manage the EKS cluster, which is `tower-launcher-sa` in the default configuration.: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "oidc.eks..amazonaws.com/id/:aud": "sts.amazonaws.com", "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount::" } } } ] } ``` Replace ``, ``, ``, ``, `` with the corresponding values. 1. Annotate the Kubernetes Service Account with the IAM role: ```shell kubectl annotate serviceaccount --namespace eks.amazonaws.com/role-arn=arn:aws:iam:::role/ ``` Replace `` (by default `tower-launcher-sa`, as created in the [cluster preparation guide](./k8s)), ``, and `` with the corresponding values previously defined. This will allow pods using that service account to assume the IAM role and access the S3 bucket specified as work directory. See the [AWS documentation](https://docs.aws.amazon.com/eks/latest/userguide/associate-service-account-role.html) for further details. ## Allow an IAM User or Role access to EKS Configure the EKS cluster to allow the IAM user (or the IAM role it assumes) to access the cluster and manage pods. 1. Retrieve from the [AWS IAM console](https://console.aws.amazon.com/iam) the ARN of the [IAM User](#iam-user-creation) or [IAM Role](#iam-role-creation-optional) previously created. :::note The AWS credentials for the IAM user will be used in the Seqera compute environment configuration. ::: 1. Modify the EKS aws-auth ConfigMap to allow the IAM User to access the cluster and manage pods. This step may require cluster administrator privileges: ```bash kubectl edit configmap -n kube-system aws-auth ``` 1. In the editor that opens, edit the `mapUsers` section to add the following entry, replacing `` with the user ARN retrieved from the AWS IAM console: ```yaml mapUsers: | - userarn: username: tower-launcher-user groups: - tower-launcher-role ``` Alternatively, an IAM role can be allowed to authenticate to the cluster: in this case, the role ARN must be specified in the **Assume role** field when configuring the Seqera compute environment (step 9 in the [Amazon EKS compute environment](#amazon-eks-compute-environment) section), the role must have a trust relationship with the Seqera IAM user, and the role `` must be added to the `mapRoles` section of the EKS auth configuration instead: ```yaml mapRoles: | - rolearn: username: tower-launcher-role groups: - tower-launcher-role ``` See the [AWS documentation](https://docs.aws.amazon.com/eks/latest/userguide/auth-configmap.html) for more details on modifying the aws-auth ConfigMap of an EKS cluster. ## Amazon EKS compute environment :::caution Your compute environment uses resources that you may be charged for in your AWS account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: Once all prerequisites are met, create a Seqera EKS compute environment: 1. Select **Compute environments** from the navigation menu of the Seqera Workspace where you want to setup the CE. 1. Enter a descriptive name for this environment, e.g., `Amazon EKS (eu-west-1)`. 1. Select **Amazon EKS** as the target platform. 1. Under **Storage**, select either **Fusion storage** (recommended) or **Legacy storage**. The [Fusion v2](https://docs.seqera.io/fusion) virtual distributed file system allows access to your AWS S3-hosted data (`s3://` URLs). This eliminates the need to configure a shared file system in your Kubernetes cluster. See [Configure EKS Service Account IAM role for Fusion v2](#configure-eks-service-account-iam-role-for-fusion-v2) below. 1. From the **Credentials** drop-down, select existing AWS credentials, or select **+** to add new credentials. If you're using existing credentials, skip to step 9. The user must have the IAM permissions required to describe and list EKS clusters, per Service Account role requirements. :::note You can create multiple credentials in your Seqera environment. See [Credentials](../credentials/overview). ::: 1. Enter a name, e.g., `EKS Credentials`. 1. Under **AWS credential mode**, select **Keys** or **Role**. 1. For **Keys** mode: - Add the **Access key** and **Secret key** obtained from the AWS IAM console. - Optionally paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - If you paste a role ARN in **Assume role**, the **Generate External ID** switch is displayed. Generating an External ID is optional in **Keys** mode. - If **Generate External ID** is selected, an External ID is automatically generated and shown after you save the credential. 1. For **Role** mode: - Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - External ID is generated automatically when you save the credential. :::note When using AWS keys without an assumed role, the associated AWS user must have been granted permissions to operate on the cloud resources directly. When an assumed role is provided, the IAM user keys are only used to retrieve temporary credentials impersonating the role specified: this could be useful when e.g. multiple IAM users are used to access the same AWS account, and the actual permissions to operate on the resources are only granted to the role. ::: 1. Select a **Region**, e.g., `eu-west-1 - Europe (Ireland)`. If using Fusion v2, this region must match the location of the S3 bucket you plan to use as work directory. 1. Select a **Cluster name** from the list of available EKS clusters in the selected region. 1. Specify the **Namespace** created in the [cluster preparation](./k8s) instructions, `tower-nf` by default. 1. Specify the **Head service account** created in the [cluster preparation](./k8s) instructions, `tower-launcher-sa` by default. :::note If you enable Fusion v2 (**Fusion storage** in step 4 above), the head service account must have access to the S3 storage bucket specified as your work directory. In the [Advanced options](#amazon-eks-advanced-options) below, a service account for compute jobs need to also be specified to allow pods to interact with AWS. ::: 1. Define the **Work directory** used as the working directory by Nextflow pipelines. If using Fusion v2, this must be an S3 bucket (e.g., `s3://my-bucket/work-dir`). If using Legacy storage, this must the name of a Persistent Volume Claim (PVC) created in the [cluster preparation](./k8s) instructions, e.g., `tower-scratch`. 1. Apply [**Resource labels**](../resource-labels/overview) to the cloud resources produced by this compute environment. Workspace default resource labels are prefilled. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. Here's an example configuration to require the compute pods to be scheduled on specific nodes: ```groovy k8s { pod = [ [ nodeSelector: 'myNodeSelector=my-nodes-for-k8s-as-compute' ], [ toleration: [ key: 'myNodeSelector', operator: 'Equal', value: 'my-nodes-for-k8s-as-compute', effect: 'NoSchedule' ] ] ] } ``` :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options described in the next section, as needed. ### Amazon EKS advanced options Amazon EKS compute environments include advanced options for storage and work directory paths, resource allocation, and pod customization. - The **Storage mount path** is the file system path where Seqera mounts the Storage claim (default: `/scratch`). - The **Work directory** is the file system path that Nextflow pipelines use as a working directory. This must be the storage mount path (default) or a subdirectory of it. - The **Compute service account** is the service account that Nextflow uses to submit tasks (default: the `default` account in the given namespace). :::note If you enable Fusion v2 (**Fusion storage** in step 4 above), the compute service account must have access to the S3 storage bucket specified as your work directory. This can be the same Service Account used by the Head jobs (`tower-launcher-sa`, created in the [cluster preparation](./k8s) guide), or a separate Service Account with more granular permissions. ::: - The **Pod cleanup policy** determines when to delete terminated pods. - Use **Custom head pod specs** to provide custom options for the Nextflow workflow pod (e.g., `nodeSelector`, `affinity`, etc). For example: ```yaml spec: nodeSelector: disktype: ssd ``` - Use **Head job CPUs** and **Head job memory** to specify resource requirements of the Nextflow workflow pods. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your Amazon EKS compute environment. ::: --- ## Google Kubernetes Engine [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) is a managed Kubernetes cluster that allows the execution of containerized workloads in Google Cloud at scale. Seqera Platform offers native support for GKE clusters to streamline the deployment of Nextflow pipelines. ## Requirements See [here](../compute-envs/google-cloud-batch#configure-google-cloud) for instructions to set up your Google Cloud account and other services (such as Cloud storage). You must have a GKE cluster up and running. Follow the [cluster preparation](../compute-envs/k8s#cluster-preparation) instructions to create the resources required by Seqera. In addition to the generic Kubernetes instructions, you must make a number of modifications specific to GKE. ### Service account role You must grant cluster access to the service account used by the Seqera compute environment. To do this, update the [service account _RoleBinding_](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control#rolebinding): ```yaml cat << EOF | kubectl apply -f - --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: tower-launcher-userbind subjects: - kind: User name: apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: tower-launcher-role apiGroup: rbac.authorization.k8s.io --- EOF ``` Replace `` with the corresponding service account, e.g., `test-account@test-project-123456.google.com.iam.gserviceaccount.com`. See [Role-based access control](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control) for more information. ## Seqera compute environment :::caution Your Seqera compute environment uses resources that you may be charged for in your Google Cloud account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: After you've prepared your Kubernetes cluster and granted cluster access to your service account, create a Seqera GKE compute environment: 1. In a Seqera workspace, select **Compute environments > New environment**. 1. Enter a descriptive name for this environment, e.g., _Google Kubernetes Engine (europe-west1)_. 1. From the **Provider** drop-down, select **Google Kubernetes Engine**. 1. Under **Storage**, select either **Fusion storage** (recommended) or **Legacy storage**. The [Fusion v2](https://docs.seqera.io/fusion) virtual distributed file system allows access to your Google Cloud-hosted data (`gs://` URLs). This eliminates the need to configure a shared file system in your Kubernetes cluster. See [Fusion v2](#fusion-v2) below. 1. From the **Credentials** drop-down, select existing GKE credentials, or select **+** to add new credentials. If you choose to use existing credentials, skip to step 8. 1. Enter a name for the credentials, e.g., _GKE Credentials_. 1. Enter the **Service account key** for your Google service account. :::tip You can create multiple credentials in your Seqera environment. See [Credentials](../credentials/overview). ::: 1. Select the **Location** of your GKE cluster. :::caution GKE clusters can be either regional or zonal. For example, `us-west1` identifies the United States West-Coast _region_, which has three _zones_: `us-west1-a`, `us-west1-b`, and `us-west1-c`. Seqera Platform's auto-completion only shows regions. You should manually edit this field if you're using a zonal GKE cluster. ::: 1. Select or enter the **Cluster name** of your GKE cluster. 1. Specify the **Namespace** created in the [cluster preparation](../compute-envs/k8s#cluster-preparation) instructions. This is _tower-nf_ by default. 1. Specify the **Head service account** created in the [cluster preparation](../compute-envs/k8s#cluster-preparation) instructions. This is _tower-launcher-sa_ by default. :::note If you enable Fusion v2 (**Fusion storage** in step 4 above), the head service account must have access to the Google Cloud storage bucket specified as your work directory. ::: 1. Specify the **Storage claim** created in the [cluster preparation](../compute-envs/k8s#cluster-preparation) instructions. This serves as a scratch filesystem for Nextflow pipelines. The storage claim is called _tower-scratch_ in the provided examples. :::note The **Storage claim** isn't needed when Fusion v2 is enabled. ::: 1. Apply [**Resource labels**](../resource-labels/overview) to the cloud resources consumed by this compute environment. Workspace default resource labels are prefilled. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options described in the next section, as needed. 1. Select **Create** to finalize the compute environment setup. ### Advanced options Seqera Platform compute environments for GKE include advanced options for storage and work directory paths, resource allocation, and pod customization. - The **Storage mount path** is the file system path where the Storage claim is mounted (default: `/scratch`). - The **Work directory** is the file system path used as a working directory by Nextflow pipelines. It must be the storage mount path (default) or a subdirectory of it. - The **Compute service account** is the service account used by Nextflow to submit tasks (default: the `default` account in the given namespace). - The **Pod cleanup policy** determines when to delete terminated pods. - Use **Custom head pod specs** to provide custom options for the Nextflow workflow pod (`nodeSelector`, `affinity`, etc). For example: ```yaml spec: nodeSelector: disktype: ssd ``` - Use **Custom service pod specs** to provide custom options for the compute environment pod. See above for an example. - Use **Head job CPUs** and **Head job memory** to specify the hardware resources allocated for the Nextflow workflow pod. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your GKE compute environment. ::: ### Fusion v2 To use [Fusion v2](https://docs.seqera.io/fusion) in your Seqera GKE compute environment: 1. Use Seqera Platform version 23.1 or later. 1. Use an S3 bucket as the pipeline work directory. 1. Both the head service and compute service accounts must have access to the Google Cloud storage bucket specified as the work directory.
Configure IAM to use Fusion v2 1. Ensure the **Workload Identity** feature is enabled for the cluster: - **Enable Workload Identity** in the cluster **Security** settings. - **Enable GKE Metadata Server** in the node group **Security** settings. 1. Allow the IAM service account access to your Google storage bucket: ```shell gcloud storage buckets add-iam-policy-binding gs:// --role roles/storage.objectAdmin --member serviceAccount:@.iam.gserviceaccount.com ``` The role must have at least `storage.objects.create`, `storage.objects.get`, and `storage.objects.list` permissions. 1. Allow the Kubernetes service account to impersonate the IAM service account: ```shell gcloud iam service-accounts add-iam-policy-binding @.iam.gserviceaccount.com --role roles/iam.workloadIdentityUser --member "serviceAccount:.svc.id.goog[/]" ``` 1. Annotate the Kubernetes service account with the email address of the IAM service account: ```shell kubectl annotate serviceaccount --namespace iam.gke.io/gcp-service-account=@.iam.gserviceaccount.com ``` See the [GKE documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#authenticating_to) for further details.
--- ## Google Cloud Batch :::note This guide assumes you have an existing Google Cloud account. Sign up for a free account [here](https://cloud.google.com/). Seqera Platform provides integration to Google Cloud via the [Batch API](https://cloud.google.com/batch/docs/reference/rest). ::: The guide is split into two parts: 1. How to configure your Google Cloud account to use the Batch API. 2. How to create a Google Cloud Batch compute environment in Seqera. ## Configure Google Cloud ### Create a project Go to the [Google Project Selector page](https://console.cloud.google.com/projectselector2) and select an existing project, or select **Create project**. Enter a name for your new project, e.g., *tower-nf*. If you are part of an organization, the location defaults to your organization. ### Enable billing See [Enable, disable, or change billing for a project](https://cloud.google.com/billing/docs/how-to/modify-project) to enable billing in your Google Cloud account. ### Enable APIs See [Enable API wizard](https://console.cloud.google.com/flows/enableapi?apiid=batch.googleapis.com%2Ccompute.googleapis.com%2Cstorage-api.googleapis.com) to enable the following APIs for your project: * Batch API * Compute Engine API * Cloud Storage API Select your project from the drop-down and select **Enable**. Alternatively, enable each API manually by selecting your project in the navigation bar and visiting each API page: * [Batch API](https://console.cloud.google.com/marketplace/product/google/batch.googleapis.com) * [Compute Engine API](https://console.cloud.google.com/marketplace/product/google/compute.googleapis.com) * [Cloud Storage API](https://console.cloud.google.com/marketplace/product/google/storage-api.googleapis.com) ### IAM Seqera requires a service account with appropriate permissions to interact with your Google Cloud resources. As an IAM user, you must have access to the service account that submits Batch jobs. :::caution By default, Google Cloud Batch uses the default Compute Engine service account to submit jobs. This service account is granted the Editor (`roles/Editor`) role. While this service account has the necessary permissions needed by Seqera, this role is not recommended for production environments. Control job access using a custom service account with only the permissions necessary for Seqera to execute Batch jobs instead. ::: #### Service account permissions [Create a custom service account](https://cloud.google.com/iam/docs/service-accounts-create#creating) with at least the following permissions: * Batch Agent Reporter (`roles/batch.agentReporter`) on the project * Batch Job Editor (`roles/batch.jobsEditor`) on the project * Logs Writer (`roles/logging.logWriter`) on the project (to let jobs generate logs in Cloud Logging) * Service Account User (`roles/iam.serviceAccountUser`) * Service Usage Consumer (`roles/serviceusage.serviceUsageConsumer`) * Secret Manager Secret Accessor (`roles/secretmanager.secretAccessor`) on the project (required if your pipelines use Seqera secrets; the head job and tasks read secrets from GCP Secret Manager) If your Google Cloud project does not require access restrictions on any of its Cloud Storage buckets, you can grant project Storage Admin (`roles/storage.admin`) permissions to your service account to simplify setup. To grant access only to specific buckets, add the service account as a principal on each bucket individually. See [Cloud Storage bucket](#cloud-storage-bucket) below. #### User permissions Ask your Google Cloud administrator to grant you the following IAM user permissions to interact with your custom service account: * Batch Job Editor (`roles/batch.jobsEditor`) on the project * Service Account User (`roles/iam.serviceAccountUser`) on the job's service account (default: Compute Engine service account) * View Service Accounts (`roles/iam.serviceAccountViewer`) on the project #### Authentication methods Seqera supports two methods for authenticating with Google Cloud: **Service account keys** To authenticate using a service account key, create a [service account JSON key file](https://cloud.google.com/iam/docs/keys-list-get#get-key): 1. In the Google Cloud navigation menu, select **IAM & Admin > Service Accounts**. 2. Select the email address of the service account. :::note The Compute Engine default service account is not recommended for production environments due to its powerful permissions. To use a service account other than the Compute Engine default, specify the service account email address under **Advanced options** on the Seqera compute environment creation form. ::: 3. Select **Keys > Add key > Create new key**. 4. Select **JSON** as the key type. 5. Select **Create**. A JSON file is downloaded to your computer. This file contains the credential needed to configure the compute environment in Seqera. You can manage your key from the **Service Accounts** page. **Workload Identity Federation** Workload Identity Federation (WIF) is the recommended authentication method for production and regulated environments because it eliminates the need for long-lived service account keys. WIF uses short-lived OIDC tokens for authentication, which are generated by Seqera Platform. This requires the following steps in the GCP Console: 1. Create a [Workload Identity Pool and Provider](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) in your Google Cloud project. 2. Set Seqera as an OIDC provider within the pool. Set the Issuer URL to `https://{your-platform-domain}/api`, where `your-platform-domain}` is the hosted URL. The discovery endpoints are at `/api/.well-known/openid-configuration` and `/api/.well-known/jwks.json`. Both must be publicly reachable from GCP STS. 3. Set the Allowed audiences. If left empty, GCP derives a default audience from the provider resource path in the format `//iam.googleapis.com/projects/{PROJECT}/locations/global/workloadIdentityPools/{POOL}/providers/{PROVIDER}`. If you specify a custom value, it must match exactly what you enter in the Token audience field when creating the Google WIF credential in Seqera. 4. Define an attribute mapping and condition. At a minimum set `google.subject=assertion.sub`. This maps the subject claim from Seqera's JWT to GCP's identity space. For more information see [here](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#mappings-and-conditions) 5. Grant `roles/iam.workloadIdentityUser` on the service account created above to the Workload Identity Pool principal. This can be set for all pool identities or for a specific workspace. 6. If you use the same WIF credential for Data Explorer, grant `roles/iam.serviceAccountTokenCreator` on the service account to itself: ```bash gcloud iam service-accounts add-iam-policy-binding SA_EMAIL \ --member="serviceAccount:SA_EMAIL" \ --role="roles/iam.serviceAccountTokenCreator" ``` Replace `SA_EMAIL` with the service account email. Without this role, viewing or downloading file contents in Data Explorer fails with a signing error. Pipeline runs are not affected. WIF requires an OIDC signing key and for Seqera Platform's OIDC provider to be configured. See [Cryptographic options](https://docs.seqera.io/platform-enterprise/enterprise/configuration/overview#cryptographic-options). **Generate the OIDC signing key** Generate a PEM keypair and configure Platform to use it: ```bash openssl genrsa -out private.pem 4096 openssl rsa -in private.pem -outform PEM -pubout -out public.pem cat private.pem public.pem > oidc.pem ``` Set `TOWER_OIDC_PEM_PATH` to the path of the `oidc.pem` file in your Platform deployment. For example, `TOWER_OIDC_PEM_PATH=/path/to/oidc.pem`. If you have not generated and set an RSA keypair as part of your Enterprise deployment, any authentication will fail with the message `WIF credentials require the OIDC provider to be configured (tower.oidc.pem.path)`. After setting up WIF in Google Cloud, you need the following information to create a credential in Seqera: * **Service Account Email**: The email address of the Google Cloud service account that WIF will impersonate. * **Workload Identity Provider**: The full resource path of the Workload Identity Provider (e.g., `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID`). * **Token Audience** (optional): The intended audience for the OIDC token. Configure this if your Workload Identity Provider requires a specific audience value. Ensure this matches what you have configured in the **Allowed Audiences** value in the GCP console. The issuer URL is `${TOWER_SERVER_URL}/api` for all deployments, not just Cloud. In the GCP WIF provider, set the issuer to `https://{your-platform-domain}/api` regardless of whether it's Cloud or Enterprise. The discovery endpoints are at `/api/.well-known/openid-configuration` and `/api/.well-known/jwks.json`, and both must be publicly reachable from GCP STS. :::caution If WIF authentication fails, verify that the Workload Identity Provider path is correctly formatted, the service account has the required permissions, and the Kubernetes service account is properly annotated for your deployment environment. Check your Seqera Platform logs for specific error details. A `400` error typically indicates an invalid provider format, while a `401` error indicates a token exchange failure. ::: ### Cloud Storage bucket Google Cloud Storage is a type of **object storage**. To access files and store the results for your pipelines, create a **Cloud bucket** that your Seqera service account can access. #### Create a Cloud Storage bucket 1. In the hamburger menu (**≡**), select **Cloud Storage**. 2. From the **Buckets** tab, select **Create**. 3. Enter a name for your bucket. You reference this name when you create the compute environment in Seqera. 4. Select **Region** for the **Location type** and select the **Location** for your bucket. Use this location when you create the compute environment in Seqera. :::note The Batch API is available in a limited number of [locations](https://cloud.google.com/batch/docs/locations). These locations are only used to store metadata about the pipeline operations. The storage bucket and compute resources can be in any region. ::: 5. Select **Standard** for the default storage class. 6. To restrict public access to your bucket data, select the **Enforce public access prevention on this bucket** checkbox. 7. Under **Access control**, select **Uniform**. 8. Select any additional object data protection tools, per your organization's data protection requirements. 9. Select **Create**. #### Assign bucket permissions 1. After the bucket is created, you are redirected to the **Bucket details** page. 2. Select **Permissions**, then **Grant access** under **View by principals**. 3. Copy the email address of your service account into **New principals**. 4. Select the **Storage Admin** role, then select **Save**. :::tip You've created a project, enabled the necessary Google APIs, created a bucket, and created credentials for your service account. You now have what you need to set up a new compute environment in Seqera. ::: ### Seqera compute environment :::caution Your Seqera compute environment uses resources that incur charges in your Google Cloud account. See [Cloud costs](https://docs.seqera.io/platform-enterprise/monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: After you create your Google Cloud resources, create a Seqera Platform compute environment: 1. In a workspace, select **Compute Environments > New Environment**. 2. Enter a descriptive name for this environment, e.g., *Google Cloud Batch (europe-north1)*. 3. Select **Google Cloud Batch** as the target platform. #### Credentials 1. From the **Credentials** drop-down, select existing Google credentials or select **+** to add new credentials. If you choose to use existing credentials, skip to the next section. 2. Enter a name for the credentials, e.g., *Google Cloud Credentials*. 3. Select the credential type: - **Google Service Account Key**: Paste the contents of the JSON key file created in the [service account keys](#authentication-methods) section. - **Google WIF**: Enter the **Service Account Email**, **Workload Identity Provider** path, and optionally the **Token Audience** as described in the [Workload Identity Federation](#authentication-methods) section. #### Location and work directory Select the **Location** where you execute your pipelines. See [Location](https://cloud.google.com/compute/docs/regions-zones#available) to learn more. In the **Pipeline work directory** field, enter your storage bucket URL. For example, `gs://my-bucket`. This bucket must be accessible in the location selected in the previous step. :::note When you specify a Cloud Storage bucket as your work directory, this bucket is used for the Nextflow [cloud cache](https://docs.seqera.io/nextflow/cache-and-resume#cache-stores) by default. You can specify an alternative cache location with the **Nextflow config file** field on the pipeline [launch](../launch/launchpad#launch-form) form. ::: #### Seqera features - Select **Enable Wave containers** to facilitate access to private container repositories and provision containers in your pipelines using the Wave containers service. See [Wave containers](https://docs.seqera.io/nextflow/wave) for more information. - Select **Enable Fusion v2** to allow access to your Google Cloud Storage data via the [Fusion v2](https://docs.seqera.io/fusion) virtual distributed file system. This speeds up most data operations. The Fusion v2 file system requires Wave containers to be enabled. See [Fusion file system](../supported_software/fusion/overview) for configuration details. :::note The compute recommendations below are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. ::: 1. Use Seqera Platform version 23.1 or later. 2. Use a Google Cloud Storage bucket as the pipeline work directory. 3. Enable **Wave containers** and **Fusion v2**. 4. Specify suitable virtual machine types and local storage settings, or accept the default machine settings listed below. Use an `n2-highmem-16-lssd` VM or larger for production. :::note To specify virtual machine settings in Platform during compute environment creation, use the **Global Nextflow config** field to apply custom Nextflow process directives to all pipeline runs launched with this compute environment. To specify virtual machine settings per pipeline run in Platform, or as a persistent configuration in your Nextflow pipeline repository, use Nextflow process directives. See [Google Cloud Batch process definition](https://docs.seqera.io/nextflow/google#process-definition) for more information. ::: When Fusion v2 is enabled, Seqera Platform applies the following virtual machine settings: * A 375 GB local NVMe SSD is selected for all compute jobs. * If you do not specify a machine type, Seqera selects a VM from families that support local SSDs. * Any machine types you specify in the Nextflow config must support local SSDs. * Local SSDs are only offered in multiples of 375 GB. You can increment the number of SSDs used per process with the `disk` directive to request multiples of 375 GB. To work with files larger than 100 GB, use at least two SSDs (750 GB or more). * Fusion v2 can also use persistent disks for caching. Override the disk requested by Fusion using the `disk` directive and the `type: pd-standard`. * Use the `machineType` directive to specify a VM instance type, family, or custom machine type in a comma-separated list of patterns. For example, `c2-*`, `n1-standard-1`, `custom-2-4`, `n*`, `m?-standard-*`. :::note Wave containers and Fusion v2 are recommended features for added capability and improved performance, but neither are required to execute workflows in your compute environment. ::: #### GCP resources Enable **Spot** to use Spot instances, which have significantly reduced cost compared to On-Demand instances. :::note From Nextflow version 24.10, the default Spot reclamation retry setting changed to `0` on AWS and Google. By default, no internal retries are attempted on these platforms. Spot reclamations now lead to an immediate failure, exposed to Nextflow in the same way as other generic failures (returning for example, `exit code 1` on AWS). Nextflow treats these failures like any other job failure unless you actively configure a retry strategy. For more information, see [Spot instance failures and retries](../troubleshooting_and_faqs/nextflow#spot-instance-failures-and-retries). Selecting the 'enable Fusion snapshots' option (Google Cloud Batch) changes the default Spot reclamation retry setting to `5`. ::: :::info When a Spot instance is reclaimed by Google Cloud, Seqera Platform displays a human-readable description in the task details. Google Batch reserves exit codes in the 50001–59999 range for infrastructure events: | Exit code | Description | |-----------|-------------| | 50001 | Spot instance was reclaimed by Google Cloud | | 50002 | VM became unresponsive (host event or crash) | | 50003 | VM unexpectedly rebooted during task execution | | 50004 | Task reached unresponsive time limit and could not be cancelled | | 50005 | Task exceeded maximum allowed runtime | Exit codes 50006–59999 display a generic infrastructure failure message. Standard application exit codes (1–255) are displayed as before. ::: Apply [**Resource labels**](../resource-labels/overview) to the cloud resources consumed by this compute environment. Workspace default resource labels are prefilled. #### Scripting and environment variables * Expand **Staging options** to include: + Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. + Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: * Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: #### Advanced options :::note If you use VM instance templates for the head or compute jobs (see step 8 below), resource allocation and networking values in the templates override any conflicting values you set while creating your Seqera compute environment. ::: 1. Enable **Use Private Address** to ensure that your Google Cloud VMs aren't accessible to the public internet. 2. Use **Boot disk size** to control the persistent disk size that each task and the head job are provided. 3. Use **Boot Disk Image** to select a specific boot disk image for the compute instances. The drop-down is populated with available images from the GCP Compute API and supports autocomplete filtering. This field is optional. If not set, Google Batch uses the default image. 4. Use **Instance Type** to select one or more machine types for the compute instances. The drop-down is populated with available instance types for the selected region and supports autocomplete filtering. You can select multiple specific instance types or use family wildcards (for example, `c2-*` or `n*`) to allow Google Batch to choose from a family. This field is optional. If not set, Google Batch automatically selects an appropriate machine type. :::note The **Instance Type** field sets the default machine type selection at the compute environment level. You can override this for individual processes using the `machineType` [process directive](https://docs.seqera.io/nextflow/google#process-definition) in your Nextflow configuration, which accepts a comma-separated list of patterns (for example, `c2-*`, `n1-standard-1`, `custom-2-4`). ::: 5. Use **Head job CPUs** and **Head job memory** to specify the CPUs and memory allocated for the head job. :::caution The default head job resource values are insufficient for production pipelines. The Nextflow head job is a JVM process that tracks every submitted task, manages pipeline state, and polls the GCP Batch API. If the head job runs out of memory mid-run, the pipeline fails. Tasks already running on worker VMs run to completion, but no new tasks are scheduled. Output files that were already written are not cleaned up automatically. Results may be incomplete. Size the head job based on the number of tasks in your pipeline: | Pipeline scale | Tasks | Recommended CPUs | Recommended memory | |---|---|---|---| | Small | Up to 100 | 2 | 4 GB | | Medium | 100–500 | 4 | 8 GB | | Large | 500+ | 8 | 16 GB | Head job memory scales with the number of concurrent tasks and total pipeline duration. Long-running pipelines keep thousands of task records in memory for resumability, and need more memory than short pipelines with the same peak parallelism. Increase CPUs if task scheduling is slow or the head job logs show high garbage collection (GC) pressure. For large pipelines, you can also increase the JVM heap directly by setting `NXF_JVM_ARGS="-Xms4g -Xmx12g"` as a **Head job** environment variable (see [Scripting and environment variables](#scripting-and-environment-variables)). ::: :::note If you specify a **Head job instance template** (see step 9), the template's machine type overrides the **Head job CPUs** and **Head job memory** values set here. ::: 6. Use **Service Account email** to specify a service account email address other than the Compute Engine default to execute workflows with this compute environment (recommended for production environments). 7. Use **VPC** and **Subnet** to specify the name of a VPC network and subnet to be used by this compute environment. You can apply network tags directly in the **Network Tags** field (see below) or through VM instance templates used for the Nextflow head and compute jobs. :::note You must specify both a **VPC** and **Subnet** for your compute environment to use either. ::: 8. Use **Network Tags** to apply GCP network tags to the compute instances in this environment. Network tags control which firewall rules and routing policies apply to your instances within a VPC. Enter tags as free-text values. Tags must follow GCP format requirements: lowercase letters, numbers, and hyphens only, between 1 and 63 characters. You can add up to 64 tags per instance. :::note Network tags require a **VPC** and **Subnet** to be configured. This field is disabled when no VPC is set. ::: 9. Use **Head job instance template** and **Compute jobs instance template** to specify the name or fully-qualified reference of a VM instance template, without the `template://` prefix, to use for the head and compute jobs. [VM instance templates](https://cloud.google.com/compute/docs/instance-templates) allow you to define the resources allocated to Batch jobs. Configuration values defined in a VM instance template override any conflicting values you specify while creating your Seqera compute environment. :::caution Seqera does not validate the VM instance template you specify in these fields. Generally, use templates that define only the machine type, network, disk, and configuration values that will not change across multiple VM instances and Seqera compute environments. See [Create instance templates](https://cloud.google.com/compute/docs/instance-templates/create-instance-templates) for instructions to create your instance templates. ::: To prevent errors during workflow execution, ensure that the instance templates you use are suitably configured for your needs with an appropriate machine type. You can define multiple instance templates with varying machine type sizes in your Nextflow configuration using the `machineType` [process directive](https://docs.seqera.io/nextflow/google#process-definition) (e.g., `process.machineType = 'template://my-template-name'`). You can use [process selectors](https://docs.seqera.io/nextflow/config#config-process-selectors) to assign separate templates to each of your processes. Select **Create** to finalize the compute environment setup. :::info See [Launch pipelines](https://docs.seqera.io/platform-enterprise/launch/launchpad) to start executing workflows in your Google Cloud Batch compute environment. ::: --- ## Google Cloud :::note This compute environment type is currently in public preview. Consult this guide for the latest information on recommended configuration and limitations. This guide assumes you already have a GCP account with a valid subscription. ::: Many of the current implementations of compute environments for cloud providers rely on the use of batch services such as AWS Batch, Azure Batch, and Google Batch for the execution and management of submitted jobs, including pipelines and Studio session environments. Batch services are suitable for large-scale workloads, but they add management complexity. In practical terms, the currently used batch services result in some limitations: - **Long launch delay**: When you launch a pipeline or Studio in a batch compute environment, there's a delay of several minutes before the pipeline or Studio session environment is in a running state. This is caused by the batch services that need to provision the associated compute service to run a single job. - **Complex setup**: Standard batch services require complex identity management policies and configuration of multiple components including batch job definitions, task specifications, resource policies, etc. The Google Cloud compute environment addresses these pain points with: - **Faster startup time**: By eliminating the per-task overhead of VM provisioning, environment bootstrapping, and container image pulling that occurs with traditional batch, Nextflow pipelines reach a `Running` status and Studio sessions connect in under a minute (a 4x improvement compared to classic GCP Batch compute environments). - **Simplified configuration**: Fewer configurable options, with opinionated defaults, provide the best Nextflow pipeline and Studio session execution environment, with both Wave and Fusion enabled. - **Fewer GCP dependencies**: Direct use of Compute Engine eliminates the reliance on Google Batch APIs and reduces the required IAM permissions to core services (Compute Engine, Cloud Storage, and IAM), resulting in a simpler architecture with fewer potential points of failure. This type of compute environment is best suited to run Studios and small to medium-sized pipelines. It offers more predictable compute pricing, given the fixed instance types. It spins up a standalone Google Compute Engine instance and executes a Nextflow pipeline or Studio session with a local executor on the Google Compute Engine machine. At the end of the execution, the instance is terminated. ## Limitations The Nextflow pipeline will run entirely on a single Google Compute Engine instance. If the instance does not have sufficient resources, the pipeline execution will fail. For this reason, the number of tasks Nextflow can execute in parallel is limited by the number of cores of the instance type selected. If you need more computing resources, you must create a new compute environment with a larger instance type. This makes the compute environment less suited for larger, more complex pipelines. ## Supported locations The following locations are currently supported: - `asia-east1` - `asia-east2` - `asia-northeast1` - `asia-northeast2` - `asia-northeast3` - `asia-south1` - `asia-south2` - `asia-southeast1` - `asia-southeast2` - `australia-southeast1` - `australia-southeast2` - `europe-central2` - `europe-north1` - `europe-southwest1` - `europe-west1` - `europe-west2` - `europe-west3` - `europe-west4` - `europe-west6` - `europe-west8` - `europe-west9` - `europe-west10` - `europe-west12` - `me-central1` - `me-west1` - `northamerica-northeast1` - `northamerica-northeast2` - `southamerica-east1` - `southamerica-west1` - `us-central1` - `us-east1` - `us-east4` - `us-east5` - `us-south1` - `us-west1` - `us-west2` - `us-west3` - `us-west4` ## Requirements ### Platform credentials To create and launch pipelines or Studio sessions with this compute environment type, you must attach Seqera credentials for the cloud provider. Some permissions are mandatory for the compute environment to be created and function correctly; others are used to pre-fill Platform options, which are optional. ### Required permissions #### Service account permissions​ [Create a custom service account](https://cloud.google.com/iam/docs/service-accounts-create#creating) with at least the following permissions: - Compute instance admin (`roles/compute.instanceAdmin.v1`) - Project IAM admin (`roles/resourcemanager.projectIamAdmin`) - Service Account Admin (`roles/iam.serviceAccountAdmin`) - Service Account User (`roles/iam.serviceAccountUser`) - Service Usage Consumer (`roles/serviceusage.serviceUsageConsumer`) If your Google Cloud project does not require access restrictions on any of its Cloud Storage buckets, you can grant project Storage Admin (`roles/storage.admin`) permissions to your service account to simplify setup. To grant access only to specific buckets, add the service account as a principal [on each bucket individually](https://docs.seqera.io/platform-cloud/compute-envs/google-cloud-batch#cloud-storage-bucket). For each Google Cloud compute environment created in the Seqera platform, a separate service account is created with the necessary permissions to launch pipelines/studios. ## Advanced options - **Use an ARM64 architecture instance**: Select this option to enable an ARM architecture instance to be created for your compute workload. This option defaults to using a [C4A machine series](https://cloud.google.com/compute/docs/general-purpose-machines#c4a_series) VM with Google's ARM-based Axion™ processor. - **User GPU-enabled instance**: Select this option to enable a GPU-enabled instance to be created for your compute workload. This option defaults to using an [A2 machine series](https://cloud.google.com/compute/docs/gpus) VM with an NVIDIA A100 GPU. - **Instance type**: The Compute Engine machine type used by the compute environment. Choosing the instance type will directly allocate the CPU and memory available for computation. See the [machine resource type documentation](https://cloud.google.com/compute/docs/machine-resource) for a comprehensive list of instance types and their resource limitations. :::note It is not possible to specify instance templates with predefined machine types, storage, bootstrapped, etc. ::: - **Image**: The image defining the operating system and pre-installed software for the VM. Currently only [Ubuntu LTS](https://cloud.google.com/compute/docs/images/os-details#ubuntu_lts) Google public image project images are available and supported. For GPU-enabled instances, a Deep Learning VM base image with CUDA pre-installed is automatically selected (See [Google Deep Learning VM Images](https://cloud.google.com/deep-learning-vm/docs/images#base_versions) for more details). Optimized, Seqera-owned custom images will be available in a future release. - **Boot disk size**: The size of the boot disk for the Compute Engine instance. A standard persistent disk (`pd-standard`) is used. If undefined, a default 50 GB volume will be used. - **Zone**: The [zone](https://cloud.google.com/compute/docs/regions-zones) within the selected region where the VM will be provisioned (defaults to the first zone in the alphabetical list). --- ## HPC compute environments Seqera Platform streamlines the deployment of Nextflow pipelines into both cloud-based and on-prem HPC clusters and supports compute environment creation for the following management and scheduling solutions: - [Altair PBS Pro](https://www.altair.com/pbs-professional/) - [Grid Engine](https://www.altair.com/grid-engine/) - [IBM Spectrum LSF](https://www.ibm.com/products/hpc-workload-management/details) (Load Sharing Facility) - [Moab](http://docs.adaptivecomputing.com/suite/8-0/basic/help.htm#topics/moabWorkloadManager/topics/intro/productOverview.htm) - [Slurm](https://slurm.schedmd.com/overview.html) ## Requirements To launch pipelines into an **HPC** cluster from Seqera, the following requirements must be satisfied: - The cluster should allow outbound connections to the Seqera web service. - The cluster queue used to run the Nextflow head job must be able to submit cluster jobs. - The Nextflow runtime version **21.02.0-edge** (or later) must be installed on the cluster. ## Credentials Seqera requires SSH access to your HPC cluster to run pipelines. Use [managed identities](../credentials/managed_identities) to enable granular access control and preserve individual cluster user identities. You can also use workspace [SSH credentials](../credentials/ssh_credentials) for cluster login, but this provides service account access to your HPC to all Platform users. This means that all users will be granted the same file system access, and all activity is logged under the same user account on your HPC cluster. For HPC clusters that do not allow direct access through an SSH client, a secure connection can be authenticated with [Tower Agent](../supported_software/agent/overview). ## Work and launch directories For instances where the work directory or launch directory must be set dynamically at runtime, you can use variable expansion. This works in conjunction with Tower Agent. The path that results from variable expansion must exist before workflow execution as the agent does not create directories. For example, if the HPC cluster file system has a `/workspace` directory with subdirectories for each user that can run jobs, the value for the work directory can be the following: `/workspace/$TW_AGENT_USER`. For a user `user1`, the work directory resolves to the `/workspace/user1` directory. The following variables are supported: - `TW_AGENT_WORKDIR`: Resolves to the work directory for Tower Agent. By default, this directory resolves to the `${HOME}/work` path, where `HOME` is the home directory of the user that the agent runs as. The work directory can be overridden by specifying the `--work-dir` argument when configuring Tower Agent. For more information, see the [Tower Agent][agent] documentation. - `TW_AGENT_USER`: Resolves to the username that the agent is running as. By default, this is the Unix username that the agent runs as. On systems where the agent cannot determine which user it runs as, it falls back to the value of the `USER` environment variable. ## HPC compute environment To create a new **HPC** compute environment: 1. In a Seqera workspace, select **Compute environments > New environment**. 1. Enter a descriptive name for this environment. Use only alphanumeric characters, dashes, and underscores. 1. Select your HPC environment from the **Platform** drop-down. 1. Select your existing managed identity, SSH, or Tower Agent credentials, or select **+** and **SSH** or **Tower Agent** to add new credentials. 1. Enter the absolute path of the **Work directory** to be used on the cluster. You can use the `TW_AGENT_WORKDIR` and `TW_AGENT_USER` variables in the file system path. :::caution All managed identity users must be a part of the same Linux user group. The group must have access to the HPC compute environment work directory. Set group permissions for the work directory as follows (replace `sharedgroupname` and `` with your group name and work directory): ```bash chgrp -R sharedgroupname chmod -R g+wxs setfacl -Rdm g::rwX ``` These commands change the group ownership of all files and directories in the work directory to `sharedgroupname`, ensure new files inherit the directory's group, and apply default ACL entries to allow the group read, write, and execute permissions for new files and directories. This setup facilitates shared access and consistent permissions management in the directory. ::: 1. Enter the absolute path of the **Launch directory** to be used on the cluster. If omitted, it will be the same as the work directory. 1. Enter the **Login hostname**. This is usually the hostname or public IP address of the cluster's login node. 1. Enter the **Head queue name**. This is the [default](https://docs.seqera.io/nextflow/process#queue) cluster queue to which the Nextflow job will be submitted. 1. Enter the **Compute queue name**. This is the [default](https://docs.seqera.io/nextflow/process#queue) cluster queue to which the Nextflow job will submit tasks. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options needed: - Use the **Nextflow queue size** to limit the number of jobs that Nextflow can submit to the scheduler at the same time. - Use the **Head job submit options** to add platform-specific submit options for the head job. You can optionally apply these options to compute jobs as well: :::note Once set during compute environment creation, these options can't be overridden at pipeline launch time. ::: :::note In IBM LSF compute environments, use **Unit for memory limits**, **Per job memory limits**, and **Per task reserve** to control how memory is requested for Nextflow jobs. ::: 1. Select **Create** to finalize the creation of the compute environment. See [Launch pipelines](../launch/launchpad) to start executing workflows in your HPC compute environment. [agent]: ../supported_software/agent/overview --- ## Kubernetes [Kubernetes](https://kubernetes.io/) is the leading technology for the deployment and orchestration of containerized workloads in cloud-native environments. Seqera Platform streamlines the deployment of Nextflow pipelines into Kubernetes, both for cloud-based and on-prem clusters. The following instructions create a Seqera compute environment for a **generic Kubernetes** distribution. See [Amazon EKS](./eks) or [Google Kubernetes Engine (GKE)](./gke) for EKS and GKE compute environment instructions. ## Cluster preparation To prepare your Kubernetes cluster for the deployment of Nextflow pipelines using Seqera, this guide assumes that you've already created the cluster and that you have administrative privileges. This guide applies a Kubernetes manifest that creates a service account named `tower-launcher-sa` and the associated role bindings, all contained in the `tower-nf` namespace. Seqera uses the service account to launch Nextflow pipelines. Use this service account name when setting up the compute environment for this Kubernetes cluster in Seqera. **Prepare your Kubernetes cluster for Seqera Platform** 1. Verify the connection to your Kubernetes cluster: ```bash kubectl cluster-info ``` 1. Create a file named `tower-launcher.yml` with the following YAML: ```yaml file=../_templates/k8s/tower-launcher.yml showLineNumbers ``` 1. Apply the manifest: ```bash kubectl apply -f tower-launcher.yml ``` 1. Create a persistent API token for the `tower-launcher-sa` service account: ```bash kubectl apply -f - < ``` ## Seqera compute environment After you've prepared your Kubernetes cluster for Seqera integration, create a compute environment: **Create a Seqera Kubernetes compute environment** 1. In a workspace, select **Compute environments > New environment**. 1. Enter a descriptive name for this environment, e.g., _K8s cluster_. 1. Select **Kubernetes** as the target platform. 1. From the **Credentials** drop-down, select existing Kubernetes credentials, or select **+** to add new credentials. If you choose to use existing credentials, skip to step 7. :::tip You can create multiple credentials in your Seqera workspace. See [Credentials](../credentials/overview). ::: 1. Enter a name, such as _K8s Credentials_. 1. Select either the **Service Account Token** or **X509 Client Certs** tab: - To authenticate using a Kubernetes service account, enter your **Service account token**. Obtain the token with the following command: ```bash kubectl -n tower-nf describe secret | grep -E '^token' | cut -f2 -d':' | tr -d '\t ' ``` Replace `` with the name of the service account token created in the [cluster preparation](#cluster-preparation) instructions (default: `tower-launcher-token`). - To authenticate using an X509 client certificate, paste the contents of your certificate and key file (including the `-----BEGIN...-----` and `-----END...-----` lines) in the **Client certificate** and **Client Key** fields respectively. See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/certificates/) for instructions to generate your client certificate and key. 1. Enter the **Control plane URL**, obtained with this command: ```bash kubectl cluster-info ``` It can also be found in your `~/.kube/config` file under the `server` field corresponding to your cluster. 1. Specify the **SSL certificate** to authenticate your connection. Find the certificate data in your `~/.kube/config` file. It is the `certificate-authority-data` field corresponding to your cluster. 1. Specify the **Namespace** created in the [cluster preparation](#cluster-preparation) instructions, which is _tower-nf_ by default. 1. Specify the **Head service account** created in the [cluster preparation](#cluster-preparation) instructions, which is _tower-launcher-sa_ by default. 1. Specify the **Storage claim** created in the [cluster preparation](#cluster-preparation) instructions, which serves as a scratch filesystem for Nextflow pipelines. The storage claim is called _tower-scratch_ in each of the provided examples. 1. Apply [**Resource labels**](../resource-labels/overview) to the cloud resources consumed by this compute environment. Workspace default resource labels are prefilled. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options described below, as needed. 1. Select **Create** to finalize the compute environment setup. See [Launch pipelines](../launch/launchpad) to start executing workflows in your Kubernetes compute environment. ### Advanced options Seqera Platform compute environments for Kubernetes include advanced options for storage and work directory paths, resource allocation, and pod customization. **Seqera Kubernetes advanced options** - The **Storage mount path** is the file system path where the Storage claim is mounted (default: `/scratch`). - The **Work directory** is the file system path used as a working directory by Nextflow pipelines. It must be the storage mount path (default) or a subdirectory of it. - The **Compute service account** is the service account used by Nextflow to submit tasks (default: the `default` account in the given namespace). - The **Pod cleanup policy** determines when to delete terminated pods. - Use **Custom head pod specs** to provide custom options for the Nextflow workflow pod (`nodeSelector`, `affinity`, etc). For example: ```yaml spec: nodeSelector: disktype: ssd ``` - Use **Custom service pod specs** to provide custom options for the compute environment pod. See above for an example. - Use **Head job CPUs** and **Head job memory** to specify the hardware resources allocated to the Nextflow workflow pod. --- ## Compute environment overview Seqera Platform **compute environments** define the execution platform where a pipeline will run. Compute environments enable users to launch pipelines on a growing number of **cloud** and **on-premises** platforms. Each compute environment must be configured to enable Seqera to submit tasks. See the individual compute environment pages below for platform-specific configuration steps. ## Platforms - [AWS Batch](./aws-batch) - [AWS Cloud](./aws-cloud) - [Azure Batch](./azure-batch) - [Google Batch](./google-cloud-batch) - [Google Cloud](./google-cloud) - [Grid Engine](./hpc) - [Altair PBS Pro](./hpc) - [IBM LSF](./hpc) - [Moab](./hpc) - [Slurm](./hpc) - [Kubernetes](./k8s) - [Amazon EKS](./eks) - [Google Kubernetes Engine](./gke) :::note Compute Environments now support descriptions. Enter a description during creation to provide context and information. To update a description, select **Edit** from the menu of the relevant compute environment. You can update descriptions at any time (e.g., to reflect a status change), up to a 1000-character limit. You can also add descriptions to existing compute environments that don't have one. ::: ## Select default compute environment If you have more than one compute environment, you can select a workspace primary compute environment to be used as the default when launching pipelines in that workspace. In a workspace, select **Compute Environments**. Then select **Make primary** from the options menu next to the compute environment you wish to use as default. ## Rename compute environment You can edit the names of compute environments in private and organization workspaces. Select **Rename** from the options menu next to the compute environment you wish to edit. Select **Update** on the edit page to save your changes after you have updated the compute environment name. ## Disable compute environment Users with **Admin** or **Owner** [workspace permissions](../orgs-and-teams/roles#workspace-participant-roles) can disable and enable compute environments. When you disable a compute environment: - Actions that use this compute environment will fail to run. **Update actions to use a new compute environment**. - New pipelines and Studio sessions will not run on the disabled compute environment. **Update pipelines and Studios to use a new compute environment**. - **Running pipelines and Studio sessions are not terminated**. Ongoing runs and Studio sessions will finish gracefully. - If the compute environment was set as primary, it will be unset. Until you select a new primary compute environment, new runs will default to the next available compute environment. To disable a compute environment, select **Disable** from the options menu next to the compute environment in your workspace **Compute Environments** page. To re-enable a disabled compute environment, select **Enable** from the options menu. Enabled compute environments can run new pipelines and Studio sessions. ## Export compute environment You can export a compute environment's configuration as a JSON file for troubleshooting, audits, or as a reference when recreating it. :::note The exported JSON is for reference only. Re-importing it through the Seqera Platform UI is not supported. ::: Any user with the Maintain, Launch, or View role on the workspace can export. The compute environment detail page, or the form page for a specific compute environment. **What's included**: - Name, platform, region, and work directory - Forge or manual configuration block - Fusion and Wave settings - Environment variables - Pre- and post-run scripts - Labels - A reference to the credential used (the credential itself is excluded) **What's not included**: - Credentials and secrets ## Disable compute environment Users with **Admin** or **Owner** [workspace permissions](../orgs-and-teams/roles#workspace-participant-roles) can disable and enable compute environments. When you disable a compute environment: - Actions that use this compute environment will fail to run. **Update actions to use a new compute environment**. - New pipelines and Studio sessions will not run on the disabled compute environment. **Update pipelines and Studios to use a new compute environment**. - **Running pipelines and Studio sessions are not terminated**. Ongoing runs and Studio sessions will finish gracefully. - If the compute environment was set as primary, it will be unset. Until you select a new primary compute environment, new runs will default to the next available compute environment. To disable a compute environment, select **Disable** from the options menu next to the compute environment in your workspace **Compute Environments** page. To re-enable a disabled compute environment, select **Enable** from the options menu. Enabled compute environments can run new pipelines and Studio sessions. ## Delete compute environment Compute environments can be deleted when they are no longer required. You must delete the compute environment before deleting its associated credentials. If the credentials are deleted first, the compute environment deletion will fail with an error. If this happens, the entry needs to be manually deleted from the database to fully remove it. ## GPU usage The process for provisioning GPU instances in your compute environment differs for each cloud provider. ### AWS Batch The AWS Batch compute environment creation form in Seqera includes an **Enable GPUs** option. This enables you to run GPU-dependent workflows in the compute environment. Some important considerations: - Seqera only supports NVIDIA GPUs. Select instances with NVIDIA GPUs for your GPU-dependent processes. - The **Enable GPUs** setting causes Batch Forge to specify the most current [AWS-recommended GPU-optimized ECS AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html) as the EC2 fleet AMI when creating the compute environment. This setting can be overridden by **AMI ID** in the advanced options. - The **Enable GPUs** setting alone does not deploy GPU instances in your compute environment. You must still specify GPU-enabled instance types in the **Advanced options > Instance types** field. - Your Nextflow script must include [accelerator directives](https://docs.seqera.io/nextflow/process.html?highlight=accelerator#accelerator) to use the provisioned GPUs. - The NVIDIA Container Runtime uses [environment variables](https://github.com/NVIDIA/nvidia-container-runtime#environment-variables-oci-spec) in container images to specify a GPU accelerated container. These variables should be included in the [`containerOptions`](https://docs.seqera.io/nextflow/process#process-containeroptions) directive for each GPU-dependent process in your Nextflow script. The `containerOptions` directive can be set inline in your process definition or via configuration. For example, to add the directive to a process named `UseGPU` via configuration: ```groovy process { withName: UseGPU { containerOptions '-e NVIDIA_DRIVER_CAPABILITIES=compute,utility -e NVIDIA_VISIBLE_DEVICES=all' } } ``` - GPU-accelerated containers (such as NVIDIA Parabricks) bundle a specific CUDA runtime. The compute environment's AMI must include an NVIDIA driver compatible with the container's CUDA runtime. When **Enable GPUs** is set, Batch Forge selects the current AWS-recommended GPU-optimized ECS AMI. If you override **AMI ID** under **Advanced options**, confirm that the custom AMI's driver satisfies the container's CUDA version. See the [NVIDIA CUDA compatibility matrix](https://docs.nvidia.com/deploy/cuda-compatibility/) for supported driver versions. For GPU driver and CUDA compatibility errors, see [AWS troubleshooting](../troubleshooting_and_faqs/aws_troubleshooting#gpus). ### GPU metrics :::note Detailed GPU metrics are only available for tasks that run with Fusion version 2.5.10 onwards and using Nextflow version 26.03.3-edge onwards ::: When [Fusion](https://docs.seqera.io/fusion) is enabled, Seqera Platform automatically collects GPU metrics for tasks that run on NVIDIA GPU instances. No additional configuration is required beyond enabling Fusion and provisioning GPU instances in your compute environment. The following metrics are collected per task: - **GPU type**: The GPU model (e.g., NVIDIA A10G, A100). - **Driver version**: The NVIDIA driver version in use. - **GPU utilization %**: The percentage of GPU compute capacity used. - **GPU memory peak**: The maximum GPU memory used during execution. - **GPU memory average**: The average GPU memory used during execution. For tasks that use multiple GPUs, metrics are aggregated (average or peak across all GPUs assigned to the task) and displayed as a single combined value per task. #### Where GPU metrics appear - **Task detail view**: Select a GPU task in the task table to view GPU type, driver version, utilization, and memory metrics alongside existing CPU metrics. ![GPU metrics in task detail view](./_images/gpu-metrics-task.png) - **Metrics tab**: A dedicated **GPU** section displays box-and-whisker plots grouped by task name, with tabs for **GPU Utilization %**, **Memory Peak**, and **Memory Average**. This section appears only when the workflow includes tasks with GPU data. ![GPU utilization](./_images/gpu-metrics-utilization.png) ![GPU memory peak](./_images/gpu-metrics-memory-peak.png) ![GPU memory average](./_images/gpu-metrics-memory-average.png) - **Platform API**: GPU metrics are included in [task](https://docs.seqera.io/platform-api/describe-workflow-task) and [workflow](https://docs.seqera.io/platform-api/list-workflow-tasks) API responses for programmatic access. :::note GPU metrics are only available for tasks that run with Fusion enabled on NVIDIA GPU instances. Non-GPU tasks do not display a GPU metrics section. For tasks that fail mid-execution, partial metrics collected up to the point of failure are shown. ::: --- ## Compute environment pre-flight checks Pre-flight checks validate that a compute environment is usable before you launch a pipeline. They run on a recurring background schedule and again at launch time, so problems surface before submission rather than mid-run. Pre-flight checks only flag conditions that would block a launch. Pre-flight checks are **disabled by default** in Seqera Platform Enterprise and must be enabled by an administrator. ## What to verify before creating a compute environment Before creating or deploying a compute environment, confirm the following: **Credentials** - The access keys, service account key, or managed identity are valid and have not been rotated or revoked. - The IAM role or service account has the permissions required by the cloud provider. See the relevant compute environment page for the minimum required policy. **Wave** (if enabled) - The Wave service is running and reachable from Seqera Platform. **Tower Agent** (HPC/grid compute environments only) - Tower Agent is reachable from Platform. See [Tower Agent](../supported_software/agent/overview) for installation and startup instructions. ## Enable pre-flight checks Pre-flight checks require two flags set to `true` in `tower.yml`. Setting only one is not sufficient. | Environment variable | `tower.yml` key | What it does | Default | |---|---|---|---| | `TOWER_CREDENTIALS_VALIDATION_ENABLED` | `tower.credentials.validation.enabled` | Enables credential status tracking. When `true`, credentials are automatically validated against the cloud provider on create and update. The validation result (status and error message) is persisted on the credential record and displayed in the UI. When `false`, validation is skipped on create/update, the credential status block is hidden in the UI, and `/credentials/{id}/validate` returns a non-persisting result. | `false` | | `TOWER_PREFLIGHT_CHECK_ENABLED` | `tower.preflight.check.enabled` | Master switch for pre-flight checks. When `true`, the background credentials-validation cron probes in-scope credentials on a schedule, the compute environment validation cron validates environments on a schedule, Platform rejects launches against `INVALID` credentials or compute environments with a `400 Bad Request`, and the compute environment creation picker hides `INVALID` credentials. When `false`, both crons are dormant, the launch API treats `INVALID` status as advisory only, and the picker shows every credential regardless of status. | `false` | :::note Both flags are read once at process start. Restart the `backend` and `cron` containers after changing either value. ::: ## Validation process Platform runs three tiers of validation: ### 1. Credential validation Runs on a recurring schedule. For each cloud credential (AWS, Google Cloud, Azure) in scope, Platform calls the provider API to verify that the credential is still accepted. For AWS role-based credentials and Google Cloud Workload Identity Federation, this check confirms the credential is well-formed but cannot fully verify the underlying role or identity provider trust configuration. When a credential fails this check, Platform marks it **INVALID** and records the provider error on the credential record. This error appears in the launch-time error message when a pipeline is blocked, but not in the compute environment banner. To see the specific provider error, check the credential record directly. ### 2. Compute environment validation Platform checks the associated credential status. If the credential is `INVALID`, the compute environment is marked `INVALID` immediately. A compute environment marked `INVALID` displays a banner with the error message. An `AVAILABLE` compute environment has its `lastValidated` timestamp refreshed. :::note These checks cover AWS Batch, AWS Cloud, Azure Batch, Azure Cloud, Google Cloud Batch, and Google Cloud compute environments. ::: ### 3. Pipeline launch-time checks Runs immediately when a user submits a pipeline launch. If any check fails, the launch is blocked and a specific error is returned. Multiple failures are reported together. | Check | What it does | |---|---| | Compute environment status | Reads the last recorded status from the database. Blocks launch if the compute environment is marked `INVALID`. | | Credential status | Reads the last recorded status from the database. Blocks launch if the credential associated with the compute environment is marked `INVALID`. | | Wave connectivity | For compute environments with Wave enabled, verifies the Wave service connection is active | | Tower Agent | For HPC compute environments, verifies a Tower Agent is online for the environment | ## Validate a credential manually After you rotate the keys or fix the underlying issue on an `INVALID` credential, trigger an immediate re-validation: 1. Navigate to **Credentials** in your workspace. 2. Find the credential and select **Validate**. Platform makes a live call to the cloud provider and updates the credential status immediately. If the check passes, the credential returns to `AVAILABLE`. Compute environments marked `INVALID` because of this credential do not recover automatically. Use **Validate** on each affected compute environment after restoring the credential. ## Validate a compute environment manually After you fix the underlying issue on an `INVALID` compute environment, trigger an immediate re-validation without waiting for the next background sweep: 1. Navigate to **Compute environments** in your workspace. 2. Find the compute environment and open its **⋮** (three-dot) drop-down. 3. Select **Validate**. Platform runs pre-flight checks and updates the compute environment status immediately. If all checks pass, the compute environment returns to `AVAILABLE`. :::warning[Validate the credential before the compute environment] If both the credential and its associated compute environment are marked `INVALID`, you must restore the credential to `AVAILABLE` before validating the compute environment. If the credential is still `INVALID`, the compute environment remains `INVALID`. ::: ## Advanced configuration (optional) The defaults work for most deployments. Only adjust these if you have specific rate-limit or scheduling requirements. These parameters only take effect when `TOWER_PREFLIGHT_CHECK_ENABLED=true`. ### Credential validation cron | Environment variable | `tower.yml` key | Description | Default | |---|---|---|---| | `TOWER_CRON_CREDENTIALS_VALIDATION_INTERVAL` | `tower.cron.credentials-validation.interval` | Per-credential re-validation cadence. After each successful probe, the credential is rescheduled at `now + interval ± 10%` jitter. This is a background freshness job. Because the launch-path check independently handles real-time launch-blocking on revoked credentials, you can safely relax this cadence. | `12h` | | `TOWER_CRON_CREDENTIALS_VALIDATION_TICK_RATE` | `tower.cron.credentials-validation.tick-rate` | How often the evaluator polls the Redis schedule store for due credentials. Distinct from the per-credential interval. | `60s` | | `TOWER_CRON_CREDENTIALS_VALIDATION_DELAY` | `tower.cron.credentials-validation.delay` | Initial delay before the first evaluator tick after process start. Randomised ±50% to spread cold-start load across replicas. | `20s` | | `TOWER_CRON_CREDENTIALS_VALIDATION_BATCH_SIZE` | `tower.cron.credentials-validation.batch-size` | Maximum credential IDs drained from the Redis schedule store per evaluator tick. | `100` | | `TOWER_CRON_CREDENTIALS_VALIDATION_CONCURRENCY` | `tower.cron.credentials-validation.concurrency` | Global in-flight cap on concurrent cloud probes across all evaluator pumps. Tune conservatively when many credentials in one workspace share a single cloud account to avoid provider rate limits (for example, AWS STS `TooManyRequests`). | `10` | | `TOWER_CRON_CREDENTIALS_VALIDATION_PROBE_DELAY` | `tower.cron.credentials-validation.probe-delay` | Optional sleep between probes within a single pump. Set to a non-zero value (for example, `200ms`) when many credentials share a cloud account and a cold-start burst would exceed provider rate limits. | `0ms` (no pacing) | | `TOWER_CRON_CREDENTIALS_VALIDATION_TRANSIENT_RETRY_INTERVAL` | `tower.cron.credentials-validation.transient-retry-interval` | Shorter cadence used to re-enqueue a credential after a transient probe failure (network interruption, provider 5xx, unexpected SDK exception). Prevents a credential from being silently skipped until the next process restart. | `5m` | ### Compute environment validation cron | Environment variable | `tower.yml` key | Description | Default | |---|---|---|---| | `TOWER_CRON_COMPUTE_ENV_VALIDATION_INTERVAL` | `tower.cron.compute-env-validation.interval` | Compute environment re-validation cadence. A compute environment is due when its `lastValidated` timestamp is null or older than `now - interval`. | `12h` | | `TOWER_CRON_COMPUTE_ENV_VALIDATION_TICK_RATE` | `tower.cron.compute-env-validation.tick-rate` | How often the evaluator sweeps the database for due compute environments. Distinct from the per-compute-environment interval. | `60s` | | `TOWER_CRON_COMPUTE_ENV_VALIDATION_DELAY` | `tower.cron.compute-env-validation.delay` | Initial delay before the first evaluator tick after process start. Randomised ±50% to spread cold-start load across replicas. | `20s` | | `TOWER_CRON_COMPUTE_ENV_VALIDATION_BATCH_SIZE` | `tower.cron.compute-env-validation.batch-size` | Maximum compute environment IDs swept from the database per evaluator tick. | `100` | ### Credential auto-validation timeout Only effective when `TOWER_CREDENTIALS_VALIDATION_ENABLED=true`. | Environment variable | `tower.yml` key | Description | Default | |---|---|---|---| | `TOWER_CREDENTIALS_AUTO_VALIDATION_TIMEOUT_SEC` | `tower.credentials.autoValidationTimeoutSec` | Timeout in seconds for the cloud provider probe triggered when a credential is created or updated. Platform treats timeout expiry as a transient failure and leaves the persisted status untouched. | `10` | ## Error reference For pre-flight check error messages, causes, and resolutions, see [Pre-flight checks troubleshooting](../troubleshooting_and_faqs/preflight_checks_troubleshooting). --- ## Tower Agent credentials [Tower Agent](../supported_software/agent/overview) enables Seqera Platform to launch pipelines on HPC clusters that do not allow direct access through an SSH client. Tower Agent authenticates a secure connection with Seqera using a Tower Agent credential. ## Tower Agent sharing You can share a single Tower Agent instance with all members of a workspace. Create a Tower Agent credential, with **Shared agent** enabled, in the relevant workspace. All workspace members can then use this credential (Connection ID + Seqera access token) to use the same Tower Agent instance. ## Create a Tower Agent credential 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-agent-creds`. - **Provider**: Select **Tower Agent**. - **Agent connection ID**: The connection ID used to run your Tower Agent instance. Must match the connection ID used when running the Agent (see **Usage** below). - **Shared agent**: Enables Tower Agent sharing for all workspace members. - **Usage**: Populates a code snippet for Tower Agent download with your connection ID. Replace `` with your [Seqera access token](https://docs.seqera.io/platform-api/create-token). 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## AWS ECR credentials From version 22.3, Seqera Platform supports the configuration of credentials for the Nextflow Wave container service to authenticate to private and public container registries. For more information on Wave containers, see [the Nextflow documentation](https://docs.seqera.io/nextflow/wave). :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## AWS ECR Private Registry Wave requires programmatic access to your private Elastic Container Registry (ECR) via [long-term access keys](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#create-long-term-access-keys). Create a user with registry read permissions (e.g., a subset of the AWS-managed `AmazonEC2ContainerRegistryReadOnly` policy) for this purpose. **Create an IAM user with AWS ECR access** 1. Open the [IAM console](https://console.aws.amazon.com/iam/). 2. Select **Users** from the navigation pane. 3. Select the name of the user whose keys you want to manage, then select the **Security credentials** tab. We recommend creating an IAM user specifically for Wave authentication instead of using existing credentials with broader permissions. 4. In the **Access keys** section, select **Create access key**. Each IAM user can have only two access keys at a time, so if the Create option is deactivated, delete an existing access key first. 5. On the **Access key best practices & alternatives** page, select **Other** and then **Next**. 6. On the **Retrieve access key** page, you can either **Show** the user's secret access key details, or store them by selecting **Download .csv file**. 7. The newly created access key pair is active by default and can be stored as a container registry credential in Seqera. :::note Your credential must be stored in Seqera as a **container registry** credential, even if the same access keys already exist as a workspace credential. ::: ## Add private ECR credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your IAM user access key ID. For example, `AKIAIOSFODNN7EXAMPLE`. - **Password**: Specify your IAM user secret access key. - **Registry server**: Specify your private ECR registry URL. For example, `.dkr.ecr..amazonaws.com`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. ## AWS ECR Public Registry Amazon ECR Public Gallery (`public.ecr.aws`) hosts publicly accessible container images. While images can be pulled without authentication, AWS applies rate limits to unauthenticated pulls. Authenticating with AWS credentials removes these rate limits and is required when running pipelines at scale. ### Required IAM permissions The IAM user needs the following permissions to authenticate to ECR Public: - `ecr-public:GetAuthorizationToken` - `ecr-public:BatchCheckLayerAvailability` - `ecr-public:GetRepositoryPolicy` - `ecr-public:DescribeRepositories` - `ecr-public:DescribeImages` - `ecr-public:DescribeImageTags` - `sts:GetServiceBearerToken` Attach the AWS managed policy `AmazonElasticContainerRegistryPublicReadOnly` and add the `sts:GetServiceBearerToken` permission. This permission is not included in the managed policy and must be granted separately, or ECR Public authentication will fail. ### Add ECR Public credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `ecr-public-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your IAM user access key ID. For example, `AKIAIOSFODNN7EXAMPLE`. - **Password**: Specify your IAM user secret access key. - **Registry server**: Enter `public.ecr.aws`. 3. After you've completed all the form fields, select **Add**. Wave matches the `public.ecr.aws` hostname to these credentials and authenticates ECR Public pulls on your behalf. --- ## Azure container registry credentials From version 22.3, Seqera Platform supports the configuration of credentials for the Nextflow Wave container service to authenticate to private and public container registries. For more information on Wave containers, see the [Nextflow documentation](https://docs.seqera.io/nextflow/wave). :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Azure container registry access Azure container registry makes use of Azure RBAC (Role-Based Access Control) to grant users access. For more information, see [Azure container registry roles and permissions](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-roles). You must use Azure credentials with long-term registry read (**content/read**) access to authenticate Seqera to your registry. We recommend a [token with repository-scoped permissions](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-repository-scoped-permissions) that's used only by Seqera. **Create an access token with Azure container registry access** 1. In the Azure portal, navigate to your container registry. 2. Under **Repository permissions**, select **Tokens > +Add**. 3. Enter a token name. 4. Under **Scope map**, select **Create new**. 5. In the **Create scope map** section, enter a name and description for the new scope map. 6. Select your **Repository** from the drop-down. 7. Select **content/read** from the **Permissions** drop-down, then select **Add** to create the scope map. 8. In the **Create token** section, ensure the **Status** is **Enabled** (default), then select **Create**. 9. Return to **Repository permissions > Tokens** for your registry, then select the token you just created. 10. On the token details page, select **password1** or **password2**. 11. In the password details section, uncheck the **Set expiration date?** checkbox, then select **Generate**. 12. Copy and save the generated password (this is only displayed once). ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your registry token name. For example, `my-registry-token`. - **Password**: Your registry token password. For example, `my-registry-token`. - **Registry server**: Specify the container registry server name. You can obtain this from the Azure portal: **Settings > Access keys > Login server**. For example, `myregistry.azurecr.io`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## Data repositories Data Explorer requires programmatic access via valid credentials to browse and interact with remotely hosted private data repositories. To automatically connect to one or more data repositories, create a new credential that includes **Name** and **Provider**. Specific data repositories require additional information to connect. ## AWS Simple Storage Service (S3) object storage Add an **Access key**, and **Secret key**. You can optionally provide an IAM role for temporary access - this must be a fully qualified AWS role ARN. S3 object storage buckets are prefixed with an AWS icon and `s3://` in Data Explorer. :::note Seqera Compute uses AWS S3 object storage, and are prefixed with a Seqera icon and the `s3://` namespace in Data Explorer. ::: ## Azure Blob Storage Select between different credential types: a **Shared key**, **Entra**, or **Cloud**. - **Shared key:** Access your Azure accounts directly using primary or secondary access keys. - **Entra:** Authenticate via an Azure Entra service principal for enhanced security and identity management. - **Cloud:** Authenticate via an Azure Entra service principal for Azure Cloud. :::info Select Entra for modern, identity-based access control. Select Cloud for Entra identity-based access control with Cloud specializations. Select Shared key for full, direct account access. ::: Add a **Batch account name**, **Batch account key**, **Blob Storage account name**, and **Blob Storage account key**. Azure Blob Storage are prefixed with an Azure icon and `az://` in Data Explorer. ## GCP object storage Add the contents of the **Service account key** JSON file. GCP object storage buckets are prefixed with a GCP icon and `gs://` in Data Explorer. ## S3-compatible storage This includes cloud-provider and on-premise based storage solutions with an S3-compatible API. Examples include [Cloudflare R2][cloudflare], [MinIO][minio], and [Oracle Cloud Infrastructure][oci]. Add an **Access key**, **Secret key**, **Server base URL**, and optionally select path-style URL access. Refer to your S3-compatible storage provider documentation to determine if path-style URL access is applicable. :::info OCI has specific object-storage endpoints that are [S3-compatible][oci-s3-compatible], and include `.compat.` in the server base URL. These are in the form `https://.compat.objectstorage..oci.customer-oci.com`. ::: S3-compatible storage are prefixed with a S3-compatible storage icon and `s3://` in Data Explorer. {/* Links */} [cloudflare]: https://www.cloudflare.com/developer-platform/products/r2/ [minio]: https://min.io [oci]: https://www.oracle.com/cloud/ [oci-s3-compatible]: https://docs.oracle.com/en-us/iaas/api/#/en/s3objectstorage --- ## Docker Hub credentials From version 22.3, Seqera Platform supports the configuration of credentials for the Nextflow Wave container service to authenticate to private and public container registries. For more information on Wave containers, see the [Nextflow documentation](https://docs.seqera.io/nextflow/wave). :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Docker Hub registry access You must use Docker Hub credentials with **Read-only** access to authenticate Seqera to your registry. Docker Hub uses personal access tokens (PATs) for authentication. We don't currently support Docker Hub authentication with 2FA (two-factor authentication). **Create a Docker Hub PAT** 1. Log in to [Docker Hub](https://hub.docker.com/). 2. Select your username in the top right corner and select **Account Settings**. 3. Select **Security > New Access Token**. 4. Enter a token description and select **Read-only** from the Access permissions drop-down, then select **Generate**. 5. Copy and save the generated access token (this is only displayed once). ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your Docker username. For example, `user1`. - **Password**: Specify your personal access token (PAT). For example, `1fcd02dc-...215bc3f3`. - **Registry server**: Specify the container registry hostname, excluding the protocol. For example, `docker.io`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## Gitea container registry credentials From version 22.3, Seqera Platform supports the configuration of credentials for the Nextflow Wave container service to authenticate to private and public container registries. For more information on Wave containers, see the [Nextflow documentation](https://docs.seqera.io/nextflow/wave). Gitea container registries support [authentication][gitea-auth] using a personal access token. Use your personal access token as your password when you create your Gitea container registry credentials in Seqera. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Create a personal access token (PAT) You must create a PAT to access your Gitea container registry from Wave. For more information, see [Create a personal access token][gitea-create]. ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your Gitea username. For example, `gitlab_user1`. - **Password**: Specify your Gitea personal access token (PAT). For example, `1fcd02dc-...215bc3f3`. - **Registry server**: Specify your Gitea container registry URL. For example, `gitea.example.com`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. [gitea-auth]: https://docs.gitea.com/usage/packages/container#login-to-the-container-registry [gitea-create]: https://docs.gitea.com/development/api-usage#authentication --- ## GitHub container registry credentials From version 22.3, Seqera Platform supports the configuration of credentials for the Nextflow Wave container service to authenticate to private and public container registries. For more information on Wave containers, see the [Nextflow documentation](https://docs.seqera.io/nextflow/wave). GitHub Packages only supports [authentication][github-pat] using a personal access token (classic). Use your personal access token as your password when you create your GitHub container registry credentials in Seqera. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Create a personal access token (PAT) You must create a PAT to access your GitHub container registry from Wave. For more information, see [Create a personal access token][github-create]. ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your GitHub username. For example, `github_user1`. - **Password**: Specify your personal access token (PAT) classic. For example, `1fcd02dc-...215bc3f3`. - **Registry server**: Specify your GitHub container registry URL. For example, `ghcr.io`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. [github-pat]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic [github-create]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic --- ## GitLab container registry credentials From version 22.3, Seqera Platform supports the configuration of credentials for the Nextflow Wave container service to authenticate to private and public container registries. For more information on Wave containers, see the [Nextflow documentation](https://docs.seqera.io/nextflow/wave). If your organization enabled two-factor authentication (2FA) for your GitLab organization or project, you must use your [personal access token][gitlab-pat] as your password when you create your [GitLab container registry credentials][gitlab-cr]. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Create a personal access token (PAT) If your organization enabled 2FA for your organization or project, you must create a PAT to access your GitLab container registry from Wave. For more information, see [Create a personal access token][gitlab-create]. If your organization created a [project access token][gitlab-project] or a [group access token][gitlab-group], ask your GitLab administrator for access. ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your GitLab username. - **Password**: Specify your personal access token (PAT), group access token, or project access token if 2FA is enabled by your GitLab organization. Otherwise specify your GitLab password. - **Registry server**: Specify your GitLab container registry URL. For example, `gitlab.example.com`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. [gitlab-cr]: https://docs.gitlab.com/ee/user/packages/container_registry/authenticate_with_container_registry.html [gitlab-pat]: https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html [gitlab-create]: https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token [gitlab-project]: https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html [gitlab-group]: https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html --- ## Google registry credentials From version 22.3, Seqera Platform supports the configuration of credentials for the Nextflow Wave container service to authenticate to private and public container registries. For more information on Wave containers, see the [Nextflow documentation](https://docs.seqera.io/nextflow/wave). :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Google Cloud registry access :::note Although Google Cloud Container Registry is still available and supported as a [Google Enterprise API](https://cloud.google.com/blog/topics/inside-google-cloud/new-api-stability-tenets-govern-google-enterprise-apis), new features will only be available in Artifact Registry. Container Registry will only receive critical security fixes. Google recommends using Artifact Registry for all new registries moving forward. ::: Google Cloud Artifact Registry and Container Registry are fully integrated with Google Cloud services and support various authentication methods. Seqera requires programmatic access to your private registry using [long-lived service account keys](https://cloud.google.com/artifact-registry/docs/docker/authentication#json-key) in JSON format. Create dedicated service account keys that are only used to interact with your repositories. Seqera requires the [Artifact Registry Reader](https://cloud.google.com/artifact-registry/docs/access-control#permissions) or [Storage Object Viewer](https://cloud.google.com/container-registry/docs/access-control#permissions) role. ## Create a Google service account with registry access **Google Cloud Artifact Registry** Administrators can create a service account from the Google Cloud console: 1. Go to the [Create service account](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create?walkthrough_id=iam--create-service-account) page. 2. Select a Cloud project. 3. Enter a service account name and (optional) description. 4. Select **Create and continue**. 5. From the **Role** drop-down under step 2, select **Artifact Registry > Artifact Registry Reader**, then select **Continue**. 6. (Optional) Grant other users and admins access to this service account. 7. Select **Done**. 8. From the project service accounts page, select the three dots menu icon under **Actions** for the service account you just created, then select **Manage keys**. 9. On the **Keys** page, select **Add key**. 10. On the **Create private key** popup, select **JSON** and then **Create**. This triggers a download of a JSON file containing the service account private key and service account details. 11. Base-64 encode the contents of the JSON key file: ```bash #Linux base64 KEY-FILE-NAME > NEW-KEY-FILE-NAME #macOS base64 -i KEY-FILE-NAME -o NEW-KEY-FILE-NAME #Windows Base64.exe -e KEY-FILE-NAME > NEW-KEY-FILE-NAME ``` **Google Cloud Container Registry** Administrators can create a service account from the Google Cloud console: 1. Navigate to the [Create service account](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create?walkthrough_id=iam--create-service-account) page. 2. Select a Cloud project. 3. Enter a service account name and an optional description. 4. Select **Create and continue**. 5. From the **Role** drop-down under step 2, search for and select **Storage Object Viewer**, then select **Continue**. 6. (Optional) Grant other users and admins access to this service account under step 3. 7. Select **Done**. 8. From the project service accounts page, select the three dots menu icon under **Actions** for the service account you just created, then select **Manage keys**. 9. On the **Keys** page, select **Add key**. 10. On the **Create private key** popup, select **JSON** and then **Create**. This triggers a download of a JSON file containing the service account private key and service account details. ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify the service account key type: - Container registry: `_json_key` - Artifact Registry: `_json_key_base64` - **Password**: Specify the JSON key file content. This content is base64-encoded for Artifact Registry. You must remove any line breaks or trailing spaces. For example, `wewogICJ02...9tIgp9Cg==`. - **Registry server**: Specify the container registry hostname, excluding the protocol. For example, `-docker.pkg.dev`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## Managed identities Managed identities offer significant advantages for high performance computing (HPC) environments by enabling granular access control for individual workspace users. Unlike traditional SSH credentials that grant all workspace users access to HPC clusters using the same set of credentials, managed identities ensure each user’s activity is logged under their own credentials. This preservation of user identity is crucial as it naturally inherits the HPC system's fair usage queue policies, mitigates the noisy neighbor problem, and reduces the long wait times associated with First-In-First-Out (FIFO) queues common with shared SSH credentials. Traditional SSH credentials, while simplifying access control to computing resources, result in all user activities on the HPC cluster being logged under the same user credentials. This means all Seqera workspace users have the same access permissions on your HPC cluster, leading to indistinguishable user activities. Managed identities resolve these limitations by allowing administrators to configure a managed identity at the organizational level for access to supported HPC compute environments. This managed identity is selected for authentication similarly to traditional credentials, but contains multiple user credentials each tied to a unique Seqera user. This setup preserves the identity of the user launching workflows on the compute environment and improves traceability and adherence to data access policies. Moreover, with managed identities, users only have the access permissions that their system administrators have granted, minimizing the risk of unauthorized read/write operations in restricted folders. In contrast, shared SSH credentials provide all workspace users with the same access level on the HPC side, which is often more extensive than what an individual user typically needs. By grouping individual user SSH credentials into a single element, managed identities allow administrators to streamline user login and compute environment access while maintaining visibility into data access and compute resource usage for each user. ## Create a managed identity Organization owners can create managed identities at the organization level. A managed identity with user credentials can be used as a credential in HPC clusters for the same provider. 1. From your organization page, select the **Managed identities** tab, then **Add managed identity**. 1. Enter the details of your cluster: - A unique **Cluster name** of your choice using alphanumeric, dash, and underscore characters. - Select a cluster **Provider** from the drop-down. - The fully qualified cluster **Hostname** to be used to connect to the cluster via SSH. This is usually the cluster login node. - The SSH **Port** number for the login connection. The default is port 22. 1. Select **Add cluster**. The new cluster is now listed under your organization's managed identities. Select **Edit** next to a managed identity in the list to edit its details and add user credentials. :::note If the managed identity is already in use on a compute environment, editing its details may lead to errors when using the compute environment. ::: ## Add user credentials Organization owners can grant individual users access to managed identities by adding each user's credentials to the managed identity. You must add user credentials to a managed identity before it can be used in a compute environment. Organization members can add, edit, and delete their own user credentials in a managed identity. :::caution All managed identity users must be a part of the same Linux user group. The group must have access to the HPC compute environment work directory. Set group permissions for the work directory as follows (replace `sharedgroupname` and `` with your group name and work directory): ```bash chgrp -R sharedgroupname chmod -R g+wxs setfacl -Rdm g::rwX ``` These commands change the group ownership of all files and directories in the work directory to `sharedgroupname`, ensure new files inherit the directory's group, and apply default ACL entries to allow the group read, write, and execute permissions for new files and directories. This setup facilitates shared access and consistent permissions management in the directory. ::: 1. From the **Managed identities** tab, select **Edit** next to the cluster in question, then select the **Users** tab. 1. The members of the organization are prepopulated in the **Users** list. Users without credentials are listed with a **Missing** credentials status. Add a user's credentials by selecting **Add credentials** from the user action menu, or the **Add credentials** button. 1. Enter the credential details in the **Add credentials** window: - The member's **Linux username** used to access the cluster. - Paste the contents of the **SSH private key** file for the user's SSH key pair, including the `-----BEGIN OPENSSH PRIVATE KEY-----` and `-----END OPENSSH PRIVATE KEY-----` lines. Ensure no additional lines or spaces are included. - The SSH private key **Passphrase**, if the key has a passphrase. Otherwise, leave this blank. 1. Select **Add credentials**. The Linux username for the user is now populated in the list, and the **Credentials** status is changed to **Added**. Edit existing user credentials by selecting **Edit credentials** from the **Actions** menu next to a user name in the list. --- ## Credentials Overview Configure **workspace credentials** in Seqera Platform to store the access keys and tokens for your [compute environments][compute], [data repositories][data], and [Git hosting services][git]. From version 22.3, you can configure **container registry credentials** to be used by the [Wave container service][wave] to authenticate to private and public container registries like Docker Hub, Google Artifact Registry, Quay, etc. See the **Container registry credentials** section for registry-specific instructions. :::note All credentials are (AES-256) encrypted before secure storage and not exposed in an unencrypted way by any Seqera API. ::: {/* links */} [compute]: ../compute-envs/overview [data]: ../data/data-explorer [git]: ../git/overview [wave]: https://docs.seqera.io/wave/provisioning --- ## Quay container registry credentials From version 22.3, Seqera Platform supports the configuration of credentials for the Nextflow Wave container service to authenticate to private and public container registries. For more information on Wave containers, see the [Nextflow documentation](https://docs.seqera.io/nextflow/wave). :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: For Quay repositories, we recommend using [robot accounts](https://docs.quay.io/glossary/robot-accounts.html) with **Read** access permissions for authentication. **Create a Quay robot account** 1. Sign in to [quay.io](https://quay.io/). 2. From the user or organization view, select the **Robot Accounts** tab. 3. Select **Create Robot Account**. 4. Enter a robot account name. The username for robot accounts have the format `namespace+accountname`, where `namespace` is the user or organization name and `accountname` is your chosen robot account name. 5. Grant the robot account repository **Read** permissions from **Settings > User and Robot Permissions** in the repository view. 6. Select the robot account in your admin panel to retrieve the token value. ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your robot account username. For example, `namespace+accountname`. - **Password**: Specify your robot account access token. For example, `PasswordFromQuayAdminPanel`. - **Registry server**: Specify your container registry hostname. For example, `quay.io`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## SSH credentials SSH public key authentication relies on asymmetric cryptography to generate a public and private key pair. The public key remains on the target (remote) machine, while the private key (and passphrase) is stored in Seqera Platform as a credential. The key pair is used to authenticate a connection with your SSH-enabled environment. To preserve individual user identities by using multiple user SSH credentials to access your HPC compute environments, see [Managed identities](./managed_identities). :::note All credentials are (AES-256) encrypted before secure storage and not exposed in an unencrypted way by any Seqera API. ::: ## Create an SSH key pair To use SSH public key authentication: - The remote system must have a version of SSH installed. This guide assumes the remote system uses OpenSSH. If you're using a different version of SSH, the key generation steps may differ. - The SSH public key must be present on the remote system (usually in `~/.ssh/authorized_keys`). To generate an SSH key pair: 1. From the target machine, open a terminal window and run `ssh-keygen`. 2. Follow the prompts to: - Specify a file path and name (or keep the default). - Specify a passphrase (recommended). 3. Navigate to the target folder (default `/home/user/.ssh/id_rsa`) and open the private key file with a plain text editor. 4. Copy the private key file contents before navigating to Seqera. ## Create an SSH credential in Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: A unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-ssh-creds`. - **Provider**: Select **SSH**. - **SSH private key**: Paste the SSH private key file contents. Include the `-----BEGIN OPENSSH PRIVATE KEY-----` and `-----END OPENSSH PRIVATE KEY-----` lines. - **Passphrase**: The SSH private key passphrase (recommended). If your key pair was created without a passphrase, leave this blank. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## Data Explorer With Data Explorer, you can browse and interact with remote data repositories from organization workspaces in Seqera Platform. It supports AWS S3, Azure Blob Storage, Google Cloud Storage, and Amazon S3-compatible API storage (for example, Cloudflare R2, MinIO, and Oracle Cloud). Access the **Data Explorer** tab from any workspace to view and manage all available data repositories. Data Explorer is also integrated with the pipeline launch form, run detail pages, and Studios. Use these integrations to select input data files and output directories, view the output files of a run, or use files in object storage directly for interactive analysis. ## Participant roles The role assigned to a workspace user affects what functionality is available in Data Explorer. These permissions are listed in the [Participant roles][roles]. - **View**: Can only view contents of cloud storage buckets. Cannot download, upload, or preview. Cannot hide or add buckets. - **Launch**: Can only view contents of cloud storage buckets. Cannot download, upload, or preview. Cannot hide or add buckets. - **Connect**: Can only view contents of cloud storage buckets. Cannot download, upload, or preview. Cannot hide or add buckets. - **Maintain**: Can view download, upload, and preview contents of cloud storage buckets. Can hide and add buckets. - **Admin**: Can view, download, upload, and preview contents of cloud storage buckets. Can hide and add buckets. - **Owner**: Can view, download, upload, and preview contents of cloud storage buckets. Can hide and add buckets. ## Access control Two mechanisms control Data Explorer access: - **Participant roles** determine which Data Explorer actions a workspace user can perform, such as browsing, previewing, downloading, and uploading. See [Participant roles][roles]. - **Credentials** determine which objects those actions can reach. Each data-link uses the credentials you select when you add the data repository to the workspace. The cloud provider permissions attached to those credentials define the scope of Data Explorer access to that repository. To narrow what Data Explorer can do in a bucket, assign that data-link a dedicated credential with a more restrictive cloud provider policy. Sharing one broad credential across compute environments and data repositories gives Data Explorer the full scope of that credential. Data Explorer has no per-bucket or per-workspace setting that disables downloads or uploads while leaving browsing available. Two instance-level [environment variables](../enterprise/configuration/overview#data-features) control Data Explorer availability: - `TOWER_DATA_EXPLORER_ENABLED` enables or disables Data Explorer for every workspace in your Enterprise instance. This is the only way to remove download and upload access completely. - `TOWER_DATA_EXPLORER_CLOUD_DISABLED_WORKSPACES` disables automatic cloud bucket retrieval in the listed workspaces. This is not a download or upload control. Manually added data-links remain usable in those workspaces. :::warning Cross-origin resource sharing (CORS) is not an access-control mechanism. Browsers enforce CORS, and it covers only the upload and multi-file download paths described in [CORS configurations for cloud providers](#cors-configurations-for-cloud-providers). Leaving a bucket's CORS configuration unset does not prevent Data Explorer users from reaching the objects in that bucket. CORS has no effect on access through the Seqera Platform API, the Seqera Platform CLI (`tw`), or your cloud provider's tools. Use credentials and cloud provider access policies to control access to your data. ::: ## Add data repository links Data Explorer lists public and private data repositories. Repositories accessible to your workspace credentials are retrieved automatically; workspace maintainers can also configure repositories manually. - **Retrieve data repositories with workspace credentials** Private data repositories accessible to the credentials defined in your workspace are listed in Data Explorer automatically. The permissions required for your [AWS](../compute-envs/aws-batch#iam-user-creation), [Google Cloud](../compute-envs/google-cloud-batch#iam), [Azure Batch](../compute-envs/azure-batch#storage-account), or high-performance computing (HPC) compute environment credentials allow full Data Explorer functionality. For AWS S3, Data Explorer requires the following minimum IAM permissions: - `s3:ListAllMyBuckets` (on `*`) to auto-discover the buckets accessible to your workspace credentials. - `s3:ListBucket`, `s3:GetBucketLocation`, `s3:GetBucketPolicy`, and `s3:GetBucketAcl` on each bucket you want to browse, to resolve its region and access configuration. - `s3:GetObject` and `s3:PutObject` on the objects in each bucket, to download and upload files. These are a subset of the S3 permissions documented for the [AWS Batch](../compute-envs/aws-batch#required-platform-iam-permissions), [AWS Cloud](../compute-envs/aws-cloud#required-permissions), and [Amazon EKS](../compute-envs/eks#required-platform-iam-permissions) compute environments. For Azure Blob Storage, see the [Azure Cloud data-links permissions](../compute-envs/azure-cloud#data-links). - **Configure individual data repositories manually** Select **Add data repository** from the Data Explorer tab to add a link to an individual repository (or prefix within a cloud bucket). Specify the **Provider**, **Path**, **Name**, **Credentials**, and **Description**, then select **Add**. For public cloud buckets, select **Public** from the **Credentials** drop-down. ## Browse data repositories ![](./_images/data_explorer.png) - **View data repository details** To view details such as the cloud provider, address, and credentials, select the information icon next to a data-link in the Data Explorer list. - **Search and filter data repositories** Search for repositories by name and region (for example, `region:eu-west-2`) in the search field, and filter by provider. - **Hide data repositories from list view** Using checkboxes, choose one or more data repositories, then select the **Hide** icon in the Data Explorer toolbar. To hide repositories individually, select **Hide** from the three dots options menu of a repository in the list. The Data Explorer list filter defaults to **Only visible**. Select **Only hidden** or **All** from the filtering menu to view hidden data repositories in the list. You can unhide a data repository by selecting **Show** from the three dots options menu in the list view. - **View data repository contents** Select a data-link from the Data Explorer list to view the contents of that data repository. From the **View data repository** page, you can browse directories and search for objects by name in a particular directory. The size and path of an object appear in columns to the right of the object name. To view data repository details such as the provider, address, and credentials, select the information icon. - **Preview and download files** From the **View data repository** page, you can preview and download files. Select the download icon in the **Actions** column to download a file directly from the list view. Select a file to open a preview window that includes a **Download** button. File preview is supported for these object types: - Nextflow output files (`.command.*`, `.fusion.*`, and `.exitcode`) - Molecular data using the [Mol* library](https://molstar.org/) - Genome tracks using the [igv.js library](https://igv.org/doc/igvjs/) (annotations, wigs, alignments, and variants) - Text - CSV and TSV - PDF - HTML - Images (JPG, PNG, and SVG) :::note With the exception of genome tracks, the preview file size limit is 10 MB. Files of 10-25 MB can still be downloaded directly. Seqera Enterprise users can increase the default 25 MB file size download limit with `tower.content.max-file-size` in the `tower.yml` [configuration](https://docs.seqera.io/platform-enterprise/enterprise/configuration/overview#data-features) file. Increasing this value can degrade Platform performance. ::: - **Copy object paths** Select the **Path** of an object on the **View data repository** page to copy its absolute path to the clipboard. Use these object paths to specify input data locations during [pipeline launch](../launch/launchpad), add them to a [dataset](../data/datasets) for pipeline input, or when mounting data during Studio creation. ### Isolate view, read, and write permissions to specific data repository paths To isolate pipeline or Studios view, read, and write permissions to a specific **data repository path**, workspace maintainers can create **custom data-links** by manually configuring an individual data repository plus path to a specific folder/directory. This is supported to any level of the data repository path hierarchy, provided it is a folder (also known as a **prefix**). You can **Hide** or **Show** either the base data repository or any related custom data-links on demand in Data Explorer using the **Show/Hide** toggle and the **Show data repositories** filter options: - Only visible (default) - Only hidden - All :::note This customized Data Explorer view displays by default for all workspace users until a workspace maintainer updates or removes the filter. ::: ## Upload files to private data repositories Data Explorer supports single or bulk file uploads to your private data repositories. From the **View data repositories** page, select **Upload** and choose either the **Upload files** or **Upload folder** option. You can also drag and drop files and folders directly into Data Explorer. You can upload up to 300 files at a time via the Platform interface. The file size upload limits reflect the size limitations of the relevant cloud storage provider or data repository integration. These limits apply to cloud providers: - [AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html) - Single `PUT` upload: 5 GiB - Multi-part upload: 5 TiB - [Azure](https://learn.microsoft.com/en-us/rest/api/storageservices/put-blob?tabs=microsoft-entra-id#remarks) - Single `PUT` upload: 5 GiB - Multi-part upload: 4.77 TiB - [Cloudflare R2](https://developers.cloudflare.com/r2/platform/limits/) - Single `PUT` upload: 4.995 GiB - Multi-part upload: 50 TiB - [GCP](https://cloud.google.com/storage/quotas#objects): - Single `PUT` upload: 5 TiB - Multi-part upload: 5 TiB - [MinIO](https://docs.min.io/enterprise/aistor-object-store/reference/aistor-server/thresholds/) - Single `PUT` upload: 5 TiB - Multi-part upload: 50 TiB - [Oracle Cloud](https://docs.oracle.com/en-us/iaas/Content/Object/Tasks/managingobjects_topic-To_upload_objects_to_a_bucket.htm) - Single `PUT` upload: 64 MiB - Multi-part upload: 50 GiB To cancel an upload, select **X** in the upload window. Any files not uploaded display as **Failed**. Files that uploaded successfully are not removed. :::note You must configure cross-origin resource sharing (CORS) for your data repository provider to allow file uploads from Platform. CORS configuration differs for each provider. ::: ## Download multiple files You can download up to 1,000 files using the browser interface, or an unlimited number of files with the auto-generated download script that uses your data repository provider's CLI and credentials. :::note If you use a non-Chromium based browser, such as Safari or Firefox, file paths are concatenated with an underscore (`_`) character and the data repository directory structure is not reproduced locally. For example, the file `s3://example-us-east-1/path/to/files/my-file-1.txt` is saved as `path_to_files_my-file-1.txt`. ::: Open the data repository and navigate to the folder that you want to download files and folders from. By default, you can download the contents of the current directory by choosing **Download current directory**. Alternatively, use checkboxes to select specific files and folders, and select the **Download** button. You can **Download files** via the browser or **Download using code**. The code snippet is specific to the data repository provider you configured. You may be prompted to authenticate during the download process. Refer to your data repository provider's documentation for troubleshooting credential-related issues: - [GCP](https://cloud.google.com/sdk/gcloud/reference/storage) - [AWS](https://docs.aws.amazon.com/cli/latest/reference/s3/) - [Azure](https://learn.microsoft.com/en-us/cli/azure/storage?view=azure-cli-latest) ## CORS configurations for cloud providers Each cloud provider has a specific way to allow Cross-Origin Resource Sharing (CORS) for both uploads and multi-file downloads. CORS enables these browser-based paths, but it is not an access-control mechanism. See [Access control](#access-control) for the mechanisms that restrict access to your data. ### Amazon S3 CORS configuration Apply a [CORS configuration](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html) to enable file uploads and folder downloads from the Seqera Platform to and from specific S3 buckets. The CORS configuration is a JSON file that defines the origins, headers, and methods allowed for resource sharing requests to a bucket. Follow [these AWS instructions](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html) to apply the following CORS configuration to each bucket you want to enable file uploads and folder downloads for: **Seqera Cloud S3 CORS configuration** ```json [ { "AllowedHeaders": ["*"], "AllowedMethods": ["PUT", "POST", "DELETE", "GET"], "AllowedOrigins": ["https://cloud.seqera.io"], "ExposeHeaders": ["ETag"] } ] ``` **Seqera Enterprise S3 CORS configuration** Replace `` with your Seqera Enterprise server URL: ```json [ { "AllowedHeaders": ["*"], "AllowedMethods": ["PUT", "POST", "DELETE", "GET"], "AllowedOrigins": ["https://"], "ExposeHeaders": ["ETag"] } ] ``` ### Azure Blob Storage CORS configuration :::note CORS configuration in Azure Blob Storage is set at the account level. This means that CORS rules for your account apply to every blob in the account. ::: Apply a [CORS configuration](https://learn.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services#enabling-cors-for-azure-storage) to enable file uploads and folder downloads from the Seqera Platform to and from your Azure Blob Storage account. **Seqera Cloud Azure CORS configuration** 1. From the [Azure portal](https://portal.azure.com), go to the **Storage account** you want to configure. 2. Under **Settings** in the left navigation menu, select **Resource sharing (CORS)**. 3. Add a new entry under **Blob service**: - **Allowed origins**: `https://cloud.seqera.io` - **Allowed methods**: `GET,POST,PUT,DELETE,HEAD` - **Allowed headers**: `x-ms-blob-type,content-type` - **Exposed headers**: `x-ms-blob-type` 4. Select **Save** to apply the CORS configuration. **Seqera Enterprise Azure CORS configuration** 1. From the [Azure portal](https://portal.azure.com), go to the Storage account you want to configure. 2. Under **Settings** in the left navigation menu, select **Resource sharing (CORS)**. 3. Add a new entry under **Blob service**: - **Allowed origins**: `https://` - **Allowed methods**: `GET,POST,PUT,DELETE,HEAD` - **Allowed headers**: `x-ms-blob-type,content-type` - **Exposed headers**: `x-ms-blob-type` 4. Select **Save** to apply the CORS configuration. ### Google Cloud Storage CORS configuration Apply a [CORS configuration](https://cloud.google.com/storage/docs/cross-origin#cors-components) to enable file uploads from Seqera to specific GCS buckets. The CORS configuration is a JSON file that defines the origins, headers, and methods allowed for resource sharing requests to a bucket. Follow [these Google instructions](https://cloud.google.com/storage/docs/using-cors#command-line) to apply the following CORS configuration to each bucket you want to enable file uploads for. :::note Google Cloud Storage only supports CORS configuration via gcloud CLI. ::: **Seqera Cloud GCS CORS configuration** ```json { "origin": ["https://cloud.seqera.io"], "method": ["GET", "POST", "PUT", "DELETE", "HEAD"], "responseHeader": ["Content-Type", "Content-Range"], "maxAgeSeconds": 3600 } ``` **Seqera Enterprise GCS CORS configuration** ```json { "origin": ["https://"], "method": ["GET", "POST", "PUT", "DELETE", "HEAD"], "responseHeader": ["Content-Type", "Content-Range"], "maxAgeSeconds": 3600 } ``` [roles]: ../orgs-and-teams/roles --- ## Data lineage :::info Data lineage in Platform is in public preview. It is supported in AWS compute environments. It requires Nextflow v25.04 or later, AWS S3 object storage, and Amazon Simple Queue Service (SQS). ::: :::warning The feature is experimental and subject to change. This page provides the latest configuration recommendations and limitations. ::: Data lineage tracks the full provenance of every pipeline run at both the task and workflow level, including what executed, what data it consumed, and what outputs it produced. Use it to audit results, verify reproducibility, and trace file provenance. ## Why use data lineage Production pipelines generate results that teams need to trust, audit, and reproduce. Data lineage provides a precise, immutable record of how each result was produced. - **Reproducibility**: Every run, task, and output file receives a unique lineage ID (LID), a traversable URI that points to a structured record of what ran. Verify that two runs produced identical results, or identify where they diverged. - **Auditing and compliance**: For teams in regulated industries such as pharma, clinical genomics, and contract research organizations (CROs), lineage provides the audit trail needed for regulatory compliance. Each record captures inputs, outputs, parameters, compute environment, and the user who launched the run. - **Debugging**: When a cached task unexpectedly re-executes, or a pipeline produces an unexpected result, lineage traces backward from any output to all contributing tasks and parameters. Compare two task runs to isolate what changed. - **Broader team access**: Exploring Nextflow lineage previously required CLI access and comfort reading raw JSON. Platform now surfaces lineage data in pipeline run detail pages and Data Explorer. Users can inspect provenance directly. - **Cross-workflow discoverability**: [Workflow output labels][workflow-labels] make output files discoverable across runs. Navigate lineage records by label to find all matching outputs workspace-wide, without knowing which specific run produced a file. ## How data lineage works Nextflow creates a structured JSON record for each entity in your pipeline when lineage is enabled: | Record type | Description | |---|---| | **WorkflowRun** | Full pipeline execution: repository, commit ID, parameters, compute environment, session ID, and Platform context (user, workspace, pipeline) | | **TaskRun** | Individual task execution: script, code checksum, inputs, outputs, container, and dependencies | | **FileOutput** | Output file: path, checksum, size, timestamp, and links back to the task and workflow that produced it | Each record gets a lineage ID (LID), a `lid://` URI that uniquely identifies the entity. ## Enable data lineage To start collecting data lineage for all pipeline runs in your workspace: 1. Open **Settings > Workspace settings**. 2. Select **Lineage**. If you don't see **Lineage** listed, contact your system administrator. 3. Toggle the **Enable lineage by default** on to collect data lineage for all pipeline runs in the workspace or toggle off to require per pipeline launch configuration. Choose either a **Manual** or an **Automatic** configuration for lineage resources: - **Manual**: Define the credentials, region, object storage bucket and path, SQS queue name, and (optionally) SQS queue ARN. - **Automatic**: Define the credentials, region, and (optionally) the object storage bucket and path where lineage data is stored and indexed. This is the default setting. If the storage bucket field is empty, a default bucket is generated for storing lineage data. 4. Once set and enabled, all pipeline runs in the workspace generate data lineage. See [Lineage][workspace-lineage] for more information about the settings. :::danger Updating the lineage settings after pipelines have generated lineage data will result in historic data loss. The lineage index is tied to the lineage storage bucket and path. Changing it makes existing records inaccessible. To avoid data loss when updating the storage location, first copy all existing lineage data to the new bucket and path (for example, `aws s3 cp --recursive s3://old-bucket/path s3://new-bucket/path`), then update the workspace setting. ::: When launching a pipeline in a data-lineage enabled workspace, the **Enable lineage** toggle in the pipeline **Run setup** reflects the **Enable lineage by default** workspace setting. Turn it off to _explicitly exclude_ data lineage for the pipeline run. :::tip Maintain role users and above can toggle lineage on or off when launching a specific pipeline run. ::: ### Additional IAM permissions required If you use existing AWS Batch or AWS Cloud compute environments with custom IAM roles, the following service role policies are required: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ListObjectsInBucket", "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": "arn:aws:s3:::seqera-lineage-" }, { "Sid": "AllObjectActions", "Effect": "Allow", "Action": "s3:*Object", "Resource": "arn:aws:s3:::seqera-lineage-/*" }, { "Sid": "AllowObjectTagging", "Effect": "Allow", "Action": [ "s3:PutObjectTagging", "s3:GetObjectTagging" ], "Resource": "arn:aws:s3:::seqera-lineage-/*" } ] } ``` Platform integration credentials require the following additional permissions: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sqs:CreateQueue", "sqs:GetQueueAttributes", "sqs:SetQueueAttributes", "sqs:GetQueueUrl", "sqs:ReceiveMessage", "sqs:DeleteMessage" ], "Resource": "arn:aws:sqs:*:*:seqera-lineage-*" }, { "Effect": "Allow", "Action": [ "s3:CreateBucket", "s3:GetBucketNotification", "s3:PutBucketNotification", "s3:GetBucketLocation" ], "Resource": "arn:aws:s3:::seqera-lineage-*" } ] } ``` ### Advanced: Experimenting with data lineage To test or troubleshoot data lineage for a _specific pipeline_, add the following to your **Nextflow config file** under **Advanced options** when _adding_ a pipeline to the launchpad. ```groovy lineage.enabled = true lineage.store.location = '' ``` To test for a _single pipeline run_, add the same code to your **Nextflow config file** under **Advanced options** when _launching_ the pipeline run. :::warning If data lineage is defined for a workspace, only that data is displayed in Platform. Any unique _specific pipeline_ or _single pipeline run_ lineage data is only accessible via the AWS S3 console and other related services (such as Amazon Athena). ::: ## Data lineage displayed in Platform ### Workflow run details When a run was executed with lineage enabled, the [run details page][run-details] displays lineage data across the following tabs: - **Run Info**: Shows the lineage ID, lineage labels, and the full Platform context captured at execution time: user, workspace, compute environment, pipeline name, revision, and commit ID. - **Tasks**: Displays the lineage ID and lineage labels for each `TaskRun` alongside existing task data. You can trace any task back to its lineage record. All task file inputs and outputs, and upstream and downstream tasks linked by lineage records, are displayed. - **Inputs**: Lists all input datasets and parameters with file paths, types, and lineage IDs and lineage labels where available. - **Outputs**: Lists all `FileOutput` records linked to the workflow run: output name, file path, type, lineage ID, and lineage labels. Files link directly to [Data Explorer][data-explorer]. ### Data Explorer Output objects from a lineage-enabled run display their LID and any lineage labels when you preview the object in Data Explorer. You can trace any file back to the pipeline run that produced it. ## Search lineage records Use the search bar in the top navigation to find workflow runs, tasks, and output files across every workspace you can access. Search covers only workspaces that have lineage enabled and in which you are a participant. Results are ordered by most recently indexed. An empty query returns the most recent records across all accessible workspaces. As you type, the field suggests keywords and, where supported, values. ### Search syntax A query is a series of space-separated tokens. Each token is either a `qualifier:value` pair or free text. Three rules apply to every qualifier: - A space between tokens is **AND**: `type:file label:qc` returns output files that carry the `qc` label. - A comma inside a value is **OR**: `type:workflow,task` returns workflow runs and tasks. - Repeating a qualifier is **AND**: `label:qc label:validated` returns records carrying both labels. Qualifier names and free text are case-insensitive. Free text matches any substring of the record value. For example, `salmon` matches any record whose value contains `salmon`. :::caution A record has exactly one type and lives in exactly one workspace. Repeating `type:` or `workspace:` returns an empty list because no record can match both values. For example, `type:workflow type:file` requires a record to be both a workflow run and a file. Use the comma form `type:workflow,file` to match either type. ::: ### Qualifiers | Qualifier | Accepts | Description | | --- | --- | --- | | `type:` | `workflow`, `task`, `file` | Restrict results to a record type. Also accepts the internal names `WorkflowRun`, `TaskRun`, and `FileOutput`. | | `label:` | Any label | Records tagged with the label. Covers both Platform labels and Nextflow lineage labels. | | `workspace:` | `organization/workspace` | Scope the search to one or more workspaces by fully qualified name. | | `workspaceId:` | Numeric workspace ID | Numeric alias for `workspace:`. | | `workflow:` | A `WorkflowRun` LID | Scope the search to a single run. Results include the run itself, its tasks, and its published output files. | | `task:` | A `TaskRun` LID | Scope the search to a single task. Results include the task itself and the output files in its work directory. | | Free text | Any string | Case-insensitive substring match on the record value. | The field suggests `workspace:`, `type:`, and `label:` as you type. Enter the remaining qualifiers manually. `workspace:` and `workspaceId:` set the scope of a search rather than filter its results. A query that contains only a workspace still returns that workspace's most recent records. Omit both to search every workspace available to you. Referencing a workspace you do not participate in returns an error rather than an empty list. ### Examples | Query | Returns | | --- | --- | | `type:workflow,task` | Workflow run or task records | | `label:qc,validated` | Records labeled `qc` or `validated` | | `label:qc label:validated` | Records labeled both `qc` and `validated` | | `label:qc,draft label:validated` | Records labeled `validated` and either `qc` or `draft` | | `type:file salmon` | Output files whose value contains `salmon` | | `workspace:acme/dev label:qc` | Records labeled `qc` in the `acme/dev` workspace | | `workspace:acme/dev,acme/prod` | Records in the `acme/dev` or `acme/prod` workspace | | `workspace:acme/dev workspace:acme/prod` | Nothing, because a record lives in one workspace. Use the comma form instead. | | `workflow:lid://abc123` | The run `lid://abc123`, its tasks, and its published output files | | `workflow:lid://abc123 type:task` | The tasks of run `lid://abc123` | | `task:lid://abc123 type:file` | The output files of task `lid://abc123` | :::tip Lineage search is also available through the Platform API. The `GET /lineage/search` endpoint accepts the same query syntax in its `q` parameter and returns paginated results. See the [Platform API reference][platform-api] for the full set of lineage endpoints. ::: ## Lineage labels Assign lineage labels to output files using the `label` directive in your Nextflow process definitions. Labels appear in lineage records. Both Seqera Platform labels and Nextflow lineage labels propagate to lineage records. Seqera Platform excludes resource labels as they relate to underlying compute resources, not the data itself. :::info Nextflow lineage labels are immutable. They are set at execution time and cannot be changed. Seqera Platform labels are mutable. Updating Platform labels after a run completes can produce a mismatch between Platform run labels and lineage labels. This is expected behavior. ::: {/* links */} [workflow-labels]: https://docs.seqera.io/nextflow/workflow#labels [workspace-lineage]: ../orgs-and-teams/workspace-management#lineage [run-details]: ../monitoring/run-details [data-explorer]: data-explorer [platform-api]: https://docs.seqera.io/platform-api --- ## Datasets :::note This feature is only available in organization workspaces. ::: Datasets are CSV (comma-separated values) and TSV (tab-separated values) files stored in, or linked to, a workspace. Use them as pipeline inputs to simplify data management, reduce data-entry errors, and support reproducible analyses. On the datasets screen, you can: - Upload directly or link to an externally hosted dataset. - View the count of pipeline runs in the workspace that have used a specific dataset input. - Apply multiple labels to datasets for easier searching and grouping. - Sort datasets by name, most recently updated, and most recently used. - Hide datasets that are not used in the workspace. - View dataset metadata (created by, last updated, last used). - Edit dataset details (name, description, and labels). - Create new versions of an uploaded dataset. ## Benefits - Datasets reduce errors from manual data entry when you launch pipelines. - Datasets can be generated automatically in response to events (such as new-file notifications from S3 storage). - Datasets can simplify differential data analysis when you use the same pipeline to launch a run for each dataset as it becomes available. ## Format The most commonly used datasets for Nextflow pipelines are sample sheets, where each row contains a sample identifier, the location of that sample's files (such as FASTQ files), and other sample details. For example, [*nf-core/rnaseq*](https://github.com/nf-core/rnaseq) works with input datasets (sample sheets) that include sample names, FASTQ file locations, and strandedness annotations. The Seqera Community Showcase sample dataset for *nf-core/rnaseq* looks like this: **Example rnaseq dataset** |sample |fastq_1 |fastq_2 |strandedness| |-------------------|------------------------------------|---------------------------------------------|------------| |WT_REP1 |s3://nf-core-awsmegatests/rnaseq/...|s3://nf-core-awsmegatests/rnaseq/... |reverse | |WT_REP1 |s3://nf-core-awsmegatests/rnaseq/...|s3://nf-core-awsmegatests/rnaseq/... |reverse | |WT_REP2 |s3://nf-core-awsmegatests/rnaseq/...|s3://nf-core-awsmegatests/rnaseq/... |reverse | |RAP1_UNINDUCED_REP1|s3://nf-core-awsmegatests/rnaseq/...| |reverse | |RAP1_UNINDUCED_REP2|s3://nf-core-awsmegatests/rnaseq/...| |reverse | |RAP1_UNINDUCED_REP2|s3://nf-core-awsmegatests/rnaseq/...| |reverse | |RAP1_IAA_30M_REP1 |s3://nf-core-awsmegatests/rnaseq/...|s3://nf-core-awsmegatests/rnaseq/... |reverse | :::note Use [Data Explorer](../data/data-explorer) to browse for cloud storage objects directly and copy the object paths to be used in your datasets. ::: ### Automation and pipeline schemas Combine datasets, [secrets](../secrets/overview), and [actions](../pipeline-actions/overview) to automate workflows that curate your data and maintain and launch pipelines in response to specific events. See [workflow-automation](https://seqera.io/blog/workflow-automation/) for an example of pipeline workflow automation. For your pipeline to use your dataset as input during runtime, information about the dataset and file format must be included in the relevant parameters of your [pipeline schema](../pipeline-schema/overview). The pipeline schema specifies the accepted dataset file type in the `mimetype` attribute (either `text/csv` or `text/tsv`). ## Dataset file content requirements and validation Datasets can point to files stored in Amazon S3, GitHub, Hugging Face, and other locations. To stage the file paths defined in the dataset, Nextflow requires access to the infrastructure where the files reside, whether on cloud or HPC systems. Add the access keys for data sources that require authentication to your [secrets](../secrets/overview). :::note Seqera doesn't validate your dataset file contents. While datasets can contain static file links, you're responsible for maintaining the access to that data. ::: ## Add a dataset All Seqera user roles have access to the datasets feature in organization workspaces. There are two ways to add a dataset: 1. **Direct upload**: Best when you need immutability and the file is under 10 MB. 2. **Link to an externally hosted file**: Best for large files, but availability and immutability depend on the external hosting service. ### Direct upload 1. In the sidebar navigation, select **Datasets**. 2. Select **Add Dataset** and choose **Upload file**. 3. Complete the **Name** and **Description** fields using information relevant to your dataset. 4. Optionally add one or more **Labels** to your dataset. You can use labels as a search filter but they don't apply to other resources in Seqera. 5. Upload a dataset to your workspace with drag-and-drop or use the **Upload file** file explorer dialog. 6. For datasets that use their first row for column names, customize the dataset view using the **Set first row as header** option. 7. Select **Add**. :::warning The size of the uploaded dataset file cannot exceed 10 MB. ::: ### Link to an externally hosted file 1. In the sidebar navigation, select **Datasets**. 2. Select **Add Dataset** and choose **Link to URL**. 3. Complete the **Name** and **Description** fields using information relevant to your dataset. 4. Optionally add one or more **Labels** to your dataset. You can use labels as a search filter but they don't apply to other resources in Seqera. 5. Copy and paste the dataset URL into the **Dataset URL** field. 6. For datasets that use their first row for column names, customize the dataset view using the **Set first row as header** option. 7. Select **Add**. 8. The dataset appears with a `Linked` badge. ## Manage dataset versions For directly uploaded datasets, Seqera can manage multiple versions. :::note For linked datasets, versioning is unavailable. ::: ### Add a dataset version 1. Select the three dots next to the dataset you want to add a new version for. 2. Select **Add version**. 3. Upload a dataset to your workspace with drag-and-drop or use the system **Upload file** file explorer dialog. 4. For datasets that use their first row for column names, customize the dataset view using the **Set first row as header** option. 5. Select **Add**. :::caution All subsequent versions of a dataset must be the same format (CSV or TSV) as the initial version. ::: ### View dataset versions To see all versions of a dataset, use the **Show** drop-down in the **Preview** tab. Seqera automatically displays a preview of the most recent version and flags it as **(latest)**, unless it is disabled. To preview previous dataset versions, change the version from the **Show** drop-down. The **Created by** and **Created on** values also change. To download a dataset version, select the **Download** icon. To copy a permalink to the dataset, select the **Copy** icon. ### Disable a dataset version To disable one or more dataset versions, select **Disable version**. A disabled version cannot be selected as a pipeline input. If you disable the most recent version, the most recent non-disabled version is flagged as **(latest)**. :::note For compliance reasons, datasets or dataset versions cannot be deleted, they can only be **hidden** or **disabled**, respectively. Once disabled, a dataset version cannot be re-enabled. ::: ## Use a dataset To use a dataset with pipelines added to your workspace: 1. Open any pipeline that contains a pipeline schema from the [Launchpad](../launch/launchpad). 2. Select the input field for the pipeline, removing any default values. 3. Pick the dataset to use as input to your pipeline. :::note The input field drop-down displays only datasets that match the file type specified in the `nextflow_schema.json` of the chosen pipeline. If the schema specifies `"mimetype": "text/csv"`, no TSV datasets are available for use with that pipeline, and vice-versa. If multiple dataset versions exist, the pipeline input always defaults to the **latest** version. ::: ## Manage datasets **View runs** To view a list of all pipeline runs in a workspace that have used a specific dataset input either: - Select the three dots next to a dataset and select **View runs**. - Select the number in the **Runs** column. **Toggle dataset visibility** Select the three dots next to a dataset and select **Mark dataset as hidden** to hide a dataset no longer used in your workspace. To show a hidden dataset, select **Mark dataset as visible**. This filter applies to all workspace users. You can toggle between **Visible**, **Hidden**, and **All** datasets in the **Show** drop-down on the main datasets page. :::note Hidden datasets do not count toward your per workspace quota. ::: **Filter datasets** Filter the list of datasets to only display datasets that match one or more filters defined in the **Search datasets** field. Select the info icon to see the list of available filters. **Edit dataset details** Select the three dots next to a dataset to edit the name, description, and labels associated with a dataset. --- ## Data privacy Seqera Platform orchestrates pipeline execution in your own infrastructure and stores only a limited set of metadata about your runs and tasks. ## Your data Your data stays within your infrastructure. To launch a pipeline with Seqera Platform, you create credentials and a compute environment in a workspace to connect your own infrastructure, such as high-performance computing (HPC) clusters, virtual machines (VMs), or Kubernetes. Seqera Platform uses this configuration to run the pipeline in your infrastructure, the same way the Nextflow CLI does. Seqera Platform does not manipulate your data, and your data is not transferred to the infrastructure where Seqera Platform runs. You can view some data in your storage from the Seqera Platform interface, such as logs and reports generated in a pipeline run. This data is never stored in Seqera Platform infrastructure. ## User deletion When a Seqera Platform user account is deleted: - The user account email is changed to `none@your-domain`. Runs and run metadata associated with the user account display that email address. - The username is changed to `username-`. - All of the user's organization, workspace, and team memberships are deleted. - All of the user's access tokens are deleted from their personal workspace. Enterprise installations also delete the following from the user's personal workspace: - All credentials - All compute environments - All actions created by the user ## Metadata stored by Seqera Platform The Nextflow runtime sends workflow execution metadata to Seqera Platform when: - You launch a pipeline from Seqera Platform. - You run a pipeline with the `-with-tower` command-line option. - You set `tower.enabled` in your Nextflow configuration. ### Workflow metadata Seqera Platform collects and stores the following metadata fields during a workflow execution: | Name | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `command_line` | The command line used to launch the workflow execution | | `commit_id` | The workflow project commit ID at the time of the execution | | `complete` | The workflow execution completion timestamp | | `config_files` | The Nextflow config file path(s) involved in the workflow execution | | `config_text` | The Nextflow config content used for the workflow execution. Note: secrets, such as AWS keys, are stripped and _not_ included in this field | | `container` | The container image name(s) used for the pipeline execution | | `container_engine` | The container engine name used for the pipeline execution | | `duration` | The workflow execution overall duration (wall time) | | `error_message` | The error message reported when the Nextflow execution fails | | `error_report` | The extended error message reported when the workflow execution fails | | `exit_status` | The workflow execution (POSIX) exit code | | `home_dir` | The launching user home directory path | | `launch_dir` | The workflow launching directory path | | `manifest_author` | The workflow project author as defined in the Nextflow config manifest file | | `manifest_default_branch` | The workflow project default Git branch as defined in the Nextflow config manifest file | | `manifest_description` | The workflow project description as defined in the Nextflow config manifest file | | `manifest_gitmodules` | The workflow project Git submodule flag in the Nextflow config manifest file | | `manifest_home_page` | The workflow project Git home page as defined in the Nextflow config manifest file | | `manifest_main_script` | The workflow project main script file name as defined in the Nextflow config manifest file | | `manifest_name` | The workflow project name as defined in the Nextflow config manifest file | | `manifest_nextflow_version` | The workflow project required Nextflow version defined in the Nextflow config manifest file | | `manifest_version` | The workflow project version string as defined in the Nextflow config manifest file | | `nextflow_build` | The build number of the Nextflow runtime used to launch the workflow execution | | `nextflow_timestamp` | The build timestamp of the Nextflow runtime used to launch the workflow execution | | `nextflow_version` | The version string of the Nextflow runtime used to launch the workflow execution | | `params` | The workflow params used to launch the pipeline execution | | `profile` | The workflow config profile string used for the pipeline execution | | `project_dir` | The directory path where the workflow scripts are stored | | `project_name` | The workflow project name | | `repository` | The workflow project repository | | `resume` | The flag set when a resume execution was submitted | | `revision` | The workflow project revision number | | `run_name` | The workflow run name as given by the Nextflow runtime | | `script_file` | The workflow script file path | | `script_id` | The workflow script checksum number | | `script_name` | The workflow script filename | | `session_id` | The workflow execution unique UUID as assigned by the Nextflow runtime | | `start` | The workflow execution start timestamp | | `stats_cached_count` | The number of cached tasks upon completion | | `stats_cached_duration` | The aggregate time of cached tasks upon completion | | `stats_cached_pct` | The percentage of cached tasks upon completion | | `stats_compute_time_fmt` | The overall compute time as a formatted string | | `stats_failed_count` | The number of failed tasks upon completion | | `stats_failed_count_fmt` | The number of failed tasks upon completion as a formatted string | | `stats_failed_duration` | The aggregate time of failed tasks upon completion | | `stats_failed_pct` | The percentage of failed tasks upon completion | | `stats_ignored_count` | The number of ignored tasks upon completion | | `stats_ignored_count_fmt` | The number of ignored tasks upon completion as a formatted string | | `stats_ignored_pct` | The percentage of ignored tasks upon completion | | `stats_succeed_count` | The number of succeeded tasks upon completion | | `stats_succeed_count_fmt` | The number of succeeded tasks upon completion as a formatted string | | `stats_succeed_duration` | The aggregate time of succeeded tasks upon completion | | `stats_succeed_pct` | The percentage of succeeded tasks upon completion | | `status` | The workflow execution status | | `submit` | The workflow execution submission timestamp | | `success` | The flag reporting whether the execution completed successfully | | `user_name` | The POSIX user name that launched the workflow execution | | `work_dir` | The workflow execution scratch directory path | ### Task metadata Seqera Platform collects and stores the following metadata fields for each task: | Name | Description | | -------------- | ---------------------------------------------------------------------------------------------- | | `attempt` | Number of Nextflow execution attempts of the task | | `cloud_zone` | Cloud zone where the task execution was allocated | | `complete` | Task execution completion timestamp | | `container` | Container image name used to execute the task | | `cost` | Estimated task compute cost | | `cpus` | Number of CPUs requested | | `disk` | Amount of disk storage requested | | `duration` | Amount of time for the task to complete | | `env` | Task execution environment variables | | `error_action` | Action applied on task failure | | `executor` | Executor requested for the task execution | | `exit_status` | Task POSIX exit code on completion | | `hash` | Task unique hash code | | `inv_ctxt` | Number of involuntary context switches | | `machine_type` | Cloud virtual machine type | | `memory` | Amount of memory requested | | `module` | Environment module requested | | `name` | Task unique name | | `native_id` | Task unique ID as assigned by the underlying execution platform | | `pcpu` | Percentage of CPU used to compute the task | | `peak_rss` | Peak of real memory during the task execution | | `peak_vmem` | Peak of virtual memory during the task execution | | `pmem` | Percentage of memory used to compute the task | | `price_model` | Cloud price model applied for the task | | `process` | Nextflow process name | | `queue` | Compute queue name requested | | `rchar` | Number of bytes the process read, using any read-like system call from files, pipes, and terminals | | `read_bytes` | Number of bytes the process directly read from disk | | `realtime` | Time required to compute the task | | `rss` | Real memory (resident set) size of the process | | `scratch` | Flag reporting the task was executed in a local scratch path | | `script` | Task command script | | `start` | Task execution start timestamp | | `status` | Task execution status | | `submit` | Task submission timestamp | | `syscr` | Number of read-like system call invocations that the process performed | | `syscw` | Number of write-like system call invocations that the process performed | | `tag` | Nextflow tag associated with the task execution | | `task_id` | Nextflow task ID | | `time` | Task execution timeout requested | | `vmem` | Virtual memory size used by the task execution | | `vol_ctxt` | Number of voluntary context switches | | `wchar` | Number of bytes the process wrote, using any write-like system call | | `workdir` | Task execution work directory | | `write_bytes` | Number of bytes the process wrote to disk | --- ## Source locations The images under this folder are both generated from source files in the Seqera company Google Drive. If you're a Seqera employee, search for the following in Google Drive for the respective source files: - "Seqera reference architecture" for the source file of 'seqera_reference_architecture.png'. - "References, Architectures & Diagrams" for the source file of 'seqera_reference_architecture_aws.png'. --- ## Cert_on_frontend title: "cert_on_frontend" This example assumes deployment on an Amazon Linux 2 AMI. 1. Install NGINX and other required packages: ```yml sudo amazon-linux-extras install nginx1.12 sudo wget -r --no-parent -A 'epel-release-*.rpm' https://dl.fedoraproject.org/pub/epel/7/x86_64/Packages/e/ sudo rpm -Uvh dl.fedoraproject.org/pub/epel/7/x86_64/Packages/e/epel-release-*.rpm sudo yum-config-manager --enable epel* sudo yum repolist all sudo amazon-linux-extras install epel -y ``` 2. Generate a [private certificate and key](https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs). 3. Create a `ssl.conf` file. ```ini server { server_name your.server.name; # replace with your server name root /usr/share/nginx/html; location / { proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Authorization $http_authorization; proxy_pass_header Authorization; proxy_pass http://frontend/; proxy_read_timeout 90; proxy_redirect http://frontend/ https://your.redirect.url/; } error_page 404 /404.html; location = /40x.html { } error_page 500 502 503 504 /50x.html; location = /50x.html { } listen [::]:443 ssl ipv6only=on; listen 443 ssl; ssl_certificate /etc/ssl/testcrt.crt; ssl_certificate_key /etc/ssl/testkey.key; } ``` 4. Make a local copy of the `frontend` container's `/etc/nginx/nginx.conf` file. 5. Add the following to the `server` block of your local `nginx.conf` file: ```ini include /etc/nginx/ssl.conf; ``` 6. Modify the `frontend` container definition in your `docker-compose.yml` file: ```yml frontend: image: cr.seqera.io/frontend:${TAG} networks: - frontend ports: - 8000:80 - 443:443 volumes: - $PWD/nginx.conf:/etc/nginx/nginx.conf - $PWD/ssl.conf:/etc/nginx/ssl.conf - $PWD/cert/testcrt.crt:/etc/ssl/testcrt.crt - $PWD/cert/testkey.key:/etc/ssl/testkey.key restart: always depends_on: - backend ``` --- ## Custom Content Security Policy headers ## Introduction HTTP security headers are an important part of a website's security posture. They protect against different types of attacks including cross-site scripting (XSS), SQL injection, and clickjacking. Object storage is external to Seqera Platform, and read and write access is strictly limited to a selected group of object storage providers. These select providers are explicitly defined in the Content Security Policy (CSP). ## Supported object storage providers Data Explorer can read from, and write to, the following object storage providers by default: - [Amazon S3][aws-s3] - [Google Cloud Object Storage][gcp-os] - [Azure Blob Storage][azure-bs] - [OCI Object Storage][oci-os] - [Cloudflare R2][cloudflare-r2] - [LakeFS Cloud][lakefs] ## Subdomain support If your object storage provider and Seqera deployment share the same subdomain (e.g., `minio.janedoepharma.com` and `platform.janedoepharma.com`), then communication between Seqera and the provider works **without** additional customization. However, if your object storage provider and subdomain don't match, the CSP headers need to be customized. ## Connecting additional providers Accessing new object storage providers in [Data Explorer][data-explorer] requires updating the Content Security Policy to include the domains to access. This is done by setting the `ADDITIONAL_CSP` environment variable for the frontend container. :::note This configuration is only available when using the [Seqera frontend unprivileged](../platform-kubernetes#seqera-frontend-unprivileged) image. If you'd like to use the legacy frontend image, please reach out to Seqera support for further assistance. ::: ### Configuration Set the `ADDITIONAL_CSP` environment variable with a space-separated list of domains to add to the Content Security Policy. For example, to add support for MinIO: ```bash ADDITIONAL_CSP="https://*.min.io" ``` To add multiple domains: ```bash ADDITIONAL_CSP="https://*.min.io https://custom-storage.example.com" ``` :::info If your object storage is accessed on a port other than port **80**, include the port in the address (e.g., `https://myobjectstorage.min.io:9000`). ::: {/* links */} [aws-s3]: https://aws.amazon.com/s3/ [gcp-os]: https://cloud.google.com/storage [azure-bs]: https://azure.microsoft.com/en-us/products/storage/blobs [oci-os]: https://www.oracle.com/cloud/storage/object-storage/ [cloudflare-r2]: https://www.cloudflare.com/developer-platform/products/r2/ [lakefs]: https://lakefs.io/ [data-explorer]: ../../data/data-explorer.md --- ## Custom AWS Batch launch container You can customize your Seqera instance's Nextflow launch container, e.g., to include private CA certificates or compliance software in your Nextflow environment. :::caution Seqera recommends using the default Nextflow launch container wherever possible. Custom launch containers can complicate your Seqera configuration and upgrade process. ::: :::note A custom launch container determines the Nextflow runtime for every run. It takes precedence over per-run version selection. When `TOWER_LAUNCH_CONTAINER` is set, the [**Nextflow version**](../../launch/advanced#nextflow-version) selector is hidden on all compute environments and any selected version has no effect. ::: Specify the path to your custom launch container image with an environment variable: ```env TOWER_LAUNCH_CONTAINER=quay.io/seqeralabs/nf-launcher:j17-23.04.3 ``` **Use an AWS Batch job definition as a Seqera custom launch container** Seqera Platform automatically registers an AWS Batch [job definition](https://docs.aws.amazon.com/batch/latest/userguide/job_definitions.html) to launch pipelines with the required Nextflow runtime. If you need to manage this manually, create a job definition in your AWS Batch environment with the following settings: - `name`: any of your choice - `image`: a custom image based on the Seqera [nf-launcher image](https://quay.io/repository/seqeralabs/nf-launcher) - `vcpus`: at least `1` - `memory`: at least `1000` - `command`: `true` After the job definition is registered, update your Seqera Enterprise configuration with the following (replace `` with the name of the job definition): :::caution The custom launch container is set at the root level, so all executions in your Seqera instance will use this container. If you set an AWS Batch job definition as your custom launch container, launching workflow executions in other cloud provider compute environments will fail. ::: ```env TOWER_LAUNCH_CONTAINER=job-definition:// ``` :::note The repository where your launch container resides must be accessible to the Batch cluster's [ECS Agent](https://docs.aws.amazon.com/batch/latest/userguide/private-registry-auth.html). ::: --- ## Firewall configuration Seqera Platform Cloud ([cloud.seqera.io](https://cloud.seqera.io)) may need to connect to resources within your network, e.g., your storage server. To do so, your firewall must be configured to allow certain IPs to reach your resources. A dynamic list of IPs is kept up-to-date at https://meta.seqera.io. This endpoint returns a JSON object that can be parsed to dynamically adapt your firewall, e.g., in Python with the `requests` package: ```python $ python3 >>> import requests >>> requests.get("https://meta.seqera.io").json() { "cloud.seqera.io": [ "18.135.7.45/32", "18.169.21.18/32", "18.171.4.252/32" ], "licenses.seqera.io": [ "35.176.121.51/32", "35.178.254.247/32" ] } ``` ### DNS allowlist In order for you to access resources such as Fusion tarballs, `nf-xpack` files, Wave cloud containers and other services provided by Seqera, you'll need to add `*.seqera.io.cdn.cloudflare.net` to the allowlist in your network firewall. If DNS wildcards aren't supported by your firewall, you can use the following: - `cloud.seqera.io` - `api.cloud.seqera.io` - `user-data.cloud.seqera.io` - `tower.nf` - `connect.cloud.seqera.io` and its subdomains `*.connect.cloud.seqera.io` - `hub.seqera.io` - `ai.seqera.io` - `ai-api.seqera.io` - `wave.seqera.io` - `community.wave.seqera.io` - `cerbero.seqera.io` - `public.cr.seqera.io` - `auth.cr.seqera.io` - `cr.seqera.io` - `licenses.seqera.io` - `api.multiqc.info` - `fusionfs.seqera.io` - `nf-xpack.seqera.io` - `community-cr-prod.seqera.io` - `fusionfs.seqera.io` - `nf-xpack.seqera.io` - `public-cr-prod.seqera.io` - `wave-cache-prod-cloudflare.seqera.io` - `fusionfs.seqera.io.cdn.cloudflare.net` - `nf-xpack.seqera.io.cdn.cloudflare.net` - `community-cr-prod.seqera.io.cdn.cloudflare.net` - `fusionfs.seqera.io.cdn.cloudflare.net` - `nf-xpack.seqera.io.cdn.cloudflare.net` - `public-cr-prod.seqera.io.cdn.cloudflare.net` - `wave-cache-prod-cloudflare.seqera.io.cdn.cloudflare.net` - `registry.nextflow.io` (required from Nextflow 25.10) :::note Nextflow makes network calls to the `registry.nextflow.io` domain to resolve and download plugins. Even when plugins are already cached locally, Nextflow makes calls to the registry to check for updates and resolve plugin metadata. Ensure this domain is included in your allowlist to prevent pipeline execution failures. ::: If you chose to filter by specific DNS records, please note that new services may be added in the future. :::note If your allowlist is based on IP addresses, allow all of the following IP addresses: https://www.cloudflare.com/ips/. ::: --- ## Manual AWS Batch configuration This page describes how to set up AWS roles and Batch queues manually for the deployment of Nextflow workloads with Seqera Platform. :::tip Manual AWS Batch configuration is only necessary if you don't use Batch Forge. Batch Forge _automatically creates_ the AWS Batch queues required for your workflow executions. ::: Complete the following procedures to configure AWS Batch manually: 1. Create a user policy. 2. Create the instance role policy. 3. Create the AWS Batch service role. 4. Create an EC2 Instance role. 5. Create a Nextflow head job role. 6. Create an EC2 SpotFleet role. 7. Create a launch template. 8. Create the AWS Batch compute environments. 9. Create the AWS Batch queue. ### Create a user policy Create the policy for the user launching Nextflow jobs: 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create policy** from the Policies page. 1. Create a new policy with the following content: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1530313170000", "Effect": "Allow", "Action": [ "batch:CancelJob", "batch:RegisterJobDefinition", "batch:DescribeComputeEnvironments", "batch:DescribeJobDefinitions", "batch:DescribeJobQueues", "batch:DescribeJobs", "batch:ListJobs", "batch:SubmitJob", "batch:TerminateJob" ], "Resource": ["*"] } ] } ``` 1. Save with it the name `seqera-user`. ### Create the instance role policy Create the policy with a role that allows Seqera to submit Batch jobs on your EC2 instances: 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create policy** from the Policies page. 1. Create a new policy with the following content: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "batch:DescribeJobQueues", "batch:CancelJob", "batch:SubmitJob", "batch:ListJobs", "batch:DescribeComputeEnvironments", "batch:TerminateJob", "batch:DescribeJobs", "batch:RegisterJobDefinition", "batch:DescribeJobDefinitions", "batch:TagResource", "ecs:DescribeTasks", "ec2:DescribeInstances", "ec2:DescribeInstanceTypes", "ec2:DescribeInstanceAttribute", "ecs:DescribeContainerInstances", "ec2:DescribeInstanceStatus", "logs:Describe*", "logs:Get*", "logs:List*", "logs:Create*", "logs:Put*", "logs:StartQuery", "logs:StopQuery", "logs:TestMetricFilter", "logs:FilterLogEvents" ], "Resource": "*" } ] } ``` 1. Save it with the name `seqera-batchjob`. ### Create the Batch Service role Create a service role used by AWS Batch to launch EC2 instances on your behalf: 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create role** from the Roles page. 1. Select **AWS service** as the trusted entity type, and **Batch** as the service. 1. On the next page, the `AWSBatchServiceRole` is already attached. No further permissions are needed for this role. 1. Enter `seqera-servicerole` as the role name and add an optional description and tags if needed, then select **Create**. ### Create an EC2 instance role Create a role that controls which AWS resources the EC2 instances launched by AWS Batch can access: 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create role** from the Roles page. 1. Select AWS service as the trusted entity type, EC2 as the service, and _EC2 - Allows EC2 instances to call AWS services on your behalf_ as the use case. 1. Select **Next: Permissions**. Search for the following policies to attach to the role: - `AmazonEC2ContainerServiceforEC2Role` - `AmazonS3FullAccess` (you may want to use a custom policy to allow access only on specific S3 buckets) - `seqera-batchjob` (the instance role policy created above) 1. Enter `seqera-instancerole` as the role name and add an optional description and tags if needed, then select **Create**. ### Create a Nextflow head job role Create an IAM role for the Nextflow head job. This role is attached to the Nextflow head job container and grants it the permissions needed to orchestrate workflow tasks and retrieve task logs from CloudWatch. You specify this role in the **Head Job role** field when creating a manual compute environment in Seqera Platform. :::note This role is separate from the EC2 instance role. The head job role is attached directly to the Nextflow container via the Batch job definition, while the instance role applies to the underlying EC2 instance. ::: 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create policy** from the Policies page. 1. Create a new policy with the following content: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "BatchJobManagement", "Effect": "Allow", "Action": [ "batch:DescribeJobQueues", "batch:CancelJob", "batch:SubmitJob", "batch:ListJobs", "batch:DescribeComputeEnvironments", "batch:TerminateJob", "batch:DescribeJobs", "batch:RegisterJobDefinition", "batch:DescribeJobDefinitions", "batch:TagResource", "ecs:DescribeTasks", "ec2:DescribeInstances", "ec2:DescribeInstanceTypes", "ec2:DescribeInstanceAttribute", "ecs:DescribeContainerInstances", "ec2:DescribeInstanceStatus" ], "Resource": "*" }, { "Sid": "CloudWatchLogsAccess", "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:FilterLogEvents", "logs:GetLogEvents", "logs:ListTagsLogGroup", "logs:PutLogEvents", "logs:StartQuery", "logs:StopQuery", "logs:TestMetricFilter" ], "Resource": "*" } ] } ``` :::note `logs:GetLogEvents` is required for Nextflow to retrieve task stderr from CloudWatch when tasks fail. Without it, error reports for failed tasks show an `AccessDeniedException` instead of the actual task error. ::: 1. Save it with the name `seqera-headjob-policy`. 1. Select **Create role** from the Roles page. Select **AWS service** as the trusted entity type and **Elastic Container Service Task** as the use case. 1. Attach the `seqera-headjob-policy` policy to the role. 1. Enter `seqera-headjob-role` as the role name and select **Create**. ### Create an EC2 SpotFleet role The EC2 SpotFleet role allows you to use Spot instances when you run jobs in AWS Batch. Create a role for the creation and launch of Spot fleets — Spot instances with similar compute capabilities (i.e., vCPUs and RAM): 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create role** from the Roles page. 1. Select AWS service as the trusted entity type, EC2 as the service, and _EC2 - Spot Fleet Tagging_ as the use case. 1. On the next page, the `AmazonEC2SpotFleetTaggingRole` is already attached. No further permissions are needed for this role. 1. Enter `seqera-fleetrole` as the role name and add an optional description and tags if needed, then select **Create**. ### Create a launch template Create a launch template to configure the EC2 instances deployed by Batch jobs: 1. In the [EC2 Console](https://console.aws.amazon.com/ec2/v2/home), select **Create launch template** from the Launch templates page. 1. Scroll down to **Advanced details** and paste the following in the **User data** field: ```bash MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="//" --// Content-Type: text/cloud-config; charset="us-ascii" #cloud-config write_files: - path: /root/custom-ce.sh permissions: 0744 owner: root content: | #!/usr/bin/env bash exec > >(tee /var/log/tower-forge.log|logger -t TowerForge -s 2>/dev/console) 2>&1 ## yum install -q -y jq sed wget unzip nvme-cli lvm2 ## install CloudWatch agent curl -s https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm -o amazon-cloudwatch-agent.rpm rpm -U ./amazon-cloudwatch-agent.rpm rm -f ./amazon-cloudwatch-agent.rpm curl -s https://nf-xpack.seqera.io/amazon-cloudwatch-agent/config-v0.4.json \ # | sed 's/$FORGE_ID//g' \ > /opt/aws/amazon-cloudwatch-agent/bin/config.json /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \ -a fetch-config \ -m ec2 \ -s \ -c file:/opt/aws/amazon-cloudwatch-agent/bin/config.json ## format NVMe storage for Fusion mkdir -p /scratch/fusion NVME_DISKS=($(nvme list | grep 'Amazon EC2 NVMe Instance Storage' | awk '{ print $1 }')) NUM_DISKS=${#NVME_DISKS[@]} if (( NUM_DISKS > 0 )); then if (( NUM_DISKS == 1 )); then mkfs -t xfs ${NVME_DISKS[0]} mount ${NVME_DISKS[0]} /scratch/fusion else pvcreate ${NVME_DISKS[@]} vgcreate scratch_fusion ${NVME_DISKS[@]} lvcreate -l 100%FREE -n volume scratch_fusion mkfs -t xfs /dev/mapper/scratch_fusion-volume mount /dev/mapper/scratch_fusion-volume /scratch/fusion fi fi chmod a+w /scratch/fusion ## ECS configuration mkdir -p /etc/ecs echo ECS_IMAGE_PULL_BEHAVIOR=once >> /etc/ecs/ecs.config echo ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE=true >> /etc/ecs/ecs.config echo ECS_ENABLE_SPOT_INSTANCE_DRAINING=true >> /etc/ecs/ecs.config echo ECS_CONTAINER_CREATE_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_CONTAINER_START_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_CONTAINER_STOP_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_MANIFEST_PULL_TIMEOUT=10m >> /etc/ecs/ecs.config ## stop docker systemctl stop docker ## install AWS CLI curl -s https://nf-xpack.seqera.io/miniconda-awscli/miniconda-25.3.1-awscli-1.40.12.tar.gz \ | tar xz -C / export PATH=$PATH:/home/ec2-user/miniconda/bin ln -s /home/ec2-user/miniconda/bin/aws /usr/bin/aws ## restart docker systemctl start docker systemctl enable --now --no-block ecs ## kernel settings to prevent OOM echo "1258291200" > /proc/sys/vm/dirty_bytes echo "629145600" > /proc/sys/vm/dirty_background_bytes runcmd: - bash /root/custom-ce.sh --//-- ``` 1. To prepend a custom identifier to the CloudWatch log streams for AWS resources created by your manual compute environment, uncomment the `| sed 's/$FORGE_ID//g' \` line and replace `` with your custom identifier. If omitted, `$FORGE_ID` remains as-is in the config. 1. Save the template with the name `seqera-launchtemplate`. 1. In the [EC2 Console](https://console.aws.amazon.com/ec2/v2/home), select **Create launch template** from the Launch templates page. 1. Scroll down to **Advanced details** and paste the following in the **User data** field: ```bash MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="//" --// Content-Type: text/cloud-config; charset="us-ascii" #cloud-config write_files: - path: /root/custom-ce.sh permissions: 0744 owner: root content: | #!/usr/bin/env bash exec > >(tee /var/log/tower-forge.log|logger -t TowerForge -s 2>/dev/console) 2>&1 ## yum install -q -y jq sed wget unzip nvme-cli lvm2 ## install CloudWatch agent curl -s https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm -o amazon-cloudwatch-agent.rpm rpm -U ./amazon-cloudwatch-agent.rpm rm -f ./amazon-cloudwatch-agent.rpm curl -s https://nf-xpack.seqera.io/amazon-cloudwatch-agent/config-v0.4.json \ # | sed 's/$FORGE_ID//g' \ > /opt/aws/amazon-cloudwatch-agent/bin/config.json /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \ -a fetch-config \ -m ec2 \ -s \ -c file:/opt/aws/amazon-cloudwatch-agent/bin/config.json ## ECS configuration mkdir -p /etc/ecs echo ECS_IMAGE_PULL_BEHAVIOR=once >> /etc/ecs/ecs.config echo ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE=true >> /etc/ecs/ecs.config echo ECS_ENABLE_SPOT_INSTANCE_DRAINING=true >> /etc/ecs/ecs.config echo ECS_CONTAINER_CREATE_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_CONTAINER_START_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_CONTAINER_STOP_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_MANIFEST_PULL_TIMEOUT=10m >> /etc/ecs/ecs.config ## stop docker systemctl stop docker ## install AWS CLI curl -s https://nf-xpack.seqera.io/miniconda-awscli/miniconda-25.3.1-awscli-1.40.12.tar.gz \ | tar xz -C / export PATH=$PATH:/home/ec2-user/miniconda/bin ln -s /home/ec2-user/miniconda/bin/aws /usr/bin/aws ## restart docker systemctl start docker systemctl enable --now --no-block ecs ## kernel settings to prevent OOM echo "1258291200" > /proc/sys/vm/dirty_bytes echo "629145600" > /proc/sys/vm/dirty_background_bytes runcmd: - bash /root/custom-ce.sh --//-- ``` 1. To prepend a custom identifier to the CloudWatch log streams for AWS resources created by your manual compute environment, uncomment the `| sed 's/$FORGE_ID//g' \` line and replace `` with your custom identifier. If omitted, `$FORGE_ID` remains as-is in the config. 1. Save the template with the name `seqera-launchtemplate`. ### Create the Batch compute environments :::caution AWS Graviton instances (ARM64 CPU architecture) are not supported in manual compute environments. To use Graviton instances, create your AWS Batch compute environment with [Batch Forge](../../compute-envs/aws-batch#automatic-configuration-of-batch-resources). ::: Nextflow makes use of two job queues during workflow execution: - A head queue to run the Nextflow application - A compute queue where Nextflow will submit job executions While the compute queue can use a compute environment with Spot instances, the head queue requires an on-demand compute environment. If you intend to use an on-demand compute environment for compute jobs, the same job queue can be used for both head and compute. :::note Spot instances can significantly reduce your AWS compute costs, provided your workflow compute tasks can run on ephemeral instances. ::: Create a compute environment for each queue in the AWS Batch console: The head queue requires an on-demand compute environment. Do not select **Use Spot instances** during compute environment creation. 1. In the [Batch Console](https://eu-west-1.console.aws.amazon.com/batch/home), select **Create** on the Compute environments page. 1. Select **Amazon EC2** as the compute environment configuration. :::note Seqera AWS Batch compute environments created with [Batch Forge](../../compute-envs/aws-batch#automatic-configuration-of-batch-resources) support using Fargate for the head job, but manual compute environments must use EC2. ::: 1. Enter a name of your choice, and apply the `seqera-servicerole` and `seqera-instancerole`. 1. When creating the Seqera compute environment, enter the ARN of `seqera-headjob-role` in the **Head Job role** field. 1. Enter vCPU limits and instance types, if needed. :::note To use the same queue for both head and compute tasks, you must assign sufficient resources to your compute environment. ::: 1. Expand **Additional configuration** and select the `seqera-launchtemplate` from the Launch template drop-down. 1. Configure VPCs, subnets, and security groups on the next page as needed. 1. Review your configuration and select **Create compute environment**. Create this compute environment to use Spot instances for your workflow compute tasks. This compute environment cannot be assigned to the Nextflow head job queue. 1. In the [Batch Console](https://eu-west-1.console.aws.amazon.com/batch/home), select **Create** on the Compute environments page. 1. Select **Amazon EC2** as the compute environment configuration. 1. Enter a name of your choice, and apply the `seqera-servicerole` and `seqera-instancerole`. 1. Select **Enable using Spot instances** to use Spot instances and save computing costs. 1. Select the `seqera-fleetrole` and enter vCPU limits and instance types, if needed. 1. Expand **Additional configuration** and select the `seqera-launchtemplate` from the Launch template drop-down. 1. Configure VPCs, subnets, and security groups on the next page as needed. 1. Review your configuration and select **Create compute environment**. ### Create the Batch queue Create a Batch queue to be associated with each compute environment. :::note You only need to create one queue if you intend to use on-demand instances for your workflow compute tasks. Compute environments with Spot instances require separate queues for the head and compute tasks. ::: 1. Go to the [Batch Console](https://eu-west-1.console.aws.amazon.com/batch/home). 2. Create a new queue. 3. Associate the queue with the head queue compute environment created in the previous section. 4. Save it with a name of your choice. 1. Go to the [Batch Console](https://eu-west-1.console.aws.amazon.com/batch/home). 2. Create a new queue. 3. Associate the queue with the compute queue environment created in the previous section. 4. Save it with a name of your choice. Use the AWS resources created on this page to create your [manual AWS Batch compute environment](../../compute-envs/aws-batch#manual-configuration-of-batch-resources). --- ## Azure Batch walkthrough This guide details how to set up more complex Azure Batch compute environments with Seqera Platform. It begins with the simplest possible setup before adding complexity, therefore it is designed to be performed stepwise. The first step indicates how to configure a simple Azure Batch compute environment on Azure and Seqera Platform, however beyond that is not required for most users and is only recommended for those who need to customize their compute environments. :::info Prerequisites - An Azure account with sufficient permissions to create resources. - [Azure CLI][install-azure-cli] - [Seqera Platform CLI][install-seqera-cli] ::: ### Set up Azure Batch In the Azure Portal: 1. Create an Azure Storage account with the default settings. 1. In the Azure Storage account, add a single blob container called `work`. This is the [Nextflow working directory][nextflow-working-directory]. 1. Create a new Azure Batch account. Use Batch Managed for now, with the default settings. Use the same region as your Storage account and attach the Storage account to the Batch account when prompted. 1. On the Azure Batch page, select **Quotas**. 1. Select **Request Quota Increase**. 1. For **Quota Type**, select **Batch**, then select **Next**. 1. Select **Enter Details**, then choose the **Location** as the region of your Batch account. 1. Select **EDv5 Series**. 1. Select **Spot/low-priority vCPUS (all Series)**. 1. Select **Active jobs and job schedules per Batch account**. 1. Select **Pools per Batch account**. Increase each value to a minimum of the following: - **EDv5 Series**: 192 - **Active jobs and job schedules per Batch account**: 100 - **Pools per Batch account**: 50 - **Spot/low-priority vCPUS (all Series)**: 192 ### Set up Seqera Cloud In Seqera Cloud: - Create a new account. - [Create a new organization and workspace][create-org-workspace]. - Add a GitHub credential the workspace to prevent API rate-limiting issues with GitHub. ## Compute environment and pipeline configuration ### Option 1. Azure Batch with Seqera Batch Forge **Behavior**: - Seqera Platform will submit a Nextflow job and task to this pool. - The Nextflow job will execute and submit each task to the same node pool on Azure Batch. - The node pool will autoscale up and down based on the number of waiting tasks. **Advantages**: - Simple to set up. - Low cost. - Autoscales for number of waiting tasks. **Disadvantages**: - The Nextflow job will submit each task to the same node pool on Azure Batch, which can cause bottlenecks. - Because the processes require larger resources than the head node, you often have oversized machines running Nextflow or undersized machines running processes. - Dedicated nodes only. The first configuration is a simple Azure Batch compute environment created with Batch Forge. This environment uses the same Batch pool for both the Nextflow head job and task nodes. First, add the Azure Batch account credentials to Seqera Platform: 1. In the Azure portal, go to the Batch account you created and note the Batch account name and region. 1. Go to the **Keys** tab to find the primary access keys for the Batch account and Storage account. 1. In your Seqera Platform workspace, go to the **Credentials** tab and select **Add credentials**. 1. Enter a credential name such as `azure-keys` and select Azure from the **Provider** drop-down. 1. Enter the Batch account name and key, and Storage account name and key. 1. Select **Create** to save the credentials. Seqera now has the credentials needed to access your Azure Batch and Storage accounts and make the necessary changes. Next, create a compute environment with Batch Forge: 1. Go to the **Compute Environments** tab and select **Add Compute Environment**. 1. Enter a name such as `1-azure-batch-forge`. 1. Select Azure Batch from the **Provider** drop-down. 1. Select your `azure-keys` credentials. 1. Select the **Region** of your Batch account. 1. Select the `az://work` container in your Storage account. 1. For **VMs type**, select `standard_e2ds_v5`. 1. For **VMs count**, select 4. 1. Enable **Autoscale** and **Dispose resources**. 1. All other options can be left default. Select **Create** to save the compute environment. Add the `nextflow-hello` pipeline to your workspace: [Add a pipeline][add-pipeline] from your workspace Launchpad with the following settings: - Select your Azure Batch compute environment from the drop-down. - For **Pipeline to launch**, enter `https://github.com/nextflow-io/hello`. - For **Work directory**, enter a subdirectory in the `az://work` container in your Storage account. Select **Launch** next to the pipeline name in your workspace Launchpad to complete the launch form and launch the workflow. ### Option 2. Use a separate node and head pool on Seqera Platform **Behavior**: - Seqera Platform will submit a Nextflow job and task to the first pool, which uses dedicated VMs. - The Nextflow job will execute and submit each task to the second pool, which uses low-priority VMs. - Both pools will autoscale up and down based on the number of waiting tasks. **Advantages**: - The processes are not bottlenecked by the head node. - You can set the worker nodes to use a different VM size than the head node. - Cheaper nodes for work than for running Nextflow. **Disadvantages**: - More complex to set up. - Still fairly inflexible. - You have to wait a long time for nodes to autoscale up and down in response to the work. This configuration separates head and task nodes into different Batch pools. To create a separate node pool to run all the processes: 1. Create another compute environment in Seqera Platform, exactly as before: - **Name**: `2-azure-batch-low-priority` or similar - **Platform**: Azure Batch - **Credentials**: `azure-keys` - **Region**: As before - **Pipeline work directory**: As before - **VMs type**: `standard_e2ds_v5` - **VMs count**: `4` 1. Note the compute environment ID, which is the first item on the compute environment page. 1. In the Azure Portal, go to the Batch account you created earlier. 1. Go to the **Pools** tab and find the pool called `tower-pool-${id}`, where `${id}` is the ID you made a note of earlier. 1. Select **Scale**. 1. An Autoscale formula is displayed. On the second-to-last line, there will be a line that starts with `$TargetDedicatedNodes`. Change this string to `$TargetLowPriorityNodes`. 1. Select **Evaluate**, then **Save**. You have created a new node pool that uses low-priority VMs, which are cheaper than dedicated VMs. You can now run Nextflow on the first pool, but execute all the processes on the second pool. 1. On the pipeline launch page, duplicate the existing pipeline, but do not save it yet. 1. Under advanced options, add the following configuration block to the `nextflow.config` text input: ```nextflow process.queue = 'tower-pool-${id}' ``` :::info Remember to replace `${id}` with the ID of the compute environment you created earlier! ::: 1. Save the pipeline as `hello-world-low-priority`. Select **Launch** next to the `hello-world-low-priority` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. ### Option 3. Configure the head pool with a hot node **Behavior**: - A "hot" head node is left running. - The head node will run Nextflow as soon as the work is created. - The worker node pool will autoscale up and down based on the number of waiting tasks. **Advantages**: - The latency of the pipeline is reduced. **Disadvantages**: - The always-on head node incurs additional cost. This configuration separates the head and task pools as before and leaves a single head node up and running to make the response time faster. To create the compute environment with a persistent head node: 1. Get the ID of the first node pool (`1-azure-batch-forge`). 1. In the Azure Portal, go to the Batch account you created earlier. 1. Go to the **Pools** tab and find the pool called `tower-pool-${id}`, where `${id}` is the ID you made a note of earlier. 1. Select **Scale**. 1. In the line `targetPoolSize = max(0, min($targetVMs, 4));`, change the `0` to `1`. 1. Select **Evaluate**, then **Save**. The node pool will increase to a minimum of 1 node. Now, when you make adjustments to the pipeline, the head node will not be scaled down. Select **Launch** next to the `hello-world-low-priority` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. With this run, it should respond much faster. The _latency_ of the pipeline has improved, although the overall run time will be similar. This effect is more substantial on larger production pipelines. :::tip If you do not wish to continue paying for the head node, scale the node pool back down by replacing the original autoscale formula (`targetPoolSize = max(0, min($targetVMs, 4))`). You can also delete the compute environment in Platform, which will delete the head node. ::: ### Option 4. Use the Nextflow autopool feature **Behavior**: - Seqera will submit a Nextflow job and task to the first pool, which uses dedicated VMs. - The Nextflow job will create pools in the Azure Batch account based on the pipeline's requirements. - The pools are called `nf-pool-${id}`, where `${id}` is a unique identifier for the pool. - The pools are created with the VM size specified in the Nextflow config. - The pools are created with the autoscale settings specified in the Nextflow config. :::info Nextflow will create a range of pools based on resource sizes and try to reuse them for similar tasks. This means that if you run a process with different CPU, memory, or machineType, it will create a new pool for that process. ::: **Advantages**: - Nextflow handles the creation and management of pools. - You can create flexible pools with the correct VM size and autoscale settings. - The pools are highly configurable via Nextflow configuration. **Disadvantages**: - You may be overly specific and end up with a lot of pools, which can exhaust your quota for the maximum number of pools. - This configuration does not use low-priority nodes. With the autopool feature, Nextflow automatically creates and manages Azure Batch pools based on your pipeline's requirements. To configure your pipeline to use Nextflow autopool: 1. Duplicate the `hello-world-low-priority` pipeline to a new pipeline called `hello-world-autopool`. 1. Update your Nextflow config to use autopool mode: ```groovy process.queue = "auto" process.machineType = "Standard_E*d_v5" azure { batch { autoPoolMode = true allowPoolCreation = true pools { auto { autoscale = true vmCount = 1 maxVmCount = 4 } } } } ``` 3. Save the pipeline. Select **Launch** next to the `hello-world-autopool` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. ### Option 5. Use Nextflow autopool feature with low-priority nodes **Behavior**: - Seqera submits a Nextflow job and task to the first pool, which uses dedicated VMs. - The Nextflow job creates pools in the Azure Batch account based on the pipeline's requirements. - The pools are named `nf-pool-${id}`, where `${id}` is a unique identifier for the pool. - The pools are created with the VM size specified in the Nextflow config. - The pools are created with the autoscale settings specified in the Nextflow config. - These pools use low-priority nodes. It achieves this by modifying the autoscale formula. **Advantages**: - Nextflow handles the creation and management of pools. - You can create flexible pools with the correct VM size and autoscale settings. - This configuration uses low-priority nodes. **Disadvantages**: - Spot and low-priority nodes can be preempted, which can cause the pipeline to fail. To configure your pipeline to use Nextflow autopool with low-priority nodes: 1. Duplicate the `hello-world-autopool` pipeline to a new pipeline called `hello-world-autopool-low-priority`. 1. Update your Nextflow config to use low-priority nodes: ```groovy process.queue = "auto" process.machineType = "Standard_E*d_v5" azure { batch { autoPoolMode = true allowPoolCreation = true pools { auto { autoscale = true vmCount = 1 maxVmCount = 4 } } } } ``` 3. Save the pipeline. Select **Launch** next to the `hello-world-autopool-low-priority` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. ### Option 6. Use Entra authentication **Behavior**: - Seqera authenticates to Azure Batch and Azure Storage using a service principal. - It submits a job and task to the Azure Batch service using the service principal. - The task runs Nextflow, which authenticates to Azure Batch and Azure Storage using the managed identity. - All processes run on the head node as in the first example. **Advantages**: - No keys or short access tokens are exchanged, increasing security. - A service principal can have very granular permissions, so you can grant it only the permissions it needs. - Managed identities can be scoped to a specific resource, so the Nextflow head job has very restricted permissions. - Different managed IDs can have different permissions, so different compute environments can have different scoped permissions. **Disadvantages**: - The setup is quite complicated with room for error. - Errors can be harder to troubleshoot. Seqera can utilize an Azure Entra service principal to authenticate and access Azure Batch for job execution and Azure Storage for data management, and Nextflow can authenticate to Azure services using a managed identity. This method offers enhanced security compared to access keys, but must run on Azure infrastructure. See [Microsoft Entra](https://docs.seqera.io/nextflow/azure#microsoft-entra) in the Nextflow documentation for more information. #### Create a service principal for Seqera to use for authentication 1. [Create an Azure service principal](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal). 1. [Assign roles to the service principal](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal?tabs=current). 1. [Get the Service Principal ID, Tenant ID, and Client Secret](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#option-3-create-a-new-client-secret). 1. [Add to Seqera credentials](../../compute-envs/azure-batch#entra-service-principal-and-managed-identity). In Seqera: 1. Add new credentials with the name `entra-keys` and select the Azure **Provider**. 1. Add the Service Principal ID, Tenant ID and Client Secret. 1. Select **Create** to save the credentials. #### Create a managed identity for Nextflow to use for authentication Back in the Azure Portal: 1. [Create a managed identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp) 1. [Assign the relevant roles to the managed identity](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal?tabs=current). See [Required role assignments](https://docs.seqera.io/nextflow/azure#required-role-assignments) for Nextflow requirements. 1. Note the managed identity client ID for later. 1. In the Azure Portal, go to the Batch account you created earlier. 1. Go to the **Pools** tab and find the pool called `tower-pool-${id}`, where `${id}` is the ID of the head node pool created earlier. 1. Select **Identity**. 1. Select **Add User Assigned Identity**. 1. Select the managed identity created earlier. 1. Select **Add**. Processes running on this pool can now use the managed identity to authenticate to Azure Batch and Storage. In Seqera: 1. Add a new compute environment with the name `entra-mi` and select the Azure Batch **Provider** type. 1. For **Location**, select the same region as your Batch account. 1. For **Config mode**, select Manual. 1. For **Compute pool**, select the pool you added the managed identity to earlier (`tower-pool-${id}`). 1. For **Managed Identity Client ID**, enter the client ID of the managed identity created earlier. Duplicate the `hello-world-autopool-low-priority` pipeline and save it as `hello-world-entra-mi`. Select **Launch** next to the `hello-world-entra-mi` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. The pipeline will run as before, but using the managed identity to authenticate to Azure Batch and Storage. No keys or storage required. :::note You can also use User Subscription mode instead of Batch Managed here, but this is beyond the scope of this tutorial. ::: ### Option 7. Use a node pool attached to a VNet **Behavior**: - Each node is attached to the VNet and uses the security and networking rules of that virtual network subnetwork. - All other behavior is as normal. **Advantages**: - Security can be increased by restricting the virtual network subnet. - Exchange of data can be faster and cheaper than other services. **Disadvantages**: - It requires fairly complicated setup. - If security is too restrictive, it can fail silently and be unable to report the error state. It is common to attach Azure Batch pools to a virtual network. This is useful to connect to other resources in the same VNet or place things behind enhanced security. Seqera Platform does not support this feature directly, so you must manually create an Azure Batch pool. See [Create a Nextflow-compatible Azure Batch pool](../../compute-envs/azure-batch#create-a-nextflow-compatible-azure-batch-pool) to create an Azure Batch pool manually that is compatible with Seqera and Nextflow. Use the following settings: - Name & ID: `3-azure-batch-vnet` - Add the managed identity created earlier as a user-assigned managed identity. - VMs type: `standard_e2ds_v5` - Use the autoscale formula described in the documentation, with a minimum size of 0 and a maximum size of 4. - For Virtual network, create a new virtual network with the default subnet. You can add this to a new resource group here. In practice, you are more likely to connect an Azure Batch Node pool to an existing virtual network that is connected to other resources, such as Seqera Platform or the Azure Storage Account. In this instance, connecting it to a VNet with public internet access will route the network traffic via the virtual network while still allowing you to perform every action. Back in Seqera Platform, add a new Azure Batch compute environment: 1. Add a new compute environment with the name `3-azure-batch-vnet` and select the Azure Batch **Provider** type. 1. For **Location**, select the same region as your Batch account. 1. For **Credentials**, select the service principal credentials. 1. For **Config mode**, select Manual. 1. For **Compute pool**, select the Compute pool name `3-azure-batch-vnet`. 1. For **Managed Identity Client ID**, enter the client ID of the managed identity created earlier. Duplicate the **original** `hellow-world` pipeline and save it as `hello-world-vnet`. Select **Launch** next to the `hello-world-vnet` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. The pipeline runs as before, but it will run on the node pool attached to the VNet. It will resemble a normal Azure Batch pipeline run. Using this technique allows you to run pipelines on Azure Batch with more restrictive networking and security requirements. ### Option 8. Use a node pool attached to a VNet with worker nodes attached to the same VNet **Behavior**: - We use a separate head node pool to run Nextflow, along with automatically created Nextflow autoscale pools to run processes. - Each worker node is attached to the VNet and uses the security and networking rules of that virtual network subnetwork. **Advantages**: - Security can be increased by restricting the virtual network subnet. - Exchange of data can be faster and cheaper than other services. - Additionally, you get the advantages of using worker nodes with autopools. **Disadvantages**: - The set up is very complicated now and errors are likely to occur. - Errors can be hard to troubleshoot. Finally, you can combine some of the previous approaches. Nextflow can create and modify Azure Batch pools based on the pipeline requirements. You can also attach Azure Batch pools to a VNet. Next, attach the worker nodes to the same VNet. To achieve this, the following requirements must be met: - The pipeline must be launched on the node pool attached to the VNet. - The managed identity must be used to authenticate to Azure Batch and Storage. - The managed identity must have permissions to create resources attached to the VNet. - Nextflow creates node pools attached to the VNet. Do the following: 1. Duplicate the `hello-world-entra-mi` pipeline, but modify the compute environment to `3-azure-batch-vnet` and change the pipeline name to `hello-world-vnet`. 1. Check the virtual network string under the pool details in the Azure Portal, under the **Network Configuration** section. The value should be a Subnet ID, such as `/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.Network/virtualNetworks/${vnetName}/subnets/${subnetName}`. Save this value. 1. Change the Nextflow configuration under the **Advanced** tab to include a virtual network with the autopools: ```nextflow process.queue = "auto" process.machineType = "Standard_E*d_v5" azure { batch { autoPoolMode = true allowPoolCreation = true pools { auto { autoscale = true vmCount = 1 maxVmCount = 4 virtualNetwork = '/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.Network/virtualNetworks/${vnetName}/subnets/${subnetName}' } } } } ``` Select **Launch** next to the `hello-world-vnet` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. The pipeline runs as before, but using the managed identity to authenticate to Azure Batch and Storage. It also creates worker pools attached to the VNet. ### Clear up resources Once you have completed setup and workflow execution, you can delete the pipelines and compute environments from Seqera. In Azure, you can delete the Batch account, which will delete all pools, jobs, and tasks. You can then delete the Storage account. If you wish to keep the Azure resources, you can remove each pool within a Batch account and mark any active jobs as terminated to free up any quotas on your Azure Batch account. [install-azure-cli]: https://learn.microsoft.com/en-us/cli/azure/install-azure-cli [install-seqera-cli]: /platform-cli/installation [nextflow-working-directory]: https://docs.seqera.io/nextflow/cache-and-resume#work-directory [create-org-workspace]: ../../getting-started/workspace-setup [add-pipeline]: ../../getting-started/quickstart-demo/add-pipelines#add-from-the-launchpad --- ## Seqera Platform Monitoring Seqera Platform has built-in observability metrics. Enable observability metrics by adding `prometheus` to the `MICRONAUT_ENVIRONMENTS` environment variable. This exposes a Prometheus endpoint at `/prometheus` on the default listen port (e.g., `http://localhost:8080/prometheus`). Combined with infrastructure monitoring tools such as Node Exporter, you can monitor relevant metrics across your deployment. ## Alerting recommendations ### Critical alerts - `jvm_memory_used_bytes{area="heap"}` > 90% of `jvm_memory_max_bytes` - `process_files_open_files` > 90% of `process_files_max_files` - `logback_events_total{level="error"}` rate > threshold - `tower_logs_errors_1minCount` > 0 - HTTP 5xx errors > 5% of total requests - `jdbc_connections_active` > 90% of `jdbc_connections_max` - Any pods in Failed/Unknown state for > 5 minutes ### Warning alerts - `jvm_gc_pause_seconds_max` > 1 second - `jvm_gc_live_data_size_bytes` approaching `jvm_gc_max_data_size_bytes` - Heap usage > 85% of max heap - `executor_queued_tasks` > threshold - Executor utilization > 90% - `hibernate_optimistic_failures_total` rate increasing - `hibernate_query_executions_max_seconds` > 5 seconds - `http_server_requests_seconds` p99 > acceptable latency - Redis cache hit rate < 70% - Hibernate query cache hit rate < 60% - Growing gap between `credits_estimation_workflow_added_total` and `credits_estimation_workflow_ended_total` - `hibernate_sessions_open_total` >> `hibernate_sessions_closed_total` over time ## Quick reference: Metrics by troubleshooting scenario | Issue | Key Metrics to Check | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Slow application response** | `http_server_requests_seconds` (latency), `jvm_gc_pause_seconds_max`, `hibernate_query_executions_max_seconds`, `executor_active_threads` | | **Out of memory errors** | `jvm_memory_used_bytes`, `jvm_gc_pause_seconds`, `jvm_gc_live_data_size_bytes`, `jvm_buffer_memory_used_bytes` | | **Database performance** | `hibernate_query_executions_max_seconds`, `jdbc_connections_active`, `hibernate_transactions_total`, cache hit rates | | **High CPU usage** | `process_cpu_usage`, `system_cpu_usage`, `jvm_threads_live_threads`, `executor_active_threads` | | **Connection exhaustion** | `jdbc_connections_active`, `jdbc_connections_max`, `hibernate_sessions_open_total` vs `hibernate_sessions_closed_total` | | **Cache issues** | Redis hit rate, `hibernate_cache_query_requests_total`, `cache_gets_total`, `cache_evictions_total` | | **Workflow processing delays** | `credits_estimation_workflow_*`, `credits_estimation_task_*`, `executor_queued_tasks`, `tower_logs_errors_*` | | **Thread starvation** | `executor_active_threads`, `executor_queued_tasks`, `jvm_threads_states_threads{state="blocked"}` | | **Memory leaks** | `jvm_memory_used_bytes` trending up, `jvm_gc_live_data_size_bytes` growing, `jvm_classes_loaded_classes` growing | | **GC pressure** | `jvm_gc_pause_seconds_max`, `jvm_gc_memory_promoted_bytes_total`, time in GC vs application time | ## Key metrics to monitor ### Seqera Platform-specific metrics #### Studios metrics | Metric | Description | | ------------------------------------------------ | -------------------------------------| | `data_studio_startup_time_failure_seconds_sum` | Time for failed Studio startups | | `data_studio_startup_time_failure_seconds_count` | Failed Studio startup count | Track Studio startup performance to identify environment provisioning issues. Slow or failing startups impact user productivity. **Average startup time by tool** ```shell sum by (tool) (increase(data_studio_startup_time_success_seconds_sum{app="backend", namespace="$namespace"}[$__rate_interval])) / sum by (tool) (increase(data_studio_startup_time_success_seconds_count{app="backend", namespace="$namespace"}[$__rate_interval])) ``` **Failed startup rate** ```shell rate(data_studio_startup_time_failure_seconds_count{namespace="$namespace"}[$__rate_interval]) ``` #### Error tracking | Metric | Description | | ------------------------------ | ------------------------- | | `tower_logs_errors_10secCount` | Errors in last 10 seconds | | `tower_logs_errors_1minCount` | Errors in last minute | | `tower_logs_errors_5minCount` | Errors in last 5 minutes | Monitor application errors across different time windows. Rolling error counts help identify transient issues versus sustained problems. **Recent error counts** ```shell tower_logs_errors_10secCount{namespace="$namespace"} tower_logs_errors_1minCount{namespace="$namespace"} tower_logs_errors_5minCount{namespace="$namespace"} ``` **Log events by severity level** ```shell rate(logback_events_total{namespace="$namespace"}[$__rate_interval]) ``` ### Infrastructure resources #### CPU usage Monitor container CPU consumption against requested resources to identify capacity issues or inefficient resource allocation. **Backend CPU usage** ```shell rate(container_cpu_usage_seconds_total{container="backend", namespace="$namespace"}[$__rate_interval]) ``` **Compare against requested resources** to determine if the container is over or under-provisioned: ```shell max(kube_pod_container_resource_requests{container="backend", namespace="$namespace", resource="cpu"}) ``` #### Memory usage Track working set memory, committed memory, and limits to prevent OOM conditions. **Backend memory working set** shows actual memory in use: ```shell container_memory_working_set_bytes{container="backend", namespace="$namespace"} ``` **Memory requests and limits** define the bounds for container memory allocation: ```shell max(kube_pod_container_resource_requests{container="backend", namespace="$namespace", resource="memory"}) max(kube_pod_container_resource_limits{container="backend", namespace="$namespace", resource="memory"}) ``` ### HTTP server requests | Metric | Description | | ------------------------------------------ | ------------------------------------------------- | | `http_server_requests_seconds_count` | Total request count by method, status, and URI | | `http_server_requests_seconds_sum` | Total request duration by method, status, and URI | | `http_server_requests_seconds_max` | Maximum request duration | | `http_server_requests_seconds` (quantiles) | Request latency percentiles (p50, p95, p99, p999) | HTTP metrics reveal application throughput, error rates, and latency patterns. These are essential for understanding user-facing performance. **Total request throughput** shows overall API activity: ```shell sum(rate(http_server_requests_seconds_count{app="backend", namespace="$namespace"}[$__rate_interval])) ``` **Error rate (4xx and 5xx responses)** indicates client errors and server failures: ```shell sum(rate(http_server_requests_seconds_count{app="backend", namespace="$namespace", status=~"[45].."}[$__rate_interval])) ``` **Average latency per endpoint** helps identify slow API paths: ```shell sum by (method, uri) (rate(http_server_requests_seconds_sum{app="backend", namespace="$namespace"}[$__rate_interval])) / sum by (method, uri) (rate(http_server_requests_seconds_count{app="backend", namespace="$namespace"}[$__rate_interval])) ``` **Top 10 endpoints by time spent** highlights where server time is consumed for optimization efforts: ```shell topk(10, sum by(method, uri) (rate(http_server_requests_seconds_sum{namespace="$namespace", app="backend"}[$__rate_interval]))) ``` ### HTTP client requests | Metric | Description | | ------------------------------------ | --------------------------------- | | `http_client_requests_seconds_count` | Outbound request count | | `http_client_requests_seconds_sum` | Total outbound request duration | | `http_client_requests_seconds_max` | Maximum outbound request duration | Monitor external API calls and integrations. Slow or failing outbound requests can cascade into application performance issues. **Outbound request rate** ```shell rate(http_client_requests_seconds_count{namespace="$namespace"}[$__rate_interval]) ``` **Average outbound request duration** ```shell rate(http_client_requests_seconds_sum{namespace="$namespace"}[$__rate_interval]) / rate(http_client_requests_seconds_count{namespace="$namespace"}[$__rate_interval]) ``` **Maximum outbound request duration** identifies slow external dependencies: ```shell http_client_requests_seconds_max{namespace="$namespace"} ``` ### JVM memory metrics | Metric | Description | | ------------------------------ | -------------------------------------------------------- | | `jvm_buffer_memory_used_bytes` | Memory used by JVM buffer pools (direct, mapped) | | `jvm_memory_used_bytes` | Amount of used memory by area (heap/non-heap) and region | | `jvm_memory_committed_bytes` | Memory committed for JVM use | | `jvm_memory_max_bytes` | Maximum memory available for memory management | | `jvm_gc_live_data_size_bytes` | Size of long-lived heap memory pool after reclamation | | `jvm_gc_max_data_size_bytes` | Max size of long-lived heap memory pool | JVM memory metrics are critical for preventing OutOfMemoryErrors and identifying memory leaks. Monitor both heap (Java objects) and non-heap (metaspace, code cache) regions. **Heap memory usage** shows memory used for Java objects: ```shell jvm_memory_used_bytes{app="backend", namespace="$namespace", area="heap"} jvm_memory_committed_bytes{app="backend", namespace="$namespace", area="heap"} jvm_memory_max_bytes{app="backend", namespace="$namespace", area="heap"} ``` **Non-heap memory** includes metaspace and code cache: ```shell jvm_memory_used_bytes{app="backend", namespace="$namespace", area="nonheap"} jvm_memory_committed_bytes{app="backend", namespace="$namespace", area="nonheap"} jvm_memory_max_bytes{app="backend", namespace="$namespace", area="nonheap"} ``` **Heap usage percentage** provides a quick health indicator. Alert when this exceeds 85%: ```shell sum(jvm_memory_used_bytes{area="heap"}) / sum(jvm_memory_max_bytes{area="heap"}) * 100 ``` **Direct buffer usage** is important for Netty-based applications. High usage can cause native memory issues: ```shell jvm_buffer_memory_used_bytes{namespace="$namespace", app="backend", id="direct"} jvm_buffer_total_capacity_bytes{namespace="$namespace", app="backend", id="direct"} ``` ### JVM garbage collection | Metric | Description | | ------------------------------------- | ----------------------------------------- | | `jvm_gc_pause_seconds_sum` | Total time spent in GC pauses | | `jvm_gc_pause_seconds_count` | Number of GC pause events | | `jvm_gc_pause_seconds_max` | Maximum GC pause duration | | `jvm_gc_memory_allocated_bytes_total` | Total bytes allocated in young generation | | `jvm_gc_memory_promoted_bytes_total` | Bytes promoted to old generation | Garbage collection metrics reveal memory pressure and its impact on application responsiveness. Long GC pauses cause request latency spikes. **Average GC pause duration** should remain low (under 100ms for most applications): ```shell rate(jvm_gc_pause_seconds_sum{app="backend", namespace="$namespace"}[$__rate_interval]) / rate(jvm_gc_pause_seconds_count{app="backend", namespace="$namespace"}[$__rate_interval]) ``` **Maximum GC pause** identifies worst-case latency impact. Alert if this exceeds 1 second: ```shell jvm_gc_pause_seconds_max{app="backend", namespace="$namespace"} ``` **Live data size after GC** shows long-lived objects. If this grows over time, you may have a memory leak: ```shell jvm_gc_live_data_size_bytes{app="backend", namespace="$namespace"} ``` **Memory allocation and promotion rates** indicate object creation patterns. High promotion rates suggest objects are living longer than expected: ```shell rate(jvm_gc_memory_allocated_bytes_total{app="backend", namespace="$namespace"}[$__rate_interval]) rate(jvm_gc_memory_promoted_bytes_total{app="backend", namespace="$namespace"}[$__rate_interval]) ``` ### JVM threads | Metric | Description | | ---------------------------- | ----------------------------------------------------------------- | | `jvm_threads_live_threads` | Current number of live threads (daemon + non-daemon) | | `jvm_threads_daemon_threads` | Current number of daemon threads | | `jvm_threads_peak_threads` | Peak thread count since JVM start | | `jvm_threads_states_threads` | Thread count by state (runnable, blocked, waiting, timed-waiting) | Thread metrics help identify deadlocks, thread pool exhaustion, and concurrency issues. **Thread counts** show overall thread activity: ```shell jvm_threads_live_threads{app="backend", namespace="$namespace"} jvm_threads_daemon_threads{app="backend", namespace="$namespace"} jvm_threads_peak_threads{app="backend", namespace="$namespace"} ``` **Thread states** reveal blocking issues. High blocked thread counts indicate lock contention: ```shell jvm_threads_states_threads{app="backend", namespace="$namespace"} ``` ### JVM classes | Metric | Description | | ------------------------------------ | -------------------------------------- | | `jvm_classes_loaded_classes` | Currently loaded classes | | `jvm_classes_unloaded_classes_total` | Total classes unloaded since JVM start | Class loading metrics help identify class loader leaks or excessive dynamic class generation. **Loaded classes** should stabilize after startup. Continuous growth may indicate a class loader leak: ```shell jvm_classes_loaded_classes{namespace="$namespace", app="backend"} ``` **Class unload rate** ```shell rate(jvm_classes_unloaded_classes_total{namespace="$namespace", app="backend"}[$__rate_interval]) ``` ### Process metrics | Metric | Description | | ---------------------------- | ------------------------------------ | | `process_cpu_usage` | Recent CPU usage for the JVM process | | `process_cpu_time_ns_total` | Total CPU time used by the JVM | | `process_files_open_files` | Open file descriptor count | | `process_files_max_files` | Maximum file descriptor limit | | `process_uptime_seconds` | JVM uptime | | `process_start_time_seconds` | Process start time (unix epoch) | Process-level metrics provide visibility into resource consumption and system limits. **JVM process CPU usage** ```shell process_cpu_usage{namespace="$namespace"} ``` **Open file descriptors** should be monitored against limits. Exhaustion causes connection failures: ```shell process_files_open_files{namespace="$namespace"} ``` **File descriptor utilization percentage** - alert when this exceeds 90%: ```shell (process_files_open_files{namespace="$namespace"} / process_files_max_files{namespace="$namespace"}) * 100 ``` **Process uptime** helps identify restart events. Low uptime may indicate stability issues: ```shell process_uptime_seconds{namespace="$namespace"} ``` ### System metrics | Metric | Description | | ------------------------ | ------------------------------------- | | `system_cpu_usage` | System-wide CPU usage | | `system_cpu_count` | Number of processors available to JVM | | `system_load_average_1m` | 1-minute load average | System metrics provide host-level context for application performance. **System-wide CPU usage** ```shell system_cpu_usage{namespace="$namespace"} ``` **System load average** should remain below the CPU count for healthy systems: ```shell system_load_average_1m{namespace="$namespace"} ``` **Available CPU count** ```shell system_cpu_count{namespace="$namespace"} ``` ### Executor thread pools | Metric | Description | | -------------------------------- | ---------------------------------------------------------- | | `executor_active_threads` | Currently active threads by pool (io, blocking, scheduled) | | `executor_pool_size_threads` | Current thread pool size | | `executor_pool_max_threads` | Maximum allowed threads in pool | | `executor_queued_tasks` | Tasks queued for execution | | `executor_completed_tasks_total` | Total completed tasks | | `executor_seconds_sum` | Total execution time | Thread pool metrics reveal concurrency bottlenecks. Saturated pools cause request queuing and increased latency. **Thread pool utilization percentage** - high utilization indicates the pool is near capacity: ```shell executor_active_threads{service="backend", namespace="$namespace", name!="scheduled"} / executor_pool_size_threads{service="backend", namespace="$namespace", name!="scheduled"} ``` **Cron scheduled executor utilization** ```shell executor_active_threads{service="cron", namespace="$namespace", name="scheduled"} / executor_pool_size_threads{service="cron", namespace="$namespace", name="scheduled"} ``` **Queued tasks** indicate backlog. Growing queues suggest the pool cannot keep up with demand: ```shell executor_queued_tasks{app="backend", namespace="$namespace"} ``` **Task completion rate** ```shell rate(executor_completed_tasks_total{namespace="$namespace"}[$__rate_interval]) ``` ### Cache metrics | Metric | Description | | ----------------------- | ----------------------------------- | | `cache_size` | Number of entries in cache | | `cache_gets_total` | Cache hits and misses by cache name | | `cache_puts_total` | Cache entries added | | `cache_evictions_total` | Cache eviction count | Cache effectiveness directly impacts database load and response times. Low hit rates indicate caching issues. **Redis cache hit rate** - should be above 70% for effective caching: ```shell avg(irate(redis_keyspace_hits_total{app="platform-redis-exporter"}[$__rate_interval]) / (irate(redis_keyspace_misses_total{app="platform-redis-exporter"}[$__rate_interval]) + irate(redis_keyspace_hits_total{app="platform-redis-exporter"}[$__rate_interval]))) ``` **Cache size by name** ```shell cache_size{namespace="$namespace"} ``` **Cache operation rates** ```shell rate(cache_gets_total{namespace="$namespace"}[$__rate_interval]) rate(cache_puts_total{namespace="$namespace"}[$__rate_interval]) rate(cache_evictions_total{namespace="$namespace"}[$__rate_interval]) ``` ### Hibernate/Database metrics | Metric | Description | | ---------------------------------------- | ---------------------------------------------------- | | `hibernate_sessions_open_total` | Total sessions opened | | `hibernate_sessions_closed_total` | Total sessions closed | | `hibernate_connections_obtained_total` | Database connections obtained | | `hibernate_query_executions_total` | Total queries executed | | `hibernate_query_executions_max_seconds` | Slowest query time | | `hibernate_entities_inserts_total` | Entity insert operations | | `hibernate_entities_updates_total` | Entity update operations | | `hibernate_entities_deletes_total` | Entity delete operations | | `hibernate_entities_loads_total` | Entity load operations | | `hibernate_transactions_total` | Transaction count | | `hibernate_flushes_total` | Session flush count | | `hibernate_optimistic_failures_total` | Optimistic lock failures (StaleObjectStateException) | Database metrics reveal query performance, connection management, and transaction health. **Session operations** - open and closed counts should be roughly equal. A growing gap indicates session leaks: ```shell rate(hibernate_sessions_open_total{app="backend", namespace="$namespace"}[$__rate_interval]) rate(hibernate_sessions_closed_total{app="backend", namespace="$namespace"}[$__rate_interval]) ``` **Connection acquisition rate** ```shell rate(hibernate_connections_obtained_total{app="backend", namespace="$namespace"}[$__rate_interval]) ``` **Query execution rate** ```shell rate(hibernate_query_executions_total{app="backend", namespace="$namespace"}[$__rate_interval]) ``` **Query latency by type** helps identify slow queries for optimization: ```shell sum by (query) (rate(hibernate_query_execution_total_seconds_sum{app="backend", namespace="$namespace"}[$__rate_interval])) / sum by (query) (rate(hibernate_query_execution_total_seconds_count{app="backend", namespace="$namespace"}[$__rate_interval])) ``` **Slowest query time** - alert if this exceeds 5 seconds: ```shell hibernate_query_executions_max_seconds{app="backend", namespace="$namespace"} ``` **Entity operation rates** show database write patterns: ```shell rate(hibernate_entities_inserts_total{app="backend", namespace="$namespace"}[$__rate_interval]) rate(hibernate_entities_updates_total{app="backend", namespace="$namespace"}[$__rate_interval]) rate(hibernate_entities_deletes_total{app="backend", namespace="$namespace"}[$__rate_interval]) rate(hibernate_entities_loads_total{app="backend", namespace="$namespace"}[$__rate_interval]) ``` **Transaction success/failure rate** ```shell sum by (result) (rate(hibernate_transactions_total{app="backend", namespace="$namespace"}[$__rate_interval])) ``` **Optimistic lock failures** indicate concurrent modification conflicts. High rates suggest contention issues: ```shell rate(hibernate_optimistic_failures_total{app="backend", namespace="$namespace"}[$__rate_interval]) ``` ### Connection pool metrics | Metric | Description | | ------------------------- | ---------------------------- | | `jdbc_connections_active` | Active database connections | | `jdbc_connections_max` | Maximum connection pool size | | `jdbc_connections_min` | Minimum connection pool size | | `jdbc_connections_usage` | Connection pool usage | Connection pool metrics prevent connection exhaustion during traffic bursts. **Active connections vs pool limits** - alert when active connections approach the maximum: ```shell sum(jdbc_connections_active{app="backend", namespace="$namespace"}) sum(jdbc_connections_max{app="backend", namespace="$namespace"}) sum(jdbc_connections_min{app="backend", namespace="$namespace"}) sum(jdbc_connections_usage{app="backend", namespace="$namespace"}) ``` ### Hibernate cache metrics Hibernate caching reduces database load. Monitor hit rates to ensure caches are effective. **Query cache hit rate** - should exceed 60%: ```shell sum(increase(hibernate_cache_query_requests_total{app="backend", namespace="$namespace", result="hit"}[$__rate_interval])) / sum(increase(hibernate_cache_query_requests_total{app="backend", namespace="$namespace"}[$__rate_interval])) ``` **Query plan cache hit rate** ```shell sum(increase(hibernate_cache_query_plan_total{app="backend", namespace="$namespace", result="hit"}[$__rate_interval])) / sum(increase(hibernate_cache_query_plan_total{app="backend", namespace="$namespace"}[$__rate_interval])) ``` **Second level cache hit rate by region** ```shell sum by (region) (increase(hibernate_second_level_cache_requests_total{app="backend", namespace="$namespace", result="hit"}[$__rate_interval])) / sum by (region) (increase(hibernate_second_level_cache_requests_total{app="backend", namespace="$namespace"}[$__rate_interval])) ``` ### Logging metrics | Metric | Description | | ---------------------- | ----------------------------------------------------- | | `logback_events_total` | Log events by level (debug, info, warn, error, trace) | Log event metrics provide early warning of application issues. **Error rate** - track error log frequency for anomaly detection: ```shell rate(logback_events_total{level="error"}[5m]) ``` ### Kubernetes health Monitor pod health to catch deployment or infrastructure issues early. **Pods in unhealthy states** ```shell sum by (namespace, pod) (kube_pod_status_phase{phase=~"Pending|Unknown|Failed", namespace!="wave-build"}) > 0 ``` --- ## Legacy Seqera container image registries :::caution The `cr.seqera.io` container registry is the default Seqera Enterprise container image registry from version 22.4. Using the AWS ECR Seqera container registry in existing installations is still supported but will be deprecated on June 1, 2025. ::: Seqera publishes legacy Seqera Enterprise containers to a private Elastic Container Registry (ECR) on AWS. Retrieve them with the following steps: 1. **Provide Seqera with your AWS Account ID.** Supply this value to the Seqera representative managing your onboarding and wait for confirmation that it has been added to the ECR repository policy as an approved Principal. 2. **Retrieve a local copy of the container.** With the `docker compose` deployment method, you must retrieve container copies for local use: 1. Install [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) on the target machine. 2. Configure the AWS CLI with an IAM User with at least these privileges: ```bash ecr:BatchGetImage ecr:GetAuthorizationToken ecr:GetDownloadUrlForLayer ``` 3. Authenticate Docker against the Seqera ECR: ```bash # AWS CLI v2 aws ecr get-login-password --region eu-west-1 | \ docker login --username AWS --password-stdin 195996028523.dkr.ecr.eu-west-1.amazonaws.com # AWS CLI v1 $(aws ecr get-login --registry-ids 195996028523 --region eu-west-1 --no-include-email) ``` 4. Pull the containers to your machine: ```bash export REPOSITORY_URL="195996028523.dkr.ecr.eu-west-1.amazonaws.com/nf-tower-enterprise" export TAG="v22.3.1" docker pull ${REPOSITORY_URL}/backend:${TAG} docker pull ${REPOSITORY_URL}/frontend:${TAG} ``` --- ## Email Configure email-based passwordless authentication for Seqera Platform. This is the default authentication method that allows users to sign in using their email address. Email authentication provides a passwordless login experience where users: 1. Enter their email address on the login page 2. Receive an email containing a temporary access link 3. Select the link to authenticate and access Platform New users are automatically registered on their first login if their email address matches the trusted email patterns. The access link contains a time-limited token that expires after use. :::info Prerequisites Before enabling email authentication, you need: - A configured SMTP server for sending authentication emails - Valid SMTP credentials with permission to send emails ::: ## Configure SMTP Email authentication requires an SMTP server to send login links. Add the following environment variables to your Seqera configuration: | Variable | Description | Required | | :-------------------- | :------------------------------------------------------- | :---------------------------- | | `TOWER_SMTP_HOST` | SMTP server hostname | Yes | | `TOWER_SMTP_PORT` | SMTP server port (e.g., 587 for TLS, 25 for unencrypted) | Yes | | `TOWER_SMTP_USER` | SMTP username | If authentication is required | | `TOWER_SMTP_PASSWORD` | SMTP password | If authentication is required | | `TOWER_SMTP_AUTH` | Set to `true` to enable SMTP authentication | No (default: `false`) | | `TOWER_CONTACT_EMAIL` | Sender email address for authentication emails | Yes | :::tip For development, you can use a local SMTP server like [Mailpit](https://github.com/axllent/mailpit) to test email authentication without sending real emails. ::: ## Restrict access By default, all email addresses are allowed to authenticate. To restrict access to specific email addresses or domains, configure a trusted email list in `tower.yml`: ```yaml tower: trustedEmails: - "*@your-company.com" - "*@partner-company.com" - "external-user@example.com" ``` Pattern matching: - `*@domain.com` - allows all emails from the domain - `*@*.example.com` - allows all subdomains - `user@domain.com` - allows a specific email address - `user+*@domain.com` - allows plus addressing (e.g., `user+tag@domain.com`) When `trustedEmails` is not specified, all email addresses are trusted and can create accounts. See [User access allow list](./overview#user-access-allow-list) for more information. ## Disable email authentication To disable email authentication when other authentication providers (OAuth, OIDC, etc.) are configured, add the following environment variable: | Variable | Description | | :------------------------- | :----------------------------------------- | | `TOWER_AUTH_DISABLE_EMAIL` | Set to `true` to disable email-based login | :::warning Email authentication can only be disabled when at least one other authentication provider is configured. Users will not be able to log in if email authentication is disabled without an alternative authentication method. ::: --- ## GitHub Configure GitHub as a single sign-on (SSO) provider for Seqera Platform. :::info Prerequisites Before you begin, you need: - A GitHub organization - Permission to create OAuth Apps in your organization Ensure you know how to create a GitHub OAuth app. See GitHub's documentation on [creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) for more information. ::: ## Create a GitHub OAuth App 1. In **Profile > Settings > Developer settings**, select **OAuth Apps**. 2. Select **New OAuth App**. 3. Complete the required fields. In the **Authorization callback URL** field, enter `https:///oauth/callback/github` (must be HTTPS) - replace `` with your enterprise installation hostname. 4. Note your **Client ID**. 5. Generate a client secret, then note your **Client secret**. ## Configure Seqera Add the following environment variables to your Seqera configuration: | Variable | Description | | :------- | :---------- | | `TOWER_GITHUB_CLIENT` | The client ID from step 4 | | `TOWER_GITHUB_SECRET` | The client secret from step 5 | ## Restrict access To restrict access to specific email addresses or domains, configure an allow list in `tower.yml`: ```yaml tower: auth: github: allow-list: - "*@your-company.example.com" - "specific-user@another-company.example.net" ``` See [User access allow list](./overview#user-access-allow-list) for more information. --- ## Google Configure Google as a single sign-on (SSO) provider for Seqera Platform. :::info Prerequisites Before you begin, you need: - A Google Cloud account - Permission to create OAuth credentials in the Google Cloud console Ensure you know how to create Google OAuth credentials. See Google's documentation on [setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849) for more information. ::: ## Create Google OAuth credentials 1. In the [Google Cloud console](https://console.developers.google.com), create a new project or select an existing one. 2. Go to **APIs & Services > Credentials**. 3. Select **Create credentials > OAuth client ID**. 4. Select **Web Application** as the application type. 5. Add your redirect URI: `https:///oauth/callback/google` (must be HTTPS) - replace `` with your enterprise installation hostname. 6. Note your **Client ID** and **Client secret**. ## Configure Seqera Add the following environment variables to your Seqera configuration: | Variable | Description | | :------- | :---------- | | `TOWER_GOOGLE_CLIENT` | The client ID from step 6 | | `TOWER_GOOGLE_SECRET` | The client secret from step 6 | ## Restrict access To restrict access to specific email addresses or domains, configure an allow list in `tower.yml`: ```yaml tower: auth: google: allow-list: - "*@your-company.example.com" - "specific-user@another-company.example.net" ``` See [User access allow list](./overview#user-access-allow-list) for more information. --- ## IdP claim mapping For IdP-delegated teams to evaluate correctly at login, the tokens your identity provider sends to Platform must include a `groups` claim. This page lists the per-IdP configuration steps for the supported providers. Enterprise reads the IdP's tokens directly. ## OIDC providers ### Okta 1. In the Okta administrator console, open **Security**, then **API**, then **Authorization Servers**. 2. Select the authorization server backing your Seqera application (typically `default`). 3. Open **Claims**, then **Add claim**. 4. Set: - **Name**: `groups` - **Include in token type**: **ID Token** (and **Access Token** if you use access tokens for downstream services) - **Value type**: **Groups** - **Filter**: Match the groups you want exposed (`Matches regex .*` to expose all of them). 5. Select **Save**. :::note Okta only includes the `groups` claim in the token when the client requests a matching scope. Add `groups` to the scopes Seqera requests by setting `TOWER_OIDC_SCOPES=openid,email,profile,groups`. See [OpenID Connect](../oidc#configure-seqera) for details. ::: ### Entra ID Entra ID requires an app-registration change and attention to the format Entra emits. 1. In the Azure portal, open the app registration that backs your Platform connection. 2. Open **Token configuration**, then **Add groups claim**. 3. Select the group types you want emitted (typically **Security groups**). 4. Under **Customize token properties by type**, choose whether to emit **Group ID** (object GUIDs) or **sAMAccountName** (display names where supported). 5. Confirm via Entra ID's **Token Preview** that a sample sign-in includes the `groups` claim. :::caution With **Group ID** selected, Entra ID emits group object GUIDs. You have two options: - Use the GUID values directly as the catalog identifier and the **IdP Group** field on each team. This works but makes the catalog harder to read. - Configure Entra ID to emit display names instead. Set **sAMAccountName** as the source where supported, or post-process via a custom claims policy. The GUID and the display name don't both flow at the same time, so pick one approach for your tenant and stick with it. ::: ## Verify the mapping After saving the IdP changes, confirm the claim is reaching Platform:: 1. Sign in to Platform as a test user via SSO. 2. In your Platform instance logs, look for the SSO callback log line. It records the full claim set received. 3. Confirm the `groups` claim is present and contains the expected group identifiers. :::caution An absent or empty `groups` claim is treated as "no groups": the user is removed from every team they joined through delegation. Only a malformed `groups` claim (a value that is not a list) is ignored and leaves existing memberships unchanged. ::: --- ## Manage your IdP group catalog Platform maintains a per-organization catalog of identity provider (IdP) groups. Groups appear in the catalog as soon as they're synced from the IdP or added manually. They don't depend on any user having signed in. Use the table below to choose the path that fits your IdP. | IdP | Recommended path | Setup guide | |-----|------------------|-------------| | Okta | SCIM push | [SCIM provisioning with Okta](./scim-okta) | | Entra ID | SCIM push | [SCIM provisioning with Entra ID](./scim-entra-id) | :::info[Other identity providers] SCIM-based provisioning is supported for Okta and Microsoft Entra ID. With these providers, group membership syncs automatically, including lifecycle events (joiners, movers, leavers). Other OIDC or SAML identity providers can authenticate users through Auth0, but group membership doesn't sync automatically. An admin must update memberships in Seqera as users join, move, or leave. If you use Google Workspace, Keycloak, Ping, OneLogin, or another OIDC/SAML provider and want to delegate team membership, contact your Seqera account team to discuss your setup. ::: ## SCIM push If your IdP supports SCIM 2.0 group provisioning, Platform exposes a per-organization SCIM endpoint that the IdP can push to. Group create, rename, and delete events flow through automatically, and the catalog stays in sync without administrator intervention. To set up SCIM: 1. In Platform, open **Organization settings > Group mapping**. 2. Copy the **SCIM endpoint URL** and the generated **bearer token**. 3. Configure these values in your IdP's SCIM provisioning settings. 4. Trigger an initial sync from the IdP or wait until the IdP performs an scheduled sync. After the sync completes, the catalog displays every group your IdP shared, and the **Linked team** drop-down on **Group mapping > IdP groups** is populated. :::caution Treat the SCIM bearer token like a password. It grants write access to your organization's group catalog. If the token is compromised, rotate it immediately using **Rotate** in the **Group mapping** panel. The previous token is revoked atomically. ::: ## Manual entry To add a group manually: 1. In Platform, open **Organization settings > Group mapping**. 2. Select **Add group manually**. 3. Enter the group identifier exactly as it appears in your IdP's `groups` claim. 4. Select **Save**. To delete a manually-entered group, select **Delete** on its row. If any delegated team references the group, its members are immediately purged. :::info A manually-entered group is automatically promoted to SCIM-managed if your IdP later pushes the same group via SCIM. The promotion happens in place. The catalog row is reused, and any delegated teams that reference it continue to work without interruption. After promotion, the row's lifecycle is fully driven by SCIM, and the manual **Delete** action is no longer available. The row is removed when your IdP issues a SCIM `DELETE`. ::: ## Remove catalog entry When a group is removed from the catalog, by SCIM `DELETE`, manual deletion, or IdP-side rename detection, the following happens asynchronously: - The catalog row is removed. - Every delegated team that referenced the group has its delegation-driven members purged. The team's other settings (name, workspace assignments, role) are preserved. - If a group is deleted on the IdP side, the team's membership can be reset by setting its **IdP Group** field to a different group, or clearing the field to convert the team back to manual management. ## Multi-organization deployments On Enterprise instances that host more than one organization, group display names must be unique across all organizations on the instance. If you add a group that conflicts with another organization's catalog entry, it will fail with a `409 Conflict`. See [Multi-organization routing](../multi-org-routing) for more information. --- ## SCIM provisioning with Entra ID Configure Microsoft Entra ID (formerly Azure AD) to push your tenant's groups to Platform over SCIM 2.0. Once provisioning is enabled, the groups you assign to your Seqera Enterprise application appear in Platform's IdP group catalog and stay in sync with renames, additions, and deletions automatically. :::info[**Prerequisites**]{#prerequisites} You will need the following to get started: - An Entra ID enterprise application configured as your Platform SSO connection. See [Entra ID authentication](../../oidc). - Organization owner access to your Platform organization. - Administrator access to your Entra ID tenant with permission to manage application provisioning. ::: ## Get the Platform SCIM connection details 1. In Platform, open **Organization settings > Group mapping**. 2. Copy the **SCIM endpoint URL**. It has the form `https:///orgs//scim/v2`. 3. Select **Generate token** to issue a SCIM bearer token. Copy your bearer token immediately. You can't view it again after closing the dialog. :::caution The bearer token grants write access to your group catalog. Store it in a secrets manager and rotate it on a schedule. To rotate, generate a new token in Seqera and update Entra ID's configuration. The previous token is revoked when the new token is issued. ::: ## Enable provisioning in Entra ID 1. Sign in to the Azure portal and open **Entra ID**, then **Enterprise applications**. 2. Select the application that fronts your Platform SSO connection. 3. Open **Provisioning** and select **Get started**. 4. Set **Provisioning Mode** to **Automatic**. 5. Under **Admin Credentials**, provide: - **Tenant URL**: The Platform SCIM endpoint URL from the previous section. - **Secret Token**: The Platform bearer token from the previous section. 6. Select **Test Connection**. Entra ID should report success. 7. Select **Save**. ## Scope and start provisioning 1. With **Provisioning** still open, expand **Settings**. 2. Set **Scope** to **Sync only assigned users and groups**. 3. Save, then set **Provisioning Status** to **On**. 4. Return to the application's **Users and groups** tab and assign the groups you want Platform to receive. Entra ID runs an initial cycle within minutes and then syncs incrementally every ~40 minutes. ## Group display names vs. object IDs :::caution By default, Entra ID emits group **object GUIDs** in the `groups` claim, not display names. There are two options: - **Recommended**: Configure Entra ID to emit display names. In the application's **Token configuration**, add a **groups claim** and select **sAMAccountName** as the source where supported, or use a custom claims policy. This makes catalog entries and audit logs human-readable. - **Alternative**: Accept the default GUID emission. Use the GUID as the **IdP Group** value on each team. This works but makes the catalog harder to read. Pick one approach for your tenant and use it consistently. The GUID and the display name don't both flow at the same time. ::: ## Verify in Platform 1. In Platform, open **Organization settings > Group mapping**. 2. Select **Refresh**. The assigned Entra ID groups should appear in the catalog list after the first provisioning cycle. 3. The **Linked team** drop-down is now populated with the synced groups. If groups don't appear, open the **Provisioning logs** for the application in Entra ID and review any failed actions. ## Group rename and delete behavior Renames and deletes propagate automatically through SCIM: - **Rename**: The next provisioning cycle updates the catalog row's display name. Delegated teams that reference the group continue to work without interruption. - **Delete**: Entra ID issues a SCIM `DELETE` for the group, or removes the assignment from the enterprise application. Seqera removes the catalog row and synchronously purges members from any delegated team that referenced it. The affected teams remain in place with empty membership and an orphaned-team warning. ## Troubleshooting For SCIM provisioning issues, see [SCIM provisioning](../../../../../troubleshooting_and_faqs/authentication#scim-provisioning). --- ## SCIM provisioning with Okta Configure Okta to push your organization's groups to Platform over SCIM 2.0. Once provisioning is enabled, your Okta group directory appears in Seqera's IdP group catalog and stays in sync with renames, additions, and deletions automatically. :::info[**Prerequisites**]{#prerequisites} You will need the following to get started: - An Okta application configured as your Platform SSO connection. See [Okta authentication](../../oidc). - Organization owner access to your Platform organization. - Administrator access to your Okta tenant. ::: ## Get the Seqera SCIM connection details 1. In Platform, open **Organization settings > Group mapping**. 2. Copy the **SCIM endpoint URL**. It has the form `https:///api/orgs//scim/v2`. 3. Select **Generate token** to issue a SCIM bearer token. Copy it immediately. You can't view it again after closing the dialog. :::caution The bearer token grants write access to your group catalog. Store it in a secrets manager and rotate it on a schedule. To rotate, generate a new token in Seqera and update Okta's configuration. The previous token is revoked when the new token is issued. ::: ## Enable provisioning in Okta 1. Sign in to your Okta administrator console. 2. Open **Applications**, then select the application that fronts your Seqera SSO connection. 3. Open the **Provisioning** tab and select **Configure API integration**. 4. Select **Enable API integration** and provide: - **Base URL**: The Platform SCIM endpoint URL from the previous section, with `/Groups` removed (Okta appends the resource path). - **API token**: The Platform bearer token from the previous section. 5. Select **Test API Credentials**. Okta should report a successful connection. 6. Select **Save**. ## Enable group push 1. With the application still open, switch to the **Push Groups** tab. 2. Select **Push Groups**, then **Find groups by name** (or **By rule** for dynamic group sets). 3. Select the Okta groups you want available in Platform. 4. Confirm the push. Okta sends an initial provisioning batch. ## Verify in Platform 1. In Platform, open **Organization settings > Group mapping**. 2. Select **Refresh**. The pushed Okta groups should appear in the catalog list within a few seconds. 3. The **Linked team** drop-down is now populated with the synced groups. If groups don't appear, check the **Push Groups** status column in Okta for error details, and confirm that the **Provisioning** tab shows **Push Groups: ON**. ## Group rename and delete behavior Renames and deletes propagate automatically: - **Rename**: The next SCIM push updates the catalog row's display name. Delegated teams that reference the group continue to work without interruption. - **Delete**: Okta issues a SCIM `DELETE` for the group. Seqera removes the catalog row and synchronously purges members from any delegated team that referenced it. The affected teams remain in place with empty membership and an orphaned-team warning. ## Troubleshooting For SCIM provisioning issues, see [SCIM provisioning](../../../../../troubleshooting_and_faqs/authentication#scim-provisioning). --- ## Multi-organization routing Cloud Pro tokens carry an `org_id` claim that scopes every IdP delegation evaluation to a single organization. Enterprise SSO tokens don't carry such a claim. Platform routes by deployment topology and relies on a cross-organization uniqueness invariant on group display names. The rules on this page determine how Platform resolves a user's groups claim against each organization's catalog. ## Topology decision table | Topology | How users are routed | Group-name uniqueness | |----------|----------------------|------------------------| | **No SSO** | Not applicable. | Not applicable. | | **Single organization** | Trivially scoped to the single organization. | Not enforced; there is no second organization to collide with. | | **Multi-organization** | Evaluated against every organization the user is a member of. | **Enforced**. Group display names must be unique across all organizations on the instance. | ## The uniqueness invariant In a multi-organization Enterprise instance, when an administrator adds a group to the catalog (manually or through SCIM), Seqera checks the group's display name against every other organization's catalog on the instance. If another organization already has a row with the same display name, the operation fails: - **Manual add**: The form rejects the value with a `409 Conflict` and a message naming the conflicting organization. - **SCIM push**: Platform's SCIM endpoint returns `409 Conflict` for that group. The IdP's provisioning agent retries and surfaces the error in its administrator console. This is the mechanism that lets Seqera resolve a `groups` claim back to a specific organization's catalog at login. Without it, two organizations could both have a group called `engineering` and Platform couldn't determine which delegation rules to apply. :::info On Cloud Pro, the uniqueness check is skipped because the `org_id` claim disambiguates without it. ::: ## Resolving a conflict If a group-name conflict prevents you from adding a group: - Coordinate with the conflicting organization's owner to rename one of the groups in the upstream IdP. The rename propagates via SCIM (or is re-entered manually), and the catalog row becomes available again. - If renaming isn't possible, namespace the group in your IdP — for example, prefix the group with the organization's name (`acme-engineering` instead of `engineering`). There is no per-organization override. Uniqueness is enforced at the instance level. ## Cross-organization users When a user belongs to multiple organizations on the same instance, Platform evaluates their `groups` claim against every organization's delegated teams at login. Because group display names are unique instance-wide, each claim value maps unambiguously to one organization's catalog, and the user joins the matching teams in every organization where they apply. ## Operator guidance for new instances For new multi-organization Enterprise deployments, establish a naming convention for IdP groups before onboarding the first organization. Common patterns: - **Organization prefix**: `acme-eng-admins`, `beta-eng-admins`. Easy to read; explicit ownership. - **Reverse-DNS namespace**: `io.acme.eng.admins`. Compact; aligns with IdP best practice. - **Functional grouping with project codes**: `eng-NF-admins` where `NF` denotes a project. Useful when groups span organizations but require unique names. Document the convention in your organization onboarding checklist so administrators avoid `409 Conflict` errors when they configure delegation. --- ## IdP delegation overview IdP delegation lets you map a Seqera team to a group in your identity provider (IdP). After you delegate a team, the IdP becomes the sole authority for membership. Every time a user signs in through SSO, Seqera reads the `groups` claim from their token and updates the user's delegated-team memberships to match. IdP delegation requires a working OIDC SSO connection. To set up SSO before configuring delegation, see [Authentication](../overview). ## How it works Delegation has three components that you configure once per organization. ### The IdP group catalog Seqera maintains a per-organization catalog of IdP groups. The catalog populates the **IdP Group** drop-down on the group mapping page. Organization owners can select an IdP group when delegating a team. Groups appear in the catalog as soon as they're synced or entered, before any user has signed in. The catalog is populated in one of two ways: - **SCIM 2.0 push**: Your IdP pushes its group directory to Seqera's per-organization SCIM endpoint. Used with Okta and Entra ID. - **Manual entry**: For IdPs that don't support SCIM group sync (Google Workspace, Keycloak), an organization owner enters group identifiers in the catalog UI. A manually-entered group is automatically promoted to SCIM-managed if your IdP later pushes the same group. See [Manage your IdP group catalog](./group-catalog/overview). ### The `groups` claim At login, Seqera reads the user's IdP claims to decide which delegated teams they belong to. The `groups` claim must be present in the token and must contain the same group identifiers as your catalog. Unlike Cloud Pro, which authenticates through Auth0 and requires a connection-level mapping, Enterprise reads the IdP's tokens directly. Configure the claim at the IdP itself. See [IdP claim mapping](./claim-mapping). ### The Team's `IdP Group` field When an organization owner sets the **IdP Group** field on a team, the team becomes delegated. Delegation has the following effects: - The team is labeled **Managed in IdP** in the teams list. - The **Add member** and **Remove member** controls are hidden. - The team cannot be deleted until the **IdP groups** field is cleared. - The team's name, description, avatar, and workspace assignments remain editable. The same IdP group can only be assigned to a single team. Each team can reference exactly one IdP group. See [Delegate a team to an IdP group](../../../../orgs-and-teams/teams#delegate-a-team-to-an-idp-group). When a user logs in via SSO, Seqera evaluates their group claims and adds them to any delegated teams that match. The user must already exist in the Platform, but does not need to be a member of the organization that owns the team. :::info In deployments with more than one organization, a user does not need to be an existing member of an organization to be added to a delegated team in that organization. When their IdP group claim matches a delegated team, the user is added to both the team and its owning organization automatically. ::: ## What happens at login On every SSO login, Seqera evaluates each delegated team in your organization against the user's `groups` claim: - **Match found**: The user is added to the team if they aren't already a member, and gains the workspace access the team grants. - **No match and the user was previously a member**: The user is removed from the team, and the workspace access the team granted is revoked. - **No match and the user was never a delegation-driven member**: no change. Manual assignments to non-delegated teams are never touched by this evaluation. Users added manually to a team with no **IdP Group** value keep their membership regardless of their IdP claims. An **absent or empty** `groups` claim is treated as "member of no groups": the user is removed from every team they joined through delegation. Only a **malformed** `groups` claim (a value that is not a list) is ignored, leaving existing memberships unchanged. ## Multi-organization deployments Cloud Pro tokens carry an `org_id` claim that scopes evaluation to a single organization. Enterprise SSO tokens do not, so the platform routes by deployment topology and enforces a cross-organization uniqueness invariant on group display names. See [Multi-organization routing](./multi-org-routing) for the rules and conflict resolution. ## Audit trail Delegation activity is recorded in the [audit log](../../../../monitoring/audit-logs): - Setting, changing, or clearing the **IdP Group** field on a team produces a `team_updated` event with the previous and new value of `idpGroup`. - Each delegation-driven membership change at login produces a `team_member_added` or `team_member_removed` event. - Group catalog operations produce `idp_group_created`, `idp_group_updated`, and `idp_group_deleted` events so you can correlate catalog changes with downstream membership changes. - SCIM bearer token lifecycle operations produce `scim_token_created` and `scim_token_updated` events (the latter covers rotation and revocation), so changes to the token used against Seqera's SCIM endpoint are captured in the audit trail. SCIM-originated entries (operations performed by your IdP's provisioning agent against Seqera's SCIM endpoint) are attributed to a **System** operator rather than to a named administrator, because they authenticate with a SCIM bearer token. To correlate a SCIM event with a specific administrator action, match by `displayName` and timestamp against your IdP's provisioning logs. ## Set up delegation Complete these steps in order. Each step links to a dedicated guide. 1. [Configure authentication](../overview) for your Enterprise instance if you haven't already. 2. [Populate the IdP group catalog](./group-catalog/overview). Choose SCIM push or manual entry depending on your IdP. 3. [Configure the IdP to emit the `groups` claim](./claim-mapping) so it reaches Seqera at login. 4. If your instance hosts multiple organizations, review the [multi-organization routing rules](./multi-org-routing). 5. [Delegate a Team to an IdP group](../../../../orgs-and-teams/teams#delegate-a-team-to-an-idp-group). --- ## OpenID Connect Configure any OpenID Connect (OIDC) provider for single sign-on (SSO) to Seqera Platform. Keycloak, Microsoft Entra ID, and Okta are covered below, but the same steps apply to any OIDC-compliant provider. All OIDC providers use the same Seqera environment variables (`TOWER_OIDC_CLIENT`, `TOWER_OIDC_SECRET`, `TOWER_OIDC_ISSUER`) and the same callback URL. Only the application setup within the provider differs. :::note You can combine different OAuth and OIDC provider types. However, only one OIDC provider can be configured at a time. ::: ## Create an application with your identity provider Create an application (or client) in your identity provider, then note its client ID, client secret, and issuer URL for the next section. In your provider settings, set the callback address (also called the authorized redirect or sign-in redirect URI) to the following, replacing `` with your enterprise installation hostname (must be HTTPS): ``` https:///oauth/callback/oidc ``` :::info[Prerequisites]{#keycloak-prerequisites} You need the following: - A [Keycloak](https://www.keycloak.org/) instance - Admin access to create clients in Keycloak ::: See the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#assembly-managing-clients_server_administration_guide) to configure Keycloak clients. **Create a Keycloak client** 1. In **Realm settings**, verify the **Endpoints** field includes _OpenID Endpoint Configuration_. 2. Go to **Clients** and select **Create**. 3. Configure the client with protocol `openid-connect`, access type `confidential`, and redirect URI `https:///oauth/callback/oidc`. 4. In the **Credentials** tab, note the **Secret**. 5. In the **Keys** tab, set **Use JWKS URL** to `OFF`. 6. Note the issuer URL from **Realm Settings > Endpoints > OpenID Configuration** (the `issuer` value in the JSON), e.g., `https://keycloak.example.com/auth/realms/master`. :::info[Prerequisites]{#entra-id-prerequisites} You need the following: - An Azure account with [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc) access - Permission to create app registrations ::: See Microsoft's documentation on [registering an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) for the registration steps. **Register an Entra ID application** 1. In the [Azure portal](https://portal.azure.com/), go to **Entra ID > App Registrations**. 2. Select **New Registration** and specify a name and supported account types. 3. Set the redirect URI to `https:///oauth/callback/oidc`. 4. Note the **Application (client) ID** from the app overview. 5. Go to **Certificates & secrets** and create a new client secret. Note the secret value. 6. Go to **Endpoints** and note the OpenID Connect metadata document URI (up to `v2.0`), e.g., `https://login.microsoftonline.com//v2.0`. **User consent settings** Configure user consent settings to **Allow user consent for apps** to ensure admin approval is not required for each login. See [User consent settings](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/configure-user-consent?pivots=portal#configure-user-consent-settings). :::note Add `auth-oidc` to the `MICRONAUT_ENVIRONMENTS` environment variable for both the `cron` and `backend` services. ::: :::note Compatibility note Users on Seqera Platform version 25.2.3 and below may need to set the following environment variable to resolve an authentication method incompatibility: ```env MICRONAUT_SECURITY_OAUTH2_CLIENTS_OIDC_OPENID_TOKEN_AUTH_METHOD=client_secret_post ``` ::: :::info[Prerequisites]{#okta-prerequisites} You need the following: - An [Okta](https://www.okta.com/) organization - Administrator access to create applications ::: See Okta's documentation on [creating OIDC app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) to set up the app. **Create an Okta app integration** 1. In the **Admin Console**, go to **Applications > Applications**. 2. Select **Create App Integration**. 3. Select **OIDC - OpenID Connect** as the sign-in method and **Web Application** as the application type. 4. Enter a name for the app, e.g., `Seqera`. 5. Set the sign-in redirect URI to `https:///oauth/callback/oidc`. 6. Set the sign-out redirect URI to `https:///logout`. 7. Note the **Client ID** and **Client secret** from the application settings. 8. Note the **Issuer** URL from **Sign On > OpenID Connect ID Token**. :::note Connection strings can differ based on the issuer type. Verify the issuer URL via the Okta console. ::: ## Configure Seqera Add the following environment variables to your Seqera backend service configuration: | Variable | Description | | :------- | :---------- | | `TOWER_OIDC_CLIENT` | The client ID provided by your identity provider | | `TOWER_OIDC_SECRET` | The client secret provided by your identity provider | | `TOWER_OIDC_ISSUER` | The issuer URL provided by your identity provider | | `TOWER_OIDC_SCOPES` | Optional. Comma-separated OAuth 2.0 scopes the OIDC client requests at login. Defaults to `openid,email,profile`. `openid` is always included. Add `groups` when your IdP only emits the group claim for a requested scope (see the note below). | Some providers require the full authentication service URL while others require only the SSO root domain (without the trailing sub-directories). :::note If you plan to use IdP-delegated teams, your OIDC token must include a `groups` claim. Some providers (for example, Okta) only emit this claim when a matching scope is requested. In that case, add `groups` to the requested scopes with `TOWER_OIDC_SCOPES=openid,email,profile,groups`. See [IdP claim mapping](./idp-delegation/claim-mapping) for the per-IdP configuration steps. ::: ## Restrict access To restrict access to specific email addresses or domains, configure an allow list in `tower.yml`: ```yaml tower: auth: oidc: allow-list: - "*@your-company.example.com" - "specific-user@another-company.example.net" ``` See [User access allow list](./overview#user-access-allow-list) for more information. --- ## Authentication(Authentication) Seqera Platform supports email and various OAuth providers for login authentication. ## Identity providers Configure login authentication with any of the following identity providers: | Provider | Protocol | Configuration | | :------------------------------------------------------ | :--------- | :--------------- | | [Email](./email) | Magic link | `TOWER_SMTP_*` | | [GitHub](./github) | OAuth | `TOWER_GITHUB_*` | | [Google](./google) | OAuth | `TOWER_GOOGLE_*` | | [OpenID Connect](./oidc) (Keycloak, Entra ID, Okta, …) | OIDC | `TOWER_OIDC_*` | ## OpenID Connect configuration :::note You can combine different OAuth and OIDC provider types. However, only one OIDC provider can be configured at a time. ::: For OIDC providers, configure authentication with these environment variables: | Variable | Description | | :------------------ | :------------------------------------------------------------------------------------------ | | `TOWER_OIDC_CLIENT` | The client ID provided by your authentication service | | `TOWER_OIDC_SECRET` | The client secret provided by your authentication service | | `TOWER_OIDC_ISSUER` | The authentication service URL to which Seqera connects to authenticate the sign-in request | Some providers require the full authentication service URL while others require only the SSO root domain (without the trailing sub-directories). In your OpenID provider settings, specify the following URL as a callback address or authorized redirect: ``` https:///oauth/callback/oidc ``` :::note If you plan to use IdP-delegated teams, your OIDC token must include a `groups` claim. See [IdP claim mapping](./idp-delegation/claim-mapping) for the per-IdP configuration steps. ::: ## Root users Root users have administrative access to all Platform resources. Configure root users by their user ID or email address in a comma-separated list: **Environment variable** ```env TOWER_ROOT_USERS=1,admin@your-company.example.com ``` **tower.yml** ```yaml tower: admin: root-users: "1,admin@your-company.example.com" ``` ## JWT secret Configure the secret key used to sign JWT tokens for user authentication sessions. This is a required security setting for all Platform deployments. :::warning The JWT secret must remain consistent across all backend instances and restarts. Changing this value will invalidate all active user sessions and log out all users. ::: **Environment variable** ```env TOWER_JWT_SECRET= ``` **Requirements:** - Minimum 35 characters recommended - Use a cryptographically secure random string - Keep this value secret and do not commit to version control **Generate a secure value:** ```bash openssl rand -base64 48 ``` This secret is used to sign both access tokens and refresh tokens for user sessions. ## Disable email login Disable email-based (magic link) authentication when OAuth providers are configured. :::note This setting only takes effect when at least one OAuth provider (GitHub, Google) or OIDC is configured. ::: **Environment variable** ```env TOWER_AUTH_DISABLE_EMAIL=true ``` **tower.yml** ```yaml tower: auth: disable-email: true ``` ## Session management Platform login sessions remain active as long as the application browser window remains open and active. Sessions use short-lived access tokens that are automatically refreshed via heartbeat. | Setting | Default | Description | |:------------------------------------------------------------------|:-----------|:----------------------------------------------------------------------------| | `micronaut.security.token.generator.access-token.expiration` | 3600s (1h) | Short-lived token, auto-refreshed via heartbeat | | `micronaut.security.token.jwt.generator.refresh-token.expiration` | 6h | Session idle timeout — users are logged out after this period of inactivity | | `micronaut.security.token.refresh.cookie.cookie-max-age` | 12h | Browser cookie lifetime (should be ≥ refresh token) | **tower.yml** ```yaml micronaut: security: token: jwt: generator: refresh-token: expiration: 8h generator: access-token: expiration: 3600 refresh: cookie: cookie-max-age: 10h ``` ## User access allow list Restrict access to specific user email addresses or domains. Allow list entries are case-insensitive. Replace `` with `github`, `google`, or `oidc`. Use `oidc` for any authentication service based on OpenID Connect (Okta, Entra ID, Keycloak, etc.). Include each provider separately if you configure more than one. **tower.yml** ```yaml tower: auth: : allow-list: - "*@your-company.example.com" - "specific-user@another-company.example.net" ``` ## IdP delegation and group claims Seqera Platform Enterprise supports IdP-delegated teams: organization owners can map a Seqera team to an IdP group, after which the IdP becomes the sole authority for who belongs to that team. Memberships are evaluated on every SSO login. :::note IdP claims mapping is **enabled by default** on Enterprise from version 26.1.4. To turn it off, set `TOWER_IDP_CLAIMS_MAPPING_ENABLED=false`. On earlier versions the feature is disabled by default and must be enabled explicitly. ::: The feature is gated per organization: it applies only to organizations with an active SSO connection, and — when the allowlist below is configured — only to the organizations on that list. **Environment variables** | Variable | Description | | :-- | :-- | | `TOWER_IDP_CLAIMS_MAPPING_ENABLED` | Master switch for IdP claims mapping. Defaults to `true` on Enterprise (26.1.4 and later). Set to `false` to disable the feature for the whole instance. | | `TOWER_IDP_CLAIMS_MAPPING_ALLOWED_ORGANIZATIONS` | Optional comma-separated list of organization IDs allowed to use the feature. When unset, all organizations that pass the other checks are allowed; when set but empty, no organization is allowed; when non-empty, only the listed organizations are allowed. | **tower.yml** ```yaml tower: idp-claims-mapping: enabled: true # Optional allowlist; omit to allow all SSO-enabled organizations allowed-organizations: "100,200" ``` For delegation to work, your IdP must: - Push or expose its group directory to Seqera. See [Manage your IdP group catalog](./idp-delegation/group-catalog/overview) for the SCIM 2.0 push and manual-entry options. - Include a `groups` claim in the tokens it issues. See [IdP claim mapping](./idp-delegation/claim-mapping) for protocol-specific guidance. Once those two pieces are in place, see [IdP delegation overview](./idp-delegation/overview) for the runtime model and [Delegate a Team to an IdP group](../../../orgs-and-teams/teams#delegate-a-team-to-an-idp-group) for the administrator procedure. If your Enterprise instance hosts more than one organization, review the [multi-organization routing rules](./idp-delegation/multi-org-routing) before configuring delegation. --- ## AWS Parameter Store From version 23.1, Seqera Platform Enterprise can fetch configuration values from the AWS Parameter Store. :::caution `TOWER_DB_USER`, `TOWER_DB_PASSWORD`, and `TOWER_DB_URL` values must be specified using **environment variables** during initial Seqera Enterprise deployment in a new environment. A new installation will fail if DB values are only defined in `tower.yml` or the AWS Parameter Store. After the database has been created, these values can be added to AWS Parameter Store entries and removed from your environment variables. ::: ## Configuration values not supported in AWS Parameter Store Due to the order of operations when deploying Seqera Enterprise, some configuration values can only be retrieved from **environment variables** (`tower.env`). The following configuration values are not supported by AWS Parameter Store and must be set as environment variables: | Environment Variable | Description | Value | | ------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `TOWER_DB_USER` | The user account to access your database. If you are using an external database, you must create this user manually. **For installation in a new environment, this value must be set as an environment variable.** | Default: `tower` | | `TOWER_DB_PASSWORD` | The user password to access your database. If you are using an external database, you must create this password manually. **For installation in a new environment, this value must be set as an environment variable.** | Default: `tower` | | `TOWER_DB_URL` | The URL to access your database. **For installation in a new environment, this value must be set as an environment variable.** | Example: `jdbc:mysql://db:3306/tower?permitMysqlScheme=true` | | `TOWER_APP_NAME` | Application name. To run multiple instances of the same Seqera account, each instance must have a unique name, e.g., `tower-dev` and `tower-prod`. **Can also be set in `tower.yml` with `tower.appName`.** | Default: `tower` | | `TOWER_ENABLE_AWS_SES` | Set `true` to enable AWS Simple Email Service for sending Seqera emails instead of SMTP. | Default: `false` | | `TOWER_ENABLE_PLATFORMS` | A comma-separated list of execution backends to enable. **At least one is required.** | `altair-platform,awsbatch-platform,awscloud-platform,azbatch-platform,eks-platform,googlebatch-platform,googlecloud-platform,gke-platform,k8s-platform,local-platform,lsf-platform,moab-platform,slurm-platform` | | `TOWER_ENABLE_UNSAFE_MODE` | Set to `true` to allow HTTP connections to Seqera. HTTP must not be used in production deployments. HTTPS is used by default from version 22.1.x. | Default: `false` | ## Configure Seqera to use AWS Parameter Store values To enable Seqera use AWS Parameter Store values: 1. Grant [AWS Parameter Store permissions](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-access.html) to your Seqera host instance. 2. Add `TOWER_ENABLE_AWS_SSM=true` in the `tower.env` configuration file. 3. Create individual parameters in the AWS Parameter Store (see below). 4. Start your Seqera instance and confirm the following entries appear in the **backend** container log: ```bash [main] - INFO i.m.context.DefaultBeanContext - Reading bootstrap environment configuration [main] - INFO i.m.d.c.c.DistributedPropertySourceLocator - Resolved 2 configuration sources from client: compositeConfigurationClient(AWS Parameter Store) ``` ## Create configuration values in AWS Parameter Store Store Seqera configuration values as individual parameters in the AWS Parameter Store. :::caution The default application name is `tower-app`. To deploy multiple instances from the same Seqera Enterprise account, set a custom application name for each instance with the `micronaut.application.name` value in your `tower.yml` configuration file. ::: We recommend storing sensitive values, such as database passwords, as SecureString-type parameters. These parameters require additional IAM KMS key permissions to be decrypted. Seqera does not support StringList parameters. Configuration parameters with multiple values can be created as comma-separated lists of String type. To create Seqera configuration parameters in AWS Parameter Store, do the following: 1. Navigate to the **Parameter Store** from the **AWS Systems Manager Service** console. 2. From the **My parameters** tab, select **Create parameter** and populate as follows: | Field | Description | | ----- | ----------- | | **Name** | Use the format `/config//`. `` follows the `tower.yml` nesting hierarchy. See the [configuration overview](./overview) for specific paths.**Example: `/config/tower-app/mail.smtp.password : `** | | **Description** | (Optional) Description for the parameter. | | **Tier** | Select **Standard**. | | **Type** | Use **SecureString** for sensitive values like passwords and tokens. Use **String** for everything else. | | **Data type** | Select **text**. | | **Value** | Enter a plain text value (this is the configuration value used in Seqera). | --- ## Mirroring container images Mirroring Seqera container images to your own registry is recommended for production deployments. This ensures your deployments are not impacted by external registry availability and supports air-gapped environments. ## Registry-native replication Use your container registry's built-in replication features to automatically sync images from `cr.seqera.io`: - [Amazon ECR replication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/replication.html) - [Azure ACR artifact caching](https://learn.microsoft.com/en-us/azure/container-registry/artifact-cache-overview) - [Harbor replication](https://goharbor.io/docs/latest/administration/configuring-replication/) ## Skopeo Use [Skopeo](https://github.com/containers/skopeo) (v1.15+) when your registry doesn't support native replication. Authenticate with the Seqera registry: ```bash skopeo login --username 'robot$private+YOUR_ROBOT_USERNAME' -p 'YOUR_PASSWORD' cr.seqera.io ``` Create a YAML file (`seqera-images.yaml`) to specify which images to sync: ```yaml cr.seqera.io: images-by-semver: enterprise/platform/backend: ">= v25.3.4" enterprise/platform/frontend: ">= v25.3.4" enterprise/platform/migrate-db: ">= v25.3.4" ``` Run the sync: ```bash skopeo sync --scoped --src yaml --dest docker seqera-images.yaml YOUR_REGISTRY ``` Schedule periodic sync jobs to keep images current. See the [Skopeo sync documentation](https://github.com/containers/skopeo/blob/main/docs/skopeo-sync.1.md) for advanced usage. --- ## Networking ## HTTP proxy environment variables :::caution Proxies that require passwords aren't supported. ::: If your Seqera Platform Enterprise instance must access the internet via a proxy server, configure the following case-insensitive environment variables: - `http_proxy`: The proxy server for HTTP connections. - `https_proxy`: The proxy server for HTTPS connections. - `no_proxy`: One or more host names that bypass the proxy server. In the following example, `alice.example.com:8080` is configured as a proxy for all HTTP and HTTPS traffic, except for traffic to the `internal.example.com` and `internal2.example.com` hosts. ```env export http_proxy='alice.example.com:8080' export https_proxy='alice.example.com:8080' export no_proxy=internal.example.com,internal2.example.com ``` ## Isolated environments If you're deploying Seqera in an environment that has no external internet access, ensure that no pipeline assets or parameters in your configuration contain external links, as this will lead to connection failures. ## Mail proxy server Mail proxy server configuration details must be set either in `tower.yml` or AWS Parameter Store. **tower.yml** ::table{file=configtables/mail_server_proxy_yml.yml} **AWS Parameter Store** ::table{file=configtables/mail_server_proxy_aws.yml} --- ## Configuration :::note Nextflow Tower Enterprise is now Seqera Platform Enterprise. Existing configuration parameters, configuration files, and API endpoints that include _Tower_ currently remain unchanged. ::: Set Seqera configuration values using environment variables, a `tower.yml` configuration file, or individual values stored in AWS Parameter Store. Sensitive values such as database passwords should be stored securely (e.g., as SecureString type parameters in AWS Parameter Store). Declare environment variables in a [tower.env](../_templates/docker/tower.env) file. For example: ```bash TOWER_CONTACT_EMAIL=hello@foo.com TOWER_SMTP_HOST=your.smtphost.com ``` See the `Environment variables` option in each section below. Declare YAML configuration values in a [tower.yml](../_templates/docker/tower.yml) file. For example: ```yml mail: from: "hello@foo.com" smtp: host: "your.smtphost.com" ``` See the `tower.yml` option in each section below. YAML configuration keys on this page are listed in "dot" notation, i.e., the SMTP host value in the snippet above is represented as `mail.smtp.host` in the tables that follow. Don't declare duplicate keys in your `tower.yml` configuration file. Platform will only enforce the last instance of configuration keys that are defined more than once, for example: ```yaml # This block will not be enforced due to the duplicate `tower` key below tower: trustedEmails: - user@example.com # This block will be enforced because it's defined last tower: auth: oidc: - "*@foo.com" ``` AWS Parameter Store configuration is only supported for AWS deployments. Create parameters in the AWS Parameter Store individually, using the format `/config// : `. For example: ```bash /config/tower-app/mail.smtp.user : /config/tower-app/mail.smtp.password : ``` :::caution The default application name is `tower-app`. To deploy multiple instances from the same Seqera Enterprise account, set a custom application name for each instance with the `micronaut.application.name` value in your `tower.yml` configuration file. ::: Sensitive values (such as database passwords) should be SecureString type parameters. See [AWS Parameter Store](./aws_parameter_store) for detailed instructions. ## Configuration values not supported in tower.yml or AWS Parameter Store Due to the order of operations when deploying Seqera Enterprise, some configuration values can only be retrieved from **environment variables** (`tower.env`). The following configuration values are not supported for `tower.yml` or AWS Parameter Store configuration and must be set as environment variables: ::table{file=configtables/req_env_vars.yml} ## Basic configuration Basic configuration options such as the Seqera instance server URL, application name, and license key. ::table{file=configtables/generic_config_env.yml} YAML configuration keys in this table are listed in "dot" notation, i.e., a nested value: ```yaml ... mail: smtp: host: "your.smtphost.com" ... ``` is represented as `mail.smtp.host`. ::table{file=configtables/generic_config_yml.yml} AWS Parameter Store configuration is only supported for AWS deployments. Replace `{prefix}` in each configuration path with `/config/`, where `application_name` is `tower` or your custom application name. See [AWS Parameter Store](./aws_parameter_store). ::table{file=configtables/generic_config_aws.yml} ## Seqera and Redis databases Configuration values that control Seqera's interaction with databases and Redis instances. `TOWER_DB_USER`, `TOWER_DB_PASSWORD`, and `TOWER_DB_URL` must be specified using environment variables during initial Seqera Enterprise deployment in a new environment. A new installation will fail if DB values are only defined in `tower.yml` or the AWS Parameter Store. Once the database has been created, these values can be added to `tower.yml` or [AWS Parameter Store](./aws_parameter_store) entries and removed from your environment variables. :::note **Database version requirements:** From Seqera Enterprise version 23.4: - MySQL 8 is the officially supported and tested database version. - MySQL versions 5.6 and 5.7 are no longer supported. From Seqera Enterprise version 24.2: - Redis version 6.2 or greater is required. - Redis version 7 is officially supported. Follow your cloud provider specifications to upgrade your instance. ::: If you use a database **other than** the provided `db` container, you must create a user and database schema manually. ```SQL CREATE DATABASE tower; ALTER DATABASE tower CHARACTER SET utf8 COLLATE utf8_bin; CREATE USER 'tower' IDENTIFIED BY ; GRANT ALL PRIVILEGES ON tower.* TO tower@'%' ; ``` ```SQL GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, EXECUTE, CREATE VIEW, SHOW VIEW, CREATE ROUTINE, ALTER ROUTINE, EVENT, TRIGGER on tower.* TO tower@'%'; ``` ### Managed Redis services Seqera supports managed Redis services such as [Amazon ElastiCache](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html), [Azure Managed Redis](https://learn.microsoft.com/azure/redis/overview), or [Google Memorystore](https://cloud.google.com/memorystore/docs/redis). :::caution Microsoft is retiring Azure Cache for Redis. As of April 1, 2026, new customers cannot create instances, and from October 1, 2026, no new instances can be created. For new Azure deployments, use [Azure Managed Redis](https://learn.microsoft.com/azure/redis/overview). ::: When using a managed Redis service, you must specify the service IP address or DNS name for the `TOWER_REDIS_URL` as described in the following sections. - Use a single-node cluster, as multi-node clusters are not supported - Use an instance with at least 6 GB capacity ([cache.m4.large](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/CacheNodes.SupportedTypes.html) or greater) - Specify your private ElastiCache instance in the Seqera environment variables: ```bash TOWER_REDIS_URL=redis://:6379 ``` - Use a single-node cluster, as multi-node clusters are not supported - Choose a production-capable [Azure Managed Redis tier](https://learn.microsoft.com/azure/redis/overview) appropriate for your workload - Specify your private Azure Managed Redis instance in the Seqera environment variables: ```bash TOWER_REDIS_URL=redis://:6379 ``` - Use a single-node cluster, as multi-node clusters are not supported - Use an instance with at least 6 GB capacity ([M2](https://cloud.google.com/memorystore/docs/redis/pricing#instance_pricing) or greater) - Specify your private Memorystore instance in the Seqera environment variables: ```bash TOWER_REDIS_URL=redis://:6379 ``` If you run the Redis service as a container in your Docker or Kubernetes installation, specify the service name as part of the `TOWER_REDIS_URL`: ```bash TOWER_REDIS_URL=redis://redis:6379 ``` ### Database and Redis manual configuration If the DB username and password variables are left empty when using [Docker Compose](../platform-docker-compose), default `tower` database values are applied automatically. With [Kubernetes](../platform-kubernetes) and custom DB deployments, `tower` values are not pre-filled. :::note We recommend using managed cloud database services for production deployments. ::: ::table{file=configtables/db_env.yml} `TOWER_DB_USER`, `TOWER_DB_PASSWORD`, and `TOWER_DB_URL` must be specified using **environment variables** during initial Seqera Enterprise deployment in a new environment. YAML configuration keys in this table are listed in "dot" notation, i.e., a nested value: ```yaml ... mail: smtp: host: "your.smtphost.com" ... ``` is represented as `mail.smtp.host`. ::table{file=configtables/db_yml.yml} AWS Parameter Store configuration is only supported for AWS deployments. `TOWER_DB_USER`, `TOWER_DB_PASSWORD`, and `TOWER_DB_URL` must be specified using **environment variables** during initial Seqera Enterprise deployment in a new environment. Replace `{prefix}` in each configuration path with `/config/`, where `application_name` is `tower` or your custom application name. See [AWS Parameter Store](./aws_parameter_store). ::table{file=configtables/db_aws.yml} ## Opt-in Seqera features Configuration values that enable opt-in Seqera features per instance or workspace. ### Core features ::table{file=configtables/features_env.yml} ### Data features Configuration values used by Seqera for Datasets, Data Explorer, Data Lineage, and Studios. ::table{file=configtables/data_features_env.yml} ::table{file=configtables/data_features_yml.yml} ## Cryptographic options Configuration values used by Seqera to encrypt your data. :::caution Do not modify your crypto secret key between starts. Changing this value will prevent the decryption of existing data. ::: ::table{file=configtables/crypto_env.yml} YAML configuration keys in this table are listed in "dot" notation, i.e., a nested value: ```yaml ... mail: smtp: host: "your.smtphost.com" ... ``` is represented as `mail.smtp.host`. ::table{file=configtables/crypto_yml.yml} AWS Parameter Store configuration is only supported for AWS deployments. Replace `{prefix}` in each configuration path with `/config/`, where `application_name` is `tower` or your custom application name. See [AWS Parameter Store](./aws_parameter_store). ::table{file=configtables/crypto_aws.yml} ### Secret key rotation Rotate the key used to encrypt the credentials and secrets stored in your Platform database. Encryption key rotation is a security best practice and should be performed at an interval specified by your organization's security requirements, or in the event of a suspected compromise of your secret key. Enable rotation by setting the following configuration values: - `TOWER_SECRET_ROTATION_ENABLED=true` - `TOWER_SECRET_ROTATION_PREVIOUS_KEY=` - `TOWER_CRYPTO_SECRETKEY=` - `tower.secret.rotation.enabled: true` - `tower.secret.rotation.previous-key: ` - `tower.crypto.secretKey: ` - `/tower/secret-rotation/enabled: true` - `/tower/secret-rotation/previous-key: ` - `/tower/crypto/secretKey: ` With rotation enabled and the previous and new key values set, secret key rotation will run as part of the Platform cron service during application startup. Normal application startup is not affected by this process, and Platform is fully operational while the credentials and secrets in your database are being encrypted using your new secret key. :::warning - To prevent data loss, perform a backup of your Platform database and securely back up your current crypto secret key before enabling and performing key rotation. - All backend pods or containers for your Enterprise deployment must contain the same previous and new secret key values in their Platform config and must be in a ready/running state before starting the Platform cron service. ::: The [Admin panel](../../administration/overview.md#encryption) **Encryption** tab displays the status of completed or errored encryption tasks. ## Backend memory requirements The Platform backend and cron services run on the Java Virtual Machine (JVM). Allocate at least 4 GB of memory to each service for stable operation under load. For Kubernetes, set resource limits in your pod specifications: ```yaml resources: limits: memory: "4Gi" requests: memory: "4Gi" ``` For Docker Compose, set memory limits in your service definitions: ```yaml services: backend: mem_limit: 4g memswap_limit: 4g ``` :::note These default memory allocation limits are included in the Kubernetes manifest templates ([tower-svc.yml](../_templates/k8s/tower-svc.yml) and [tower-cron.yml](../_templates/k8s/tower-cron.yml)). For Docker Compose, add the `mem_limit` settings to your service definitions as shown above. ::: ### JVM memory tuning For production deployments, configure JVM memory parameters with the `JAVA_OPTS` environment variable. This baseline configuration suits most deployments: ```bash JAVA_OPTS="-Xms1000M -Xmx2000M -XX:MaxDirectMemorySize=800m -Dio.netty.maxDirectMemory=0 -Djdk.nio.maxCachedBufferSize=262144" ``` The `JAVA_TOOL_OPTIONS` environment variable is a supported alternative to `JAVA_OPTS`. The JVM reads it directly at startup and confirms pickup with a `Picked up JAVA_TOOL_OPTIONS` line in the service logs. Set one variable or the other, not both. Options passed on the command line (which is how `JAVA_OPTS` is applied) take precedence over `JAVA_TOOL_OPTIONS` when the same flag appears in both. :::note These default JVM memory settings are included in the configuration templates provided in these docs: - Kubernetes: [tower-svc.yml](../_templates/k8s/tower-svc.yml) and [tower-cron.yml](../_templates/k8s/tower-cron.yml) - Docker Compose: [tower.env](../_templates/docker/tower.env) ::: | Parameter | Description | | --- | --- | | `-Xms` / `-Xmx` | Initial and maximum heap size — the memory pool for Java objects. | | `-XX:MaxDirectMemorySize` | Off-heap memory for NIO operations, network buffers, and file I/O. Handles concurrent workflow API operations. | | `-Dio.netty.maxDirectMemory=0` | Disables Netty's internal memory tracking and relies on the JVM direct memory limit instead. | | `-Djdk.nio.maxCachedBufferSize` | Limits the size of cached NIO buffers to prevent excessive memory retention. | Adjust these baseline values based on the symptoms you observe. Increase `-XX:MaxDirectMemorySize` if you observe: - `OutOfMemoryError: Direct buffer memory` in the logs - High concurrent workflow launch rates (more than 100 simultaneous workflows) - Large configuration payloads or heavy API usage Increase heap memory (`-Xmx`) if you observe: - `OutOfMemoryError: Java heap space` in the logs - Garbage collection pauses that affect performance - Growing memory usage under sustained load For deployments running 200 or more concurrent workflows, increase the heap and direct memory limits: ```bash JAVA_OPTS="-Xms1000M -Xmx3000M -XX:MaxDirectMemorySize=1600m -Dio.netty.maxDirectMemory=0 -Djdk.nio.maxCachedBufferSize=262144" ``` Set the container or pod memory limit higher than the JVM limits to accommodate non-heap memory usage. :::warning These are starting values. Monitor your deployment's memory usage and adjust for your workload. Undersized memory allocation can cause out-of-memory (OOM) failures and service instability. ::: ## Compute environments Configuration values to enable computing platforms and customize Batch Forge resource naming. ::table{file=configtables/compute_env.yml} ### Compute environment cleanup A scheduled cron job can transition compute environments that are stuck in `CREATING` or `DELETING` states into terminal states (`ERRORED` or `INVALID`). The cleanup job is disabled by default. ::table{file=configtables/compute_env_cleanup_env.yml} ## Git integration Seqera Platform has built-in support for public and private Git repositories. Create [Git provider credentials](../../git/overview) to allow Seqera to interact with the following services: - [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) - [BitBucket](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) - [GitLab](https://gitlab.com/profile/personal_access_tokens) - [Gitea](https://docs.gitea.io/en-us/development/api-usage/#generating-and-listing-api-tokens) - [Azure Repos](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) :::caution Credentials configured in your SCM providers list override Git credentials in your (organization or personal) workspace. ::: Public Git repositories can be accessed without authentication, but are often subject to [throttling](https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#rate-limits-for-requests-from-personal-accounts). We recommend always adding Git credentials to your Seqera workspace, regardless of the repository type you use. Credentials and other secrets must not be hard-coded in environment variables in production environments. Credentials added using the application UI are SHA256-encrypted before secure storage and not exposed by any Seqera API. ::table{file=configtables/git_env.yml} Credentials and other secrets must not be stored in plain text in production environments. Credentials added using the application UI are SHA256-encrypted before secure storage and not exposed by any Seqera API. YAML configuration keys in this table are listed in "dot" notation, i.e., a nested value: ```yaml ... mail: smtp: host: "your.smtphost.com" ... ``` is represented as `mail.smtp.host`. ::table{file=configtables/git_yml.yml} AWS Parameter Store configuration is only supported for AWS deployments. Replace `{prefix}` in each configuration path with `/config/`, where `application_name` is `tower` or your custom application name. See [AWS Parameter Store](./aws_parameter_store). ::table{file=configtables/git_aws.yml} ### Local repositories Seqera Enterprise can connect to workflows stored in local Git repositories. To do so, volume mount your local repository folder in your Seqera backend container. Then, update your `tower.yml`: ```yml tower: pipeline: allow-local-repos: - /path/to/repo ``` ## Mail server Configure values for SMTP email service integration. Production SMTP hosts must use a TLS-protected connection. See [SSL/TLS](../configuration/ssl_tls). AWS deployments also support [Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/). ### SMTP service integration To use an SMTP gateway for mail service, set SMTP user and password values to `null`. :::caution Your organization's email security policy may prevent the `TOWER_CONTACT_EMAIL` address from receiving Seqera emails. If this occurs after successful SMTP configuration, you may need to configure `spf`, `dkim`, and `dmarc` records for your domain. Contact your IT support staff for further assistance. ::: ::table{file=configtables/mail_server_env.yml} YAML configuration keys in this table are listed in "dot" notation, i.e., a nested value: ```yaml ... mail: smtp: host: "your.smtphost.com" ... ``` is represented as `mail.smtp.host`. ::table{file=configtables/mail_server_yml.yml} AWS Parameter Store configuration is only supported for AWS deployments. Replace `{prefix}` in each configuration path with `/config/`, where `application_name` is `tower` or your custom application name. See [AWS Parameter Store](./aws_parameter_store). ::table{file=configtables/mail_server_aws.yml} ### AWS SES integration In AWS deployments, you can use AWS Simple Email Service (SES) instead of traditional SMTP for sending Seqera platform emails. :::note Simple Email Service (SES) is only supported in Seqera deployments on AWS. ::: To configure AWS SES as your Seqera email service: 1. Set `TOWER_ENABLE_AWS_SES=true` in your environment variables. 2. Specify the email address used to send Seqera emails with one of the following: - the `TOWER_CONTACT_EMAIL` environment variable - a `mail.from` entry in `tower.yml` - a `/config//mail/from` AWS Parameter Store entry 3. The [AWS SES service](https://docs.aws.amazon.com/ses/index.html) must run in the same region as your Seqera instance. 4. The [Seqera IAM role](../../compute-envs/aws-batch#iam-user-creation) must include the `ses:SendRawEmail` permission. ## Nextflow launch container :::caution Do not replace the [Seqera-provided default image](../../functionality_matrix/overview) unless absolutely necessary. ::: | Environment Variable | Description | Value | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | `TOWER_LAUNCH_CONTAINER` | The container image to run the Nextflow execution. This setting overrides the launch container selection for all organizations and workspaces in your account, and disables the per-run [Nextflow version](../../launch/advanced#nextflow-version) selector. | Example: `quay.io/seqeralabs/nf-launcher:j17-23.04.3` | ## Seqera API Enable the API endpoints to host the Seqera Enterprise OpenAPI specification and use the [tw CLI](https://github.com/seqeralabs/tower-cli). Set custom API rate limits and timeouts. :::note To configure API rate limit environment variables, you must add `ratelim` to the `MICRONAUT_ENVIRONMENTS`. Without `ratelim` being set, the rate limit configuration variables below are ignored. ::: | Environment variable | Description | Value | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `TOWER_ENABLE_OPENAPI` | Enable the OpenAPI documentation endpoint, e.g., [cloud.seqera.io/openapi/index.html](https://cloud.seqera.io/openapi/index.html). | Default: `false` | | `TOWER_RATELIMIT_PERIOD` | Specify the maximum number of HTTP requests that can be made during the `TOWER_RATELIMIT_REFRESH` period. | Default: `20` | | `TOWER_RATELIMIT_REFRESH` | API rate limit refresh period. | Default: `1s` | | `TOWER_RATELIMIT_TIMEOUT` | The waiting period before rejecting requests over the `TOWER_RATELIMIT_PERIOD` limit during the refresh period. | Default: `500ms` | ## Custom navigation menu Modify your Seqera instance's navigation menu options. ```yaml tower: navbar: menus: - label: "My Community" url: "https://host.com/foo" - label: "My Pipelines" url: "https://other.com/bar" ``` ## Logging Logging-related configuration values to aid troubleshooting. See [Audit logs](../../monitoring/audit-logs) for more information on application event logging. In 26.1, use `TOWER_AUDIT_LOG_V2_WRITE_MODE` to control whether audit events are written to the v2 schema, or to both the legacy and the v2 schema. Use `TOWER_CRON_AUDIT_LOG_CLEAN_UP_ENABLED` to disable automatic audit log deletion, and restart Platform after changing audit log settings. ::table{file=configtables/tower_logging.yml} Set the logging detail level for various Seqera services. Logs for particular services may be requested by support to assist with troubleshooting an issue. Set the logging configuration parameter in your Seqera YAML configuration before attempting to reproduce your issue. The example below sets the detail level for application and database logging: `logger` is a root-level object in the `tower.yml` configuration file, i.e., it is not nested under `tower`. ```yaml logger: levels: org.hibernate.SQL: DEBUG org.hibernate.type: TRACE io.seqera.tower: TRACE ``` ### Audit log v2 Configuration values for the v2 audit log subsystem and the audit log cleanup cron job. The v2 audit log adds support for pre/post change state capture and CSV export limits, and runs alongside the existing v1 table when `TOWER_AUDIT_LOG_V2_WRITE_MODE` is set to `dual`. ::table{file=configtables/audit_log_v2_env.yml} --- ## Pipeline optimization [Pipeline optimization](../../pipeline-optimization/overview) takes the resource usage information from previous workflow runs to optimize subsequent runs. The pipeline optimization service requires a separate database schema to store its internal data, but also requires access to the Seqera schema. The Seqera and optimization service schemas can coexist on the same database instance. ## Docker Compose deployment Docker Compose makes use of a separate container to set up the pipeline optimization service during initialization. Configuration steps differ for new and existing deployments. ### New installation To use the pipeline optimization service in a new Docker Compose installation of Seqera Enterprise, use the following steps: 1. To run the service from a custom URL, declare the URL with the `GROUNDSWELL_SERVER_URL` environment variable in `tower.env`. A non-zero value for this environment variable activates the optimization service automatically, so `TOWER_ENABLE_GROUNDSWELL` does not need to be set when you declare a custom URL. 2. Set the `TOWER_ENABLE_GROUNDSWELL` environment variable in `tower.env` to `true`. This enables the service at the default service URL `http://groundswell:8090`. 3. In your [docker-compose.yml](../_templates/docker/docker-compose.yml) file, uncomment the `groundswell` section at the bottom. - To create a schema for the optimization service on the same local MySQL container, uncomment the `init.sql` script in the `volumes` section. 4. Download the [init.sql](../_templates/docker/init.sql) file. Store this file in the mount path of your `docker-compose.yml` file, else update the `source: ./init.sql` line in your `docker-compose.yml` with the file path. 5. When the pipeline optimization service is active, pipelines that can be optimized display a lightbulb icon in your Launchpad. Any pipeline with at least one successful run can be optimized. ### Existing installation To use the pipeline optimization service in an existing Docker Compose installation of Seqera Enterprise, use the following steps: 1. To run the service from a custom URL, declare the URL with the `GROUNDSWELL_SERVER_URL` environment variable. A non-zero value for this environment variable activates the optimization service automatically, so `TOWER_ENABLE_GROUNDSWELL` does not need to be set when you declare a custom URL. 2. Set the `TOWER_ENABLE_GROUNDSWELL` environment variable to `true`. This enables the service at the default service URL `http://groundswell:8090`. 3. In your [docker-compose.yml](../_templates/docker/docker-compose.yml) file, uncomment the `groundswell` section at the bottom. If you use a `docker-compose.yml` file older than version 23.3, download a newer version of the file to extract the `groundswell` section. 4. Log in to your database server and run the following commands: ```sql CREATE DATABASE IF NOT EXISTS `swell`; CREATE USER 'swell'@'%' IDENTIFIED BY 'swell'; GRANT ALL PRIVILEGES ON *.* TO 'swell'@'%'; FLUSH PRIVILEGES; ``` 5. If you use Amazon RDS or other managed database services, run the following commands in your database instance: ```sql CREATE DATABASE IF NOT EXISTS `swell`; CREATE USER 'swell'@'%' IDENTIFIED BY 'swell'; GRANT ALL PRIVILEGES ON `%`.* TO 'swell'@'%'; FLUSH PRIVILEGES; ``` 6. Download the [groundswell.env](../_templates/docker/groundswell.env) file. Store this file in the mount path of your `docker-compose.yml` file. Update the `TOWER_DB_URL` and `SWELL_DB_URL` values: ```env # Uncomment for container DB instances # TOWER_DB_URL=mysql://db:3306/tower # SWELL_DB_URL=mysql://db:3306/swell # Uncomment for managed DB instances (Example URL shows an Amazon RDS instance URL) # TOWER_DB_URL=mysql://db1.abcdefghijkl.us-east-1.rds.amazonaws.com:3306/tower # SWELL_DB_URL=mysql://db1.abcdefghijkl.us-east-1.rds.amazonaws.com:3306/swell ``` 7. When the pipeline optimization service is active, pipelines that can be optimized display a lightbulb icon in your Launchpad. Any pipeline with at least one successful run can be optimized. ## Kubernetes deployment Kubernetes deployments use an [initContainer](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) that runs during pod initialization to set up the pipeline optimization service. To use the service in new or existing Kubernetes installations of Seqera Enterprise, do the following: 1. Download the [groundswell manifest](../_templates/k8s/groundswell.yml). 1. To run the service from a custom URL, declare the URL with the `GROUNDSWELL_SERVER_URL` environment variable in the `configmap.yml` file that you downloaded for your [Platform installation][platform-k8s]. A non-zero value for this environment variable activates the optimization service automatically, so `TOWER_ENABLE_GROUNDSWELL` does not need to be set when you declare a custom URL. 1. Define a set of credentials for the optimization database. This can be the same database used for Seqera, but in a different schema. 1. Log in to your database server and run the following commands: - If you use Amazon RDS or other managed database services, run the following commands in your database instance: ```sql CREATE DATABASE IF NOT EXISTS `swell`; CREATE USER 'swell'@'%' IDENTIFIED BY 'swell'; GRANT ALL PRIVILEGES ON `%`.* TO 'swell'@'%'; FLUSH PRIVILEGES; ``` - If you do not use a managed database service, run the following commands in your database instance: ```sql CREATE DATABASE IF NOT EXISTS `swell`; CREATE USER 'swell'@'%' IDENTIFIED BY 'swell'; GRANT ALL PRIVILEGES ON *.* TO 'swell'@'%'; FLUSH PRIVILEGES; ``` The `initContainers` process waits until both the Seqera and pipeline optimization service databases are ready before starting the migration in the Seqera database, and finally starting the optimization container. When the pipeline optimization service is active, pipelines that can be optimized display a lightbulb icon in your Launchpad. Any pipeline with at least one successful run can be optimized. [platform-k8s]: ../platform-kubernetes --- ## Reverse proxy :::caution As of February 2024, this configuration guide is not currently recommended for production use, as the instructions are actively under development and will likely change. ::: To expose your Seqera instance behind a reverse proxy, complete the following steps: 1. Use the [Seqera frontend unprivileged](../platform-kubernetes#seqera-frontend-unprivileged) image. 2. Add `TOWER_BASE_PATH` to the environment variables of the frontend container: - `TOWER_BASE_PATH: "/myseqera/"` exposes your instance at `https://example.com/myseqera/` (this must match your proxy configuration) 3. In the backend/cron environment variables or in the Seqera config file, edit the following environment variables: - Set `TOWER_SERVER_URL` to the complete URL where you want to expose your instance, e.g., `TOWER_SERVER_URL: "https://example.com/myseqera"` (without the trailing slash) - Disable/unset `TOWER_LANDING_URL` 4. Configure your reverse proxy to redirect all Seqera-related links to your Seqera frontend container: - If your frontend container listens on `http://tower-frontend:8080` and you're using Apache HTTP as your reverse proxy, add the following lines at the end of your configuration file (replace `/myseqera/` with the URL you defined in `TOWER_BASE_PATH`): ``` LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so LoadModule rewrite_module modules/mod_rewrite.so RewriteEngine on RewriteRule "^/myseqera/(.*)$" http://tower-frontend:8080/$1 [P] ProxyPassReverse "/myseqera/" http://tower-frontend:8080/ RewriteRule "^/api/(.*)$" http://tower-frontend:8080/api/$1 [P] ProxyPassReverse "/api/" http://tower-frontend:8080/api/ RewriteRule "^/auth/(.*)$" http://tower-frontend:8080/auth/$1 [P] ProxyPassReverse "/auth/" http://tower-frontend:8080/auth/ RewriteRule "^/oauth/(.*)$" http://tower-frontend:8080/oauth/$1 [P] ProxyPassReverse "/oauth/" http://tower-frontend:8080/oauth/ RewriteRule "^/openapi/(.*)$" http://tower-frontend:8080/openapi/$1 [P] ProxyPassReverse "/openapi/" http://tower-frontend:8080/openapi/ RewriteRule "^/content/(.*)$" http://tower-frontend:8080/content/$1 [P] ProxyPassReverse "/content/" http://tower-frontend:8080/content/ ``` - A similar configuration should be applied for NGINX or other reverse proxies. Redirect visits to `/api/`, `/oauth/`, `/openapi/`, and `/content/`. After you configure the reverse proxy, the Seqera frontend URL (default `http://tower-frontend:8080`) should return a blank page. This behavior is expected, because Seqera is now configured to work only from behind the reverse proxy. --- ## SSL/TLS HTTP must not be used in production environments. An SSL certificate is required for your Seqera instance to handle HTTPS traffic. Private certificates are supported, but require additional configuration during Seqera Enterprise installation and Nextflow execution. ## AWS deployments: Manage SSL certificates with Amazon Certificate Manager (ACM) Use [Amazon Certificate Manager](https://aws.amazon.com/certificate-manager/) (ACM) to apply SSL certificates to your AWS deployment: - If you have an existing SSL certificate, see [Importing certificates into AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html). - If you don't have an existing SSL certificate, see [Issuing and managing certificates](https://docs.aws.amazon.com/acm/latest/userguide/gs.html). ## Configure Seqera to trust your private certificate If you secure related infrastructure (such as private Git repositories) with certificates issued by a private Certificate Authority, these certificates must be loaded into the Seqera Enterprise containers. You can achieve this in several ways. **Configure private certificate trust** 1. This guide assumes you're using the original containers supplied by Seqera. 2. Replace `TARGET_HOSTNAME`, `TARGET_ALIAS`, and `PRIVATE_CERT.pem` with your unique values. 3. Previous instructions advised using `openssl`. The native `keytool` utility is preferred as it simplifies steps and better accommodates private CA certificates. **Use Docker volume** 1. Retrieve the private certificate on your Seqera container host: ``` keytool -printcert -rfc -sslserver TARGET_HOSTNAME:443 > /PRIVATE_CERT.pem ``` 2. Modify the `backend` and `cron` container configuration blocks in `docker-compose.yml`: ```yaml CONTAINER_NAME: # -- Other keys here like `image` and `networks`-- # Add a new mount for the downloaded certificate volumes: - type: bind source: /PRIVATE_CERT.pem target: /etc/pki/ca-trust/source/anchors/PRIVATE_CERT.pem # Add a new keytool import line PRIOR to 'update-ca-trust' for the certificate command: > sh -c "keytool -import -trustcacerts -storepass changeit -noprompt -alias TARGET_ALIAS -file /etc/pki/ca-trust/source/anchor/TARGET_HOSTNAME.pem && update-ca-trust && /wait-for-it.sh db:3306 -t 60 && /tower.sh" ``` **Use K8s ConfigMap** 1. Retrieve the private certificate on a machine with CLI access to your Kubernetes cluster: ```bash keytool -printcert -rfc -sslserver TARGET_HOSTNAME:443 > /PRIVATE_CERT.pem ``` 2. Load the certificate as a `ConfigMap` in the same namespace where your Seqera instance will run: ```bash kubectl create configmap private-cert-pemstore --from-file=/PRIVATE_CERT.pem ``` 3. Modify both the `backend` and `cron` Deployment objects: - Define a new volume based on the certificate `ConfigMap`: ```yaml spec: template: spec: volumes: - name: private-cert-pemstore configMap: name: private-cert-pemstore ``` - Add a volumeMount entry into the container definition: ```yaml spec: template: spec: containers: - name: CONTAINER_NAME volumeMounts: - name: private-cert-pemstore mountPath: /etc/pki/ca-trust/source/anchors/PRIVATE_CERT.pem subPath: PRIVATE_CERT.pem ``` - Modify the container start command to load the certificate prior to running your Seqera instance: ```yaml spec: template: spec: containers: - name: CONTAINER_NAME command: ["/bin/sh"] args: - -c - | keytool -import -trustcacerts -cacerts -storepass changeit -noprompt -alias TARGET_ALIAS -file /PRIVATE_CERT.pem; ./tower.sh ``` **Download on Pod start** 1. Modify both the `backend` and `cron` Deployment objects to retrieve and load the certificate prior to running your Seqera instance: ```yaml spec: template: spec: containers: - name: CONTAINER_NAME command: ["/bin/sh"] args: - -c - | keytool -printcert -rfc -sslserver TARGET_HOST:443 > /PRIVATE_CERT.pem; keytool -import -trustcacerts -cacerts -storepass changeit -noprompt -alias TARGET_ALIAS -file /PRIVATE_CERT.pem; ./tower.sh ``` ## Configure the Nextflow launcher image to trust your private certificate If you secure infrastructure such as private Git repositories or your Seqera Enterprise instance with certificates issued by a private Certificate Authority, these certificates must also be loaded into the Nextflow launcher container. **Import private certificates via pre-run script** 1. This configuration assumes you're using the default `nf-launcher` image supplied by Seqera. 2. Replace `TARGET_HOSTNAME`, `TARGET_ALIAS`, and `PRIVATE_CERT.pem` with your unique values. 3. Previous instructions advised using `openssl`. The native `keytool` utility is preferred as it simplifies steps and better accommodates private CA certificates. Add the following to your compute environment [pre-run script](../../launch/advanced#pre-and-post-run-scripts): ```bash keytool -printcert -rfc -sslserver TARGET_HOSTNAME:443 > /PRIVATE_CERT.pem keytool -import -trustcacerts -cacerts -storepass changeit -noprompt -alias TARGET_ALIAS -file /PRIVATE_CERT.pem cp /PRIVATE_CERT.pem /etc/pki/ca-trust/source/anchors/PRIVATE_CERT.pem update-ca-trust ``` ## Configure Seqera to present a SSL/TLS certificate You can secure your Seqera instance with a TLS certificate in several ways. **Load balancer (recommended)** Place a load balancer, configured to present a certificate and act as a TLS termination point, in front of your Seqera instance. This solution is likely already implemented for cloud-based Kubernetes implementations and can be easily implemented for Docker Compose-based stacks. See [this example](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-application-load-balancer.html). **Reverse proxy container** This solution works well for Docker Compose-based stacks to avoid the additional cost and maintenance of a load balancer. See [this example](https://doc.traefik.io/traefik/v1.7/configuration/acme/). **Modify `frontend` container** Due to complications that can be encountered during upgrades, this approach is not recommended.
Show me anyway This example assumes deployment on an Amazon Linux 2 AMI. 1. Install NGINX and other required packages: ```bash sudo amazon-linux-extras install nginx1.12 sudo wget -r --no-parent -A 'epel-release-*.rpm' https://dl.fedoraproject.org/pub/epel/7/x86_64/Packages/e/ sudo rpm -Uvh dl.fedoraproject.org/pub/epel/7/x86_64/Packages/e/epel-release-*.rpm sudo yum-config-manager --enable epel* sudo yum repolist all sudo amazon-linux-extras install epel -y ``` 2. Generate a [private certificate and key](https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs). 3. Make a local copy of the `/etc/nginx/templates/tower.conf.template` file from the `frontend` container, or create a ConfigMap to store it if you're using Kubernetes. 4. Replace the `listen` directives in the `server` block with the following: ```nginx listen ${NGINX_LISTEN_PORT} ssl default_server; listen [::]:${NGINX_LISTEN_PORT_IPV6} ssl default_server; ssl_certificate /etc/ssl/testcrt.crt; ssl_certificate_key /etc/ssl/testkey.key; ``` 5. Modify the `frontend` container definition in your `docker-compose.yml` file or Kubernetes manifest: ```yml frontend: image: cr.seqera.io/frontend:${TAG} networks: - frontend environment: NGINX_LISTEN_PORT: 8081 NGINX_LISTEN_PORT_IPV6: 8443 ports: - 8000:8081 - 443:8443 volumes: - $PWD/tower.conf.template:/etc/nginx/templates/tower.conf.template - $PWD/cert/testcrt.crt:/etc/ssl/testcrt.crt - $PWD/cert/testkey.key:/etc/ssl/testkey.key restart: always depends_on: - backend ```
## TLS version support Seqera Enterprise versions 22.3.2 and earlier rely on Java 11 (Amazon Corretto). You may encounter issues when integrating with third-party services that enforce TLS v1.2 (such as Azure Active Directory OIDC). TLS v1.2 can be explicitly enabled by default using JDK environment variables: ```bash JAVA_OPTS="-Dmail.smtp.ssl.protocols=TLSv1.2" ``` --- ## Wave containers Wave is Seqera's container provisioning service that enables on-demand container image management for Nextflow pipelines. Wave can provision containers dynamically during pipeline execution, removing the need to manually build and upload images to a container registry. ## Deployment options Wave can be integrated with Seqera Platform in two ways: - **Seqera Wave service**: Use the hosted Wave service at `https://wave.seqera.io` (default for Seqera Cloud) - **Self-hosted Wave**: Deploy Wave in your own infrastructure for full control over container builds and caching ## Requirements ### Network connectivity | Source | Destination | Purpose | | :----- | :---------- | :------ | | Seqera Platform | Wave server | API communication | | Container registry | Wave server | Allow ingress for container operations | | Compute environments | Wave server | Container image access during pipeline execution | ### Container registry credentials Container registry credentials must be configured in the Seqera UI to authenticate with your private or public registries. See [container registry credentials](../../credentials/overview) for provider-specific instructions. ## Configuration ### Connect to Wave service Configure Seqera Platform to use the Seqera-hosted Wave service or your self-hosted Wave deployment: | Variable | Description | | :------- | :---------- | | `TOWER_ENABLE_WAVE` | Set to `true` to enable Wave integration | | `WAVE_SERVER_URL` | Wave server endpoint (default: `https://wave.seqera.io`) | ### Verify connectivity Test connectivity to your Wave server: ```bash curl https://wave.seqera.io/service-info ``` Replace `wave.seqera.io` with your self-hosted Wave endpoint if applicable. ## Features enabled by Wave After Wave is enabled, the following features become available: - **Private container registries**: Access containers from private repositories using credentials stored in Seqera - **Fusion file system**: High-performance cloud-native file system for pipeline execution - **Container augmentation**: Dynamically extend existing containers with additional layers - **Conda-based containers**: Provision containers from Conda or Bioconda packages on demand - **Singularity support**: Build and provision Singularity/Apptainer format containers - **Security scanning**: Automatic vulnerability scanning of built container images Wave features are available on the compute environment creation page after integration is configured. ## Limitations - Wave does not support container repositories with private CA SSL certificates ## Self-hosted Wave deployment For enterprises requiring full control over container builds, caching, and security scanning, Wave can be deployed in your own infrastructure. Self-hosted Wave supports: - **Wave Lite**: Container augmentation and inspection capabilities (AWS, Azure, GCP) - **Full Wave**: Complete build capabilities including Conda-based containers and security scanning (requires AWS EKS with EFS storage) See the [Wave documentation](https://docs.seqera.io/wave) for installation and configuration guidance. ## Additional resources - [Wave documentation](https://docs.seqera.io/wave) - [Nextflow Wave integration](https://docs.seqera.io/nextflow/wave) - [Seqera Containers](https://seqera.io/containers/) - Free community container registry --- ## Pipeline optimization: Docker Compose This guide describes how to deploy the pipeline optimization service (referred to as `groundswell` in the configuration file) for Seqera Platform Enterprise using Docker Compose. :::info Prerequisites Other than the basic requirements [already listed in the Pipeline Optimization installation overview](./install-groundswell#prerequisites), you will need: - Docker Engine and Docker Compose ::: ## New installation 1. Set the `TOWER_ENABLE_GROUNDSWELL` environment variable in `tower.env` to `true`. This enables the service at the default URL `http://groundswell:8090`. To use a custom URL, set `GROUNDSWELL_SERVER_URL` instead. 2. In your [docker-compose.yml](./_templates/docker/docker-compose.yml) file, uncomment the `groundswell` section. 3. To create a schema on the local MySQL container, uncomment the `init.sql` script in the `volumes` section. 4. Download the [init.sql](./_templates/docker/init.sql) file and store it in the mount path of your `docker-compose.yml`. 5. Start your Platform instance: ```bash docker compose up -d ``` ## Existing installation 1. Set the `TOWER_ENABLE_GROUNDSWELL` environment variable in `tower.env` to `true`. To use a custom URL, set `GROUNDSWELL_SERVER_URL` instead. 1. In your [docker-compose.yml](./_templates/docker/docker-compose.yml) file, uncomment the `groundswell` section. 1. Download the [groundswell.env](./_templates/docker/groundswell.env) file and update the database URLs: ```env TOWER_DB_URL=mysql://db:3306/tower SWELL_DB_URL=mysql://db:3306/swell ``` 1. Restart your Platform instance: ```bash docker compose up -d ``` ## Verify When pipeline optimization is active, pipelines with at least one successful run display a lightbulb icon in the Launchpad. ## Configuration See [Pipeline optimization](./configuration/pipeline_optimization) for additional configuration options. --- ## Pipeline Optimization: Helm [Helm](https://helm.sh) is an open-source command line tool used for managing Kubernetes applications. Seqera offers a [Helm chart](https://github.com/seqeralabs/helm-charts/tree/pipeline-optimization-0.2.4/platform/charts/pipeline-optimization) to deploy Pipeline Optimization Enterprise on a Kubernetes cluster. :::info Prerequisites Other than the basic requirements [already listed in the Pipeline Optimization installation overview](./install-groundswell#prerequisites), you will need: - A Kubernetes cluster - [Helm v3](https://helm.sh/docs/intro/install) and [kubectl](https://kubernetes.io/docs/tasks/tools/) installed locally ::: ## Installation as part of Seqera Platform Enterprise The Pipeline Optimization Helm chart has been designed as a sub-chart of the main Seqera Platform Enterprise Helm chart, but can optionally be installed independently like the Platform chart. To install Pipeline Optimization as part of your Seqera Platform Enterprise deployment, make sure the `pipeline-optimization.enabled` value in your custom Platform's `values.yaml` file is set to `true`: ```yaml pipeline-optimization: enabled: true ``` At the same time, configure the desired Pipeline Optimization options as described in the [Pipeline Optimization Helm chart documentation](https://github.com/seqeralabs/helm-charts/tree/pipeline-optimization-0.2.4/platform/charts/pipeline-optimization), in particular the Pipeline Optimization and Platform databases. Also refer to the [example](https://github.com/seqeralabs/helm-charts/tree/pipeline-optimization-0.2.4/platform/examples/pipeline-optimization) provided in the Helm charts repository. Then, follow the instructions in the Seqera Platform Enterprise installation guide [using Helm](./platform-helm) to install or upgrade your Platform deployment with Pipeline Optimization. --- ## Pipeline optimization: Kubernetes This guide describes how to deploy the pipeline optimization service (referred to as `groundswell` in the configuration file) for Seqera Platform Enterprise on Kubernetes. :::info Prerequisites Other than the basic requirements [already listed in the Pipeline Optimization installation overview](./install-groundswell#prerequisites), you will need: - A Kubernetes cluster - [kubectl](https://kubernetes.io/docs/tasks/tools/) installed locally ::: ## Procedure 1. Download the [groundswell manifest](./_templates/k8s/groundswell.yml). 1. Set `TOWER_ENABLE_GROUNDSWELL=true` in your `configmap.yml`. To use a custom URL, set `GROUNDSWELL_SERVER_URL` instead. 1. Update the Groundswell ConfigMap (`tower-groundswell-cfg`) with your database credentials. 1. Apply the manifests: ```bash kubectl apply -f configmap.yml kubectl apply -f groundswell.yml ``` 1. Restart the backend: ```bash kubectl rollout restart deployment/backend ``` The initContainers process waits for both databases to be ready before starting the migration and optimization service. ## Verify When pipeline optimization is active, pipelines with at least one successful run display a lightbulb icon in the Launchpad. ## Configuration See [Pipeline optimization](./configuration/pipeline_optimization) for additional configuration options. --- ## Pipeline optimization(Enterprise) Pipeline optimization (Groundswell) uses resource usage data from previous workflow runs to optimize subsequent runs. Deploy after your Platform installation is complete. ## Deployment options | Method | Guide | | :----- | :---- | | Helm | [Pipeline optimization: Helm](./groundswell-helm) | | Kubernetes | [Pipeline optimization: Kubernetes](./groundswell-kubernetes) | | Docker Compose | [Pipeline optimization: Docker Compose](./groundswell-docker-compose) | See each deployment guide for detailed requirements. For an example TLS configuration for the pipeline optimization databases, see the [helm charts repository](https://github.com/seqeralabs/helm-charts/tree/master/charts/platform/examples). ## Prerequisites :::info Before you begin, you need: - A running Seqera Platform Enterprise deployment - A MySQL 8 database separate from the one used by Seqera Platform * For example, to create a new database schema `pipeline_optimization` and user called `pipeline_optimization_admin`, you can run the following SQL commands: ```sql CREATE DATABASE IF NOT EXISTS `pipeline_optimization`; CREATE USER 'pipeline_optimization_admin'@'%' IDENTIFIED BY 'set_a_secure_password_here'; GRANT ALL PRIVILEGES ON `pipeline_optimization`.* TO 'pipeline_optimization_admin'@'%'; FLUSH PRIVILEGES; ``` - Access to the Seqera Enterprise MySQL database (Pipeline Optimization requires direct access to the Seqera database to read workflow execution data) * Read-only access is sufficient * For example, to create a read-only user called `pipeline_optimization_ro` and let it access your Seqera Enterprise database called `seqera_enterprise`, you can run the following SQL commands: ```sql CREATE USER 'pipeline_optimization_ro'@'%' IDENTIFIED BY 'set_a_secure_password_here'; GRANT SELECT ON `seqera_enterprise`.* TO 'pipeline_optimization_ro'@'%'; FLUSH PRIVILEGES; ``` ::: ## Configuration See [Pipeline optimization](./configuration/pipeline_optimization) for additional configuration options. --- ## Platform Seqera Platform Enterprise can be deployed using Docker Compose, Kubernetes, or Helm. ## Deployment options | Method | Use case | | :----- | :------- | | [Helm](./platform-helm) | Kubernetes deployments using Helm charts | | [Kubernetes](./platform-kubernetes) | Production workloads requiring high availability | | [Docker Compose](./platform-docker-compose) | Evaluation, development, small production workloads | See each deployment guide for detailed requirements. ## Prerequisites :::info Before you begin, you need: - A MySQL 8 database - A Redis 7 instance :::note MySQL 8 is the only supported database version from Seqera Enterprise version 23.4 onwards. MySQL 5.6 and 5.7 are not supported. ::: ::: --- ## Co-Scientist :::caution Co-Scientist requires Seqera Platform Enterprise 25.3.6 or later. This guide covers the Enterprise 26.1 deployment path for the agent backend, MCP server, web interface, and Seqera CLI. It is currently only available on AWS. ::: Deploy the agent backend, Seqera MCP server, and web interface alongside Platform to provide Co-Scientist assistance for workflows, data, projects, and Platform resources in the Seqera CLI and browser. The MCP, agent backend, and portal web Helm charts provide the option to define Kubernetes ingresses. Other methods to expose the services can be used, e.g. via the `extraDeploy` resource. ## Prerequisites Before you begin, make sure you have: - Seqera Platform Enterprise 25.3.6 or later deployed with the [Seqera Platform Helm chart](./platform-helm.md). - Helm v3 and `kubectl` installed locally. - DNS names and TLS certificates for the Platform, agent backend, MCP server, and portal web interface hosts. By default, the Helm charts derive `mcp.`, `ai-api.`, and `ai.`. Override `global.mcpDomain`, `global.agentBackendDomain`, and `global.portalWebDomain` if you use different hostnames. - Access to pull the images required by the Helm charts from the configured container registry, or mirrored copies in your internal registry. See [Seqera container images](./advanced-topics/seqera-container-images.md) and [Mirroring container images](./configuration/mirroring.md). - A MySQL 8.4 LTS-compatible database for the agent backend. You can use the same MySQL instance as Platform with a separate database and user, or a separate instance. - A Redis 7.2-compatible or Valkey 7.2-compatible instance for agent backend task coordination. - A stable Fernet token encryption key for the agent backend if you use Kustomize. Helm-only installs can let the chart generate this key, but explicitly setting it avoids accidental regeneration. - Access to a supported Claude inference provider. AWS Bedrock is recommended for Enterprise deployments; direct Anthropic API access is also supported. - If you use AWS Bedrock, access to the required Claude model or inference profile and the Amazon Titan embedding model. See AWS documentation to [add or remove access to Amazon Bedrock foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html). - If you use direct Anthropic API access, an Anthropic API key stored in a Kubernetes Secret. Generate a Fernet token encryption key when you set the key manually: ```bash # using uv Python package manager (installed if not available) uv --version >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh uv run --with cryptography python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" # using Python directly, cryptography dependency module must be installed in environment python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" ``` Store database passwords, Redis or Valkey passwords, OIDC token values, image pull credentials, and encryption keys in Kubernetes Secrets. Reference those Secrets from Helm values instead of committing plaintext values. ## Inference providers Co-Scientist supports two Claude inference providers. AWS Bedrock is recommended for Enterprise deployments, especially when inference must run in your AWS account or your organization wants to avoid direct egress to Anthropic. Direct Anthropic API access remains supported when your organization has approved that integration. | Inference provider | Description | | --- | --- | | AWS Bedrock | Recommended. Runs Claude inference in your AWS account through Bedrock. | | Anthropic API | Uses Anthropic-hosted Claude models through an Anthropic API key. | Documentation semantic search is configured separately from chat inference. Use Amazon Titan embeddings through Bedrock when you enable improved documentation search. ## Components | Component | Description | | --- | --- | | Agent backend | FastAPI and LangGraph service that orchestrates Co-Scientist sessions, validates Platform tokens, calls the configured inference provider, connects to MCP, and streams Server-Sent Events (SSE) to clients. | | Seqera MCP server | Model Context Protocol server that exposes Platform-aware tools for workflows, datasets, compute environments, Wave, Hub, and nf-core. | | Portal web interface | Browser interface for Co-Scientist chat, projects, thread history, report viewing, and related Platform workflows. | | MySQL | Agent backend database for sessions, threads, token usage records, and conversation history. | | Redis or Valkey | Agent backend queue and coordination store. | ## Deployment topology The recommended Enterprise topology is using the `platform` Seqera Helm chart with the `mcp`, `agent-backend`, and `portal-web` subcharts enabled. The Platform Helm chart automatically wires the MCP OIDC client registration token from the Platform backend secret, reducing the number of manual steps required. Use separate Helm releases when you cannot convert your existing Platform installation to using the Helm chart or your environment requires separate lifecycle ownership. If you deploy the charts separately, you must manually configure: - `global.platformServiceAddress` and `global.platformServicePort` on each AI chart so they can reach the Platform backend service using the cluster-internal endpoint. - `oidcToken.existingSecretName` and `oidcToken.existingSecretKey` with the same OIDC client registration token configured for the Platform backend. - Matching external DNS and TLS for `global.mcpDomain`, `global.agentBackendDomain`, and `global.portalWebDomain`. ## Configure Helm values Enable the three Co-Scientist subcharts in your Platform values file. This example uses the Platform parent chart, so the same Helm release also deploys or upgrades Platform. Include the required Platform values from your existing installation in addition to these Co-Scientist values. ```yaml global: platformExternalDomain: platform.example.com mcpDomain: mcp.platform.example.com agentBackendDomain: ai-api.platform.example.com portalWebDomain: ai.platform.example.com mcp: enabled: true agent-backend: enabled: true portal-web: enabled: true ``` For a complete example, see the [Co-Scientist Helm example](https://github.com/seqeralabs/helm-charts/tree/master/charts/platform/examples/seqera-ai). ## Configure MCP When MCP runs under the Platform parent chart, leave `mcp.oidcToken` unset unless you need to override the default wiring. The parent chart sets it to the Platform backend secret key `OIDC_CLIENT_REGISTRATION_TOKEN`. ## Configure the agent backend The agent backend needs MySQL, Redis or Valkey, inference provider access, MCP connectivity, and a stable token encryption key. In this example sensitive values (db and redis passwords, token encryption key, etc) are stored in a Kubernetes secret named `seqera-ai-secrets`, which needs to already exist before the chart installation, either created manually or with automated secret extraction tools (like External Secrets, not covered in this tutorial). Declare which provider serves each capability using `inference.provider`, `embeddings.provider`, and `sandbox.provider`. `inference.provider` is required; `embeddings.provider` and `sandbox.provider` are optional. Leave them empty to disable those features. The `bedrock` block holds credentials and configuration shared across all Bedrock-backed services, with per-service overrides available when needed. The following example shows a full Bedrock configuration with embeddings and AgentCore sandbox enabled. For Anthropic inference, see the note after the example. ```yaml agent-backend: enabled: true # -- Database database: host: mysql.example.com name: agent_backend username: agent_backend existingSecretName: seqera-ai-secrets existingSecretKey: AGENT_BACKEND_DB_PASSWORD # -- Redis or Valkey redis: host: redis.example.com db: 0 existingSecretName: seqera-ai-secrets existingSecretKey: AGENT_BACKEND_REDIS_PASSWORD tokenEncryptionKeyExistingSecretName: seqera-ai-secrets # -- Provider routing: declare which provider serves each capability inference: provider: bedrock # required; "bedrock" or "anthropic" embeddings: provider: bedrock # optional; omit to disable documentation search sandbox: provider: bedrock # optional; omit to disable AgentCore sandbox sessions # -- Bedrock configuration bedrock: # Default credentials applied to all Bedrock-backed services unless overridden per-service. # Use this when inference, embeddings, and sandbox all share the same role and region. default: assumeRoleArn: arn:aws:iam:::role/ region: inference: # Anthropic inference profile ARN on Bedrock. anthropicModel: arn:aws:bedrock:::inference-profile/ embeddings: model: amazon.titan-embed-text-v2:0 sandbox: # AgentCore runtime ARN — required when sandbox.provider is "bedrock". runtimeArn: arn:aws:bedrock-agentcore:::runtime/ ``` Use `bedrock.default.assumeRoleArn` when the pod must assume a role to access Bedrock services. Leave it empty when the pod already has direct AWS credentials for the target account. Per-service overrides (`bedrock.inference.assumeRoleArn`, `bedrock.embeddings.assumeRoleArn`, `bedrock.sandbox.assumeRoleArn`) are available when different roles are required per capability. To use direct Anthropic API access instead of Bedrock for inference, replace the `inference` and `bedrock.inference` blocks above with the following, and add the `anthropic` block. Bedrock embeddings can still be enabled alongside Anthropic inference: ```yaml inference: provider: anthropic anthropic: existingSecretName: seqera-ai-secrets embeddings: provider: bedrock bedrock: default: assumeRoleArn: arn:aws:iam:::role/ region: embeddings: model: amazon.titan-embed-text-v2:0 ``` Use direct Anthropic API access only when your organization has approved Anthropic-hosted Claude models. ## Configure the portal web interface The portal web chart serves the browser interface and proxies requests to the agent backend. It authenticates users through Seqera Platform. ```yaml portal-web: enabled: true ``` ## Install or upgrade Run Helm with your Platform values and Co-Scientist overrides: ```bash helm upgrade --install seqera oci://public.cr.seqera.io/charts/platform \ --namespace seqera \ --values values.yaml ``` After installation, verify the pods are ready: ```bash kubectl get pods -n seqera -l app.kubernetes.io/component=mcp kubectl get pods -n seqera -l app.kubernetes.io/component=agent-backend kubectl get pods -n seqera -l app.kubernetes.io/component=portal-web ``` ## Verify the installation Check the public endpoints: ```bash curl -i https://ai-api.platform.example.com/health curl -i https://mcp.platform.example.com/health curl -i https://mcp.platform.example.com/service-info curl -I https://ai.platform.example.com ``` The agent backend `/health` endpoint returns `200 OK` when the service starts and required dependencies are reachable. The MCP server exposes `/health` for reachability and `/service-info` for server and protocol information. The portal web interface does not expose a matching `/service-info` endpoint; use the HTTP response and browser sign-in test to confirm it is reachable. Open the portal web interface, for example `https://ai.platform.example.com`, and sign in with your Platform account. A successful login confirms that Platform OIDC, portal web, and the agent backend are connected. Start a chat in the interface to test the inference provider configuration; if sandboxing was configured, try asking a specific question that would trigger a sandbox execution, e.g. `What's the accurate square root of 98723516236?`, which should prompt the model to write a small Python script that should run in the sandbox. ## Connect the Seqera CLI to Co-Scientist There are two options available to install Seqera CLI: Once Platform is installed with agent-backend and portal-web enabled, use the install endpoint to install CLI: ``` curl -fsSL https:///install | bash curl -fsSL https://ai.platform.example.com/install | bash ``` For automated environments, use a Platform access token instead of browser login. ```bash export TOWER_ACCESS_TOKEN= seqera ai ``` Set `SEQERA_AUTH_CLI_CLIENT_ID` only for OAuth deployments that use a non-default CLI client ID. `SEQERA_ACCESS_TOKEN` and `TOWER_ACCESS_TOKEN` are supported for token-based authentication. Install the CLI from the official [`seqera` npm package](https://www.npmjs.com/package/seqera): ```bash npm install -g seqera ``` Point the CLI at your Enterprise deployment: ```bash export SEQERA_AUTH_DOMAIN=https://platform.example.com/api export SEQERA_AI_BACKEND_URL=https://ai-api.platform.example.com seqera ai ``` Set `SEQERA_AUTH_CLI_CLIENT_ID` only if your deployment uses a CLI OAuth client ID other than the default `seqera_ai_cli`. For automated environments, use a Platform access token instead of browser login. Current CLI builds still require `SEQERA_AUTH_DOMAIN` so the CLI can target the correct Enterprise Platform authority. ```bash export SEQERA_AUTH_DOMAIN=https://platform.example.com/api export TOWER_ACCESS_TOKEN= export SEQERA_AI_BACKEND_URL=https://ai-api.platform.example.com seqera ai ``` Set `SEQERA_AUTH_CLI_CLIENT_ID` only for OAuth deployments that use a non-default CLI client ID. `SEQERA_ACCESS_TOKEN` and `TOWER_ACCESS_TOKEN` are supported for token-based authentication. ## Usage and cost Usage and inference costs are managed by your organization through the configured inference provider, such as AWS Bedrock or Anthropic API. ## Security considerations - Use HTTPS for every exposed hostname. - Store all sensitive values in Kubernetes Secrets. - Keep the agent backend Fernet token encryption key stable across upgrades. Changing it prevents the backend from decrypting existing encrypted values. - For user-scoped operations, MCP uses the signed-in user's Platform token to call Platform APIs. Do not configure a shared administrator token for these calls. - Use a separate MySQL database and user for the agent backend, even if they are hosted on the same MySQL instance as Platform. - Enable Redis or Valkey TLS and MySQL TLS when your managed services require encrypted connections. ## Learn more - [Co-Scientist in the Seqera CLI](../co-scientist/index.md): Co-Scientist documentation. - [Co-Scientist Helm example](https://github.com/seqeralabs/helm-charts/tree/master/charts/platform/examples/seqera-ai): Example Platform values for the Co-Scientist subcharts. - [Agent backend chart](https://github.com/seqeralabs/helm-charts/tree/master/charts/platform/charts/agent-backend): Full agent backend values reference. - [MCP chart](https://github.com/seqeralabs/helm-charts/tree/master/charts/platform/charts/mcp): Full MCP values reference. - [Portal web chart](https://github.com/seqeralabs/helm-charts/tree/master/charts/platform/charts/portal-web): Full portal web values reference. --- ## Studios Studios provides interactive analysis environments within Seqera Platform. Deploy Studios after your Platform installation is complete. ## Deployment options | Method | Guide | | :----- | :---- | | Helm | [Studios: Helm](./studios-helm) | | Kubernetes | [Studios: Kubernetes](./studios-kubernetes) | | Docker Compose | [Studios: Docker Compose](./studios-docker-compose) | See each deployment guide for detailed requirements. ## Prerequisites :::info Before you begin, you need: - A running Seqera Platform Enterprise deployment at hostname `example.com` or `platform.example.com` - A Redis 7 instance separate from the one used by Seqera Platform - TLS certificates for the Studios subdomains `*.connect.example.com` * A single certificate covering both Platform and Studios subdomains can be used; if preferring to use separate certificates, you may need to configure a separate ingress when working with plain Kubernetes manifests (the Studios Helm chart already uses separate ingresses) * The Studios subdomain must share the same "root domain" with the Platform installation, for example with Platform installed at `example.com` or `platform.example.com`, Studios can be installed at: - `connect.example.com` or using another name such as `studios.example.com` - `connect.platform.example.com` - `connect.another.subdomain.example.com` - A wildcard DNS record covering the Studios subdomains, e.g., `*.connect.example.com` - Data Explorer enabled in your Seqera Platform instance (automatic with Helm deployments) ::: ## Connect environment variables These are the environment variables used to configure the components of Connect. | Environment variable | Default | Required | Used by | Description | |------------------------------------------|-----------------------------|------------|--------------|---------------------------------------------------------------------------------------------------| | `CONNECT_REDIS_ADDRESS` | `redis:6379` | yes | server,proxy | The address of the Redis server. Default applies to the server; the proxy requires it explicitly. | | `CONNECT_REDIS_USER` | | no | server,proxy | The username to authenticate with Redis. | | `CONNECT_REDIS_PASSWORD` | | no | server,proxy | The password to authenticate with Redis. | | `CONNECT_REDIS_DB` | `0` | no | server,proxy | The Redis database to use. | | `CONNECT_REDIS_PREFIX` | `connect:session` | no | server,proxy | A prefix to use for tunnel keys in Redis. | | `CONNECT_REDIS_TLS_ENABLE` | `false` | no | server,proxy | Enable TLS connection. | | `CONNECT_REDIS_TLS_SKIP_VERIFY` | `false` | no | server,proxy | Sets the insecure skip verify TLS option. | | `CONNECT_REDIS_TLS_KEY_FILE` | | no | server,proxy | The path to a certificate key file for TLS connection. | | `CONNECT_REDIS_TLS_CERT_FILE` | | no | server,proxy | The path to a certificate file for TLS connection. | | `CONNECT_LISTENER_PORT` | `7777` | no | server | The port where the server listens for connections. | | `CONNECT_TUNNEL_PORT` | `7070` | no | server | The port to open a new tunnel. | | `CONNECT_MANAGEMENT_PORT` | | no | server,proxy | The port where the server listens for metrics, readiness, and shutdown. | | `CONNECT_MANAGEMENT_AUTH_KEY` | | no | server | Auth key protecting the management service endpoints. | | `CONNECT_HOST_DOMAIN` | | no | server | The host domain suffix for the server. | | `CONNECT_HTTP_PORT` | `80` | no | proxy | The port where the proxy listens for incoming connections. | | `CONNECT_PROXY_URL` | | yes | proxy | The base domain name of Connect. | | `CONNECT_TUNNEL_URL` | | yes | proxy | The address of the connect server. Format: `:`. | | `PLATFORM_URL` | | yes | proxy | The base URL of Seqera Platform. | | `CONNECT_STORAGE_ROOT` | `/data` | no | proxy | The root directory to store the proxy data. | | `CONNECT_LOG_LEVEL` | `INFO` | no | server,proxy | Log level for the server and proxy. | | `CONNECT_CLIENT_NAME` | `tower-connect-proxy-client` | no | proxy | OIDC client name used by the proxy's Studio provider. | | `CONNECT_GRANT_TYPE` | `authorization_code` | no | proxy | OAuth grant type used by the proxy's Studio provider. | | `CONNECT_OIDC_CLIENT_REGISTRATION_TOKEN` | | no | proxy | OIDC initial access token used by the proxy. | | `LOCAL_CACHE_TTL` | `2m` | no | proxy | TTL for the proxy's local session cache before syncing with redis. | | `CONNECT_SSH_ENABLED` | `false` | no | proxy | Enable the SSH proxy server. | | `CONNECT_SSH_ADDR` | `:2222` | no | proxy | The address the SSH proxy server listens on. | | `CONNECT_SSH_KEY_PATH` | | no | proxy | Path to SSH host key file. Takes precedence over `CONNECT_SSH_KEY_VALUE_BASE64` when set. | | `CONNECT_SSH_KEY_VALUE_BASE64` | | no | proxy | Base64-encoded PEM SSH host key. Used as fallback when `CONNECT_SSH_KEY_PATH` is not set. | | `CONNECT_SSH_MAX_CONNECTIONS` | `2000` | no | proxy | Max number of concurrent ssh connections that the server will handle before start rejecting them. | | `CONNECT_SSH_MAX_CONN_CHANNELS` | `30` | no | proxy | Max number of concurrent channels that a client can open per connection. | | `CONNECT_SSH_HANDSHAKE_TIMEOUT` | `1m` | no | proxy | SSH handshake timeout. | | `CONNECT_TRUSTED_PROXY_CIDRS` | `127.0.0.1/32` | no | proxy | Space-separated CIDRs of trusted upstream proxies, used to resolve the real client IP from `X-Forwarded-For` for per-IP telemetry. Default is a no-op loopback range. See [Studios data transfer quotas](./studios-transfer-quotas). | | `CONNECT_POLICY_B64` | | no | proxy | Base64-encoded JSON traffic policy. Empty or unset disables telemetry and quota enforcement. Mutually exclusive with `CONNECT_POLICY_FILE`. See [Studios data transfer quotas](./studios-transfer-quotas). | | `CONNECT_POLICY_FILE` | | no | proxy | Path to a JSON traffic policy file. Mutually exclusive with `CONNECT_POLICY_B64`. | | `CONNECT_TELEMETRY_FLUSH_INTERVAL` | `30s` | no | proxy | How often the proxy writes in-memory byte counters to Redis. | | `CONNECT_TELEMETRY_TTL` | `168h` | no | proxy | TTL for cumulative per-bucket telemetry keys in Redis (7 days). | | `CONNECT_TELEMETRY_STREAM_EMIT_INTERVAL` | `1s` | no | proxy | How often long-lived streams (WebSocket and SSH) report transferred bytes. | ## DNS configuration Each Studio is reachable at a unique URL that includes a randomly generated subdomain name. For example: `https://abcd.connect.example.com/`, where `connect.example.com` is the Studios service domain. Provide a wildcard TLS certificate to allow for uniquely generated subdomains. A wildcard certificate common name includes `*.` in the domain name, such as `*.connect.example.com`, thereby securing any subdomain name at this level. Studios uses the following set of domains and subdomains: - The Platform domain that you set for `TOWER_SERVER_URL`, such as `example.com`. - A wildcard subdomain that you must configure specifically for Studios. This wildcard subdomain is the parent for each unique session URL, such as `abcd.connect.example.com`. - The connection proxy, defined by `CONNECT_PROXY_URL`. This URL is a first-level subdomain of your `TOWER_SERVER_URL`. For example, `https://connect.example.com`. ## Studios workspace availability You can configure which organizational workspaces have access to Studios by setting the `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES` environment variable on the backend containers. By default, all workspaces have access to Studios. To restrict access to specific workspaces, set `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES` to a comma-separated list of workspace names. For example, `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES="12345,67890"` allows only the workspaces named `12345` and `67890` to access Studios. To disable access to Studios for all workspaces, set `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES=""` (an empty string). ## Available Studios environment images Each of the provided environments includes a particular version of the underlying software package and the version of Seqera Connect, an integrated web- and file-server. To quickly identify which version of the software an image includes, the version string for each container is in the form of `-`. For example, if the version string for the R-IDE is `2025.04.1-0.12`, version `2025.04.01` is the R-IDE version and `0.12` is the Connect version of this Seqera-built container image. Learn more about Studios [environment versioning](../studios/container-images). - To see the list of all JupyterLab image templates available, including security scan results or to inspect the container specification (including container specifications, configuration, and manifest), see [public.cr.seqera.io/repo/platform/data-studio-jupyter][ds-jupyter]. - To see the list of all R-IDE image templates available, including security scan results or to inspect the container specification (including container specifications, configuration, and manifest), see [https://public.cr.seqera.io/repo/platform/data-studio-ride][ds-ride]. - To see the list of all Visual Studio Code image templates available, including security scan results or to inspect the container specification (including container specifications, configuration, and manifest), see [public.cr.seqera.io/platform/data-studio-vscode][ds-vscode]. - To see the list of all Xpra image templates available, including security scan results or to inspect the container specification (including container specifications, configuration, and manifest), see [public.cr.seqera.io/repo/platform/data-studio-xpra][ds-xpra]. ## Path-based routing configuration If your Enterprise deployment requires non-wildcard SSL certificates, enable path-based routing for Studios. This changes the dynamic subdomain used for each Studios session to a fixed subdomain with path-based routing. - When `TOWER_DATA_STUDIO_ENABLE_PATH_ROUTING` is omitted, empty, or `false`, the Studios session URLs use unique subdomains: - https://a1234abc.connect.cloud.seqera.io/ - https://a5678abcd.connect.cloud.seqera.io/ - When `TOWER_DATA_STUDIO_ENABLE_PATH_ROUTING=true`, the Studios session URLs use path-based routing: - https://connect.connect.cloud.seqera.io/_studio/a1234abc - https://connect.connect.cloud.seqera.io/_studio/a5678abcd Path-based routing is only available from Seqera Platform version 25.2 and the latest Connect server and clients. It is supported for Visual Studio Code, JupyterLab, and R-IDE container template images. It is not supported for the Xpra container template image. {/* links */} [ds-jupyter]: https://public.cr.seqera.io/repo/platform/data-studio-jupyter [ds-ride]: https://public.cr.seqera.io/repo/platform/data-studio-ride [ds-vscode]: https://public.cr.seqera.io/repo/platform/data-studio-vscode [ds-xpra]: https://public.cr.seqera.io/repo/platform/data-studio-xpra --- ## Enterprise installation :::tip Seqera Enterprise requires a license. If you have not already purchased a license, [contact us](https://seqera.io/contact-us/) for more information. ::: Seqera Platform Enterprise is a web application with a microservice-oriented architecture that is designed to maximize portability, scalability, and security. It's composed of several modules that are configured and deployed according to your organizational requirements. Seqera provides these modules as Docker container images that are securely hosted on a private container registry. ## Architecture ![Platform architecture diagram](./_images/seqera_reference_architecture.png) ### Platform backend The Seqera backend is a JVM-based web application based on the [Micronaut](https://micronaut.io/) framework, which provides a modern and secure backbone for the application. The backend implements the main application logic, which is exposed via a REST API and defined with an OpenAPI schema. The backend uses JPA, Hibernate, and JDBC API industry standards to interact with the underlying relational database. The backend can be run standalone or as multiple replicas for scalability when deployed in high-availability mode. It should run on port `8080`. ### Platform cron Cron is an auxiliary backend service that executes regularly-occurring activities, such as sending email notifications and cleaning up stale data. The cron service also performs database migrations at startup. ### Platform frontend The Seqera frontend is an NGINX web server that serves the [Angular](https://angular.io/) application and reverse-proxies HTTP traffic to the backend. The frontend should run on port `80` within the container and should be the only service that accepts incoming HTTP traffic. The frontend can also be exposed via HTTPS or a load balancer. ### Redis database Seqera Enterprise requires a Redis database for caching purposes. ### SQL database Seqera requires a SQL database to persist user activities and state. The application has been tested against MySQL 8.0. [Contact Seqera support](https://support.seqera.io) if you need to use a different JDBC-compliant SQL database. :::note From Seqera Enterprise version 23.4: - MySQL 8 is the officially supported and tested database version. - MySQL versions 5.6 and 5.7 are no longer supported. ::: ### SMTP service Seqera requires an SMTP relay to send email messages and user notifications. ### Authentication service (optional) Seqera supports enterprise authentication mechanisms such as OAuth and OpenID. Third-party identity providers and custom single sign-on flows can be developed according to specific customer requirements. ## Deployment options Seqera can be deployed to a single node, either with [Docker Compose](./platform-docker-compose) or natively, or to a [Kubernetes](./platform-kubernetes) cluster. This documentation includes instructions for both options across multiple platforms, including Amazon AWS, Microsoft Azure, Google Cloud, and on-prem infrastructure. ### Single-node The minimal Seqera Enterprise deployment requires only the frontend, backend, and database services. These services can be deployed as Docker containers or as native services. ### Kubernetes Kubernetes is emerging as the technology of choice for deploying applications that require high-availability, scalability, and security. Seqera Enterprise includes configuration manifests for Kubernetes deployment. ![](./_images/seqera_reference_architecture_aws.png) _Reference architecture diagram of Seqera Platform Enterprise on AWS using Elastic Kubernetes Service (EKS)_ ## Application container images Seqera Enterprise is distributed as a collection of Docker containers available through the Seqera container registry [`cr.seqera.io`](https://cr.seqera.io). Contact [support](https://support.seqera.io) to get your container access credentials. ## Support For further information, [contact Seqera support](https://support.seqera.io). --- ## Platform: Docker Compose Docker Compose deployments are suitable for evaluation, development, and small production workloads. :::info Prerequisites Other than the basic requirements [already listed in the Platform installation overview](./install-platform#prerequisites), you will need: - Docker Engine and Docker Compose ::: ## Container images Seqera Enterprise container images are hosted on a private registry (`cr.seqera.io`). Access is provided as part of your purchase. Contact [support](https://support.seqera.io) if you require access. We recommend mirroring these images to your own private container registry for production use. See [Mirroring container images](./configuration/mirroring) for details. ## Database configuration Create a MySQL database and user for Seqera: ```sql CREATE DATABASE tower; CREATE USER 'tower'@'%' IDENTIFIED BY 'your_secure_password'; GRANT ALL PRIVILEGES ON tower.* TO 'tower'@'%'; ``` See [Database configuration](./configuration/overview#seqera-and-redis-databases) for details. ## Redis or Valkey configuration Seqera Platform requires a Redis-compatible cache store for transient data, primarily Nextflow job metrics reporting. Both Redis and Valkey are supported. :::info The bundled `redis` container in `docker-compose.yml` is intended for evaluation and small workloads. For production, use a managed service or an [official Redis installation source](https://redis.io/docs/latest/operate/oss_and_stack/install/). ::: ### Supported versions | Cache / version | Status | | --------------- | ---------------------------- | | Redis 6.x | Not supported (EoL upstream) | | Redis 7.2 | Supported | | Redis 7.4 | Supported | | Valkey 7.x | Supported (from 26.1) | ### Connection URL Configure the connection URL in your Seqera environment using the scheme that matches your cache backend: | Backend | Scheme | Example | | --------------- | ------------ | ---------------------------------------- | | Redis | `redis://` | `TOWER_REDIS_URL=redis://:6379` | | Redis with TLS | `rediss://` | `TOWER_REDIS_URL=rediss://:6380` | The Redisson client embedded in Platform 26.1+ supports Valkey 7 dial schema — no further configuration is required. Redis password and ACL configuration carry over unchanged when migrating to Valkey. ### Managed service options Use a managed cache service for production: - [Amazon ElastiCache](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) (`cache.m4.large` or larger) - [Azure Managed Redis](https://learn.microsoft.com/azure/redis/overview) (production-capable tier appropriate for your workload) - [Google Memorystore](https://cloud.google.com/memorystore/docs/redis) (M2 tier or larger) :::caution Microsoft is retiring Azure Cache for Redis. As of April 1, 2026, new customers cannot create instances, and from October 1, 2026, no new instances can be created. For new Azure deployments, use [Azure Managed Redis](https://learn.microsoft.com/azure/redis/overview). ::: For migration guidance from Redis to Valkey on an existing installation, see [Cache layer changes](./upgrade#cache-layer-changes-redis-eol-and-valkey-support). ## Deploy Seqera Enterprise 1. Download and configure [tower.env](_templates/docker/tower.env). See [Configuration](./configuration/overview.mdx#basic-configuration) for detailed instructions. 2. Download and configure [tower.yml](_templates/docker/tower.yml). See [Configuration](./configuration/overview.mdx#basic-configuration) for detailed instructions. 3. Download and configure the [docker-compose.yml](_templates/docker/docker-compose.yml) file: - The `db` and `redis` containers should be used only for local testing. If you have configured these services elsewhere, you can remove these containers. - To configure the Seqera pipeline optimization service (`groundswell`), see [Pipeline optimization](./configuration/pipeline_optimization). - To deploy with Studios, see [Studios deployment](./install-studios). 4. Deploy the application and wait for it to initialize (this process takes a few minutes): ```bash docker compose up ``` 5. [Test](./testing) the application by running an nf-core pipeline with a test profile. 6. After you've confirmed that Seqera Enterprise is correctly configured and you can launch workflows, run `docker compose up -d` to deploy the application as a background process. You can then disconnect from the VM instance. :::note For more information on configuration, see [Configuration options](./configuration/overview.mdx). ::: #### Seqera frontend unprivileged An unprivileged version of the Seqera frontend image is also available. This image listens on an unprivileged port and therefore doesn't need to be run as the root user. Replace the tag of the frontend image `cr.seqera.io/enterprise/platform/frontend:v24.x.x` with `cr.seqera.io/enterprise/platform/frontend:v24.x.x-unprivileged`. Then update the `frontend` section of the `docker-compose.yml` file as follows, replacing the port mappings as needed: ```yaml frontend: image: cr.seqera.io/enterprise/platform/frontend:v24.x.x-unprivileged platform: linux/amd64 environment: NGINX_LISTEN_PORT: 8001 # If not defined, defaults to 8000 networks: - frontend ports: - 8081:8001 # Map host port 8081 to container port 8001 restart: always depends_on: - backend ``` The unprivileged Seqera image will soon deprecate the current image that requires root. The unprivileged image can be easily customized using environment variables: - `NGINX_LISTEN_PORT`: The port the NGINX process will listen on inside the container. Default: `8000`. - `NGINX_LISTEN_PORT_IPV6`: The NGINX listening port to open on the IPv6 address. Default: `8000`. - `NGINX_UPSTREAM_HOST`: The hostname of the backend service to which the NGINX process will route requests. Default: `backend`. - `NGINX_UPSTREAM_PORT`: The port where the backend service is exposed. Default: `8080`. If further customization of the config file is needed, mount a config map/secret over the templated NGINX configuration file at `/etc/nginx/templates/tower.conf.template`. See [SSL/TLS](./configuration/ssl_tls#configure-seqera-to-present-a-ssltls-certificate) for an example. ## Optional features ### Pipeline optimization Seqera Platform offers a service that optimizes pipeline resource requests. Refer to [Pipeline optimization](./configuration/pipeline_optimization.md) for more information. ### Studios [Studios](../studios/overview) is an interactive analysis environment available in organizational workspaces. To enable Studios, see [Studios deployment](./install-studios). :::note Studios is available from Seqera Platform v24.1. If you experience any problems during the deployment process please contact your account executive. Studios in Enterprise is not installed by default. ::: --- ## Platform: Helm [Helm](https://helm.sh) is an open-source command line tool used for managing Kubernetes applications. Seqera offers a [Helm chart](https://github.com/seqeralabs/helm-charts/tree/platform-0.36.1/charts/platform) to deploy Seqera Platform Enterprise on a Kubernetes cluster. :::info Prerequisites Other than the basic requirements [already listed in the Platform installation overview](./install-platform#prerequisites), you will need: - A Kubernetes cluster - [Helm v3](https://helm.sh/docs/intro/install) and [kubectl](https://kubernetes.io/docs/tasks/tools/) installed locally ::: ## Installing the Helm chart Helm bundles resource definitions into templates for repeatable deployments: inputs can be passed to the Helm chart either via a YAML file or inline to replace the default values. The `values.yaml` file defines a chart's settings, such as container image tags, CPU/memory limits, ingress definition to expose the service, environment variables, etc. Each Helm chart generally comes with its own `values.yaml` file containing default settings, which can be overridden by providing a custom values file. More details about values customization can be found in the [Helm documentation](https://helm.sh/docs/topics/charts#values-files). 1. Fetch the default `values.yaml` file to customize the installation with your specific configuration: ```bash helm show values oci://public.cr.seqera.io/charts/platform --version 0.36.1 > my-values.yaml ``` Now edit the `my-values.yaml` file to set your options, such as internal container image registry, database connection details, license information, and other settings. You can drop lines that you don't want to customize to keep the file concise and only include the settings you want to change: this will make it easier to maintain your configuration in the future. The values you don't specify will fall back to the defaults defined in the chart in the `values.yaml` file. For an example of a minimal configuration file, see the [example values file](https://github.com/seqeralabs/helm-charts/blob/platform-0.36.1/charts/platform/examples/kustomize/values.yaml). You can browse all the available configuration options in a tabular format in the [README](https://github.com/seqeralabs/helm-charts/tree/platform-0.36.1/charts/platform) file. 1. Install the chart from the public OCI registry in your desired namespace and with the values file customized in the previous step: ```bash helm install my-release oci://public.cr.seqera.io/charts/platform \ --version 0.36.1 \ --namespace my-namespace \ --create-namespace \ --values my-values.yaml ``` The chart will fail to install if mandatory values are not provided. ### Installing a Helm chart with Kustomize Kustomize can be used to manage Helm chart installations as well and provides further customization options. To install the Seqera Platform Enterprise Helm chart using Kustomize, check out the [Kustomize example directory](https://github.com/seqeralabs/helm-charts/tree/platform-0.36.1/charts/platform/examples/kustomize). ## Upgrading the Helm chart To upgrade an existing Seqera Platform Enterprise Helm chart installation to a new version, run the following command, replacing `my-release` and `my-namespace` with your release name and namespace: ```bash helm upgrade my-release oci://public.cr.seqera.io/charts/platform \ --version NEW_VERSION \ --namespace my-namespace \ --values my-values.yaml ``` ## Uninstalling the Helm chart To uninstall the Seqera Platform Enterprise Helm chart, run the following command, replacing `my-release` and `my-namespace` with your release name and namespace: ```bash helm uninstall my-release -n my-namespace ``` --- ## Platform: Kubernetes Kubernetes deployments are recommended for production workloads requiring high availability and scalability. :::info Prerequisites Other than the basic requirements [already listed in the Platform installation overview](./install-platform#prerequisites), you will need: - A Kubernetes cluster - [kubectl](https://kubernetes.io/docs/tasks/tools/) installed locally ::: ### Recommended resources | Component | CPU | Memory | | :---------- | :----- | :------------------------ | | Backend pod | 1 core | 4000 Mi request and limit | ## Container images Seqera Enterprise container images are hosted on a private registry (`cr.seqera.io`). Access is provided as part of your purchase. Contact [support](https://support.seqera.io) if you require access. We recommend mirroring these images to your own private container registry for production use. See [Mirroring container images](./configuration/mirroring) for details. For development and proof of concept installations, you can use [image pull secrets](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) to pull directly from the Seqera registry. ## Database configuration Create a MySQL database and user for Seqera: ```sql CREATE DATABASE tower; CREATE USER 'tower'@'%' IDENTIFIED BY 'your_secure_password'; GRANT ALL PRIVILEGES ON tower.* TO 'tower'@'%'; ``` See [Database configuration](./configuration/overview#seqera-and-redis-databases) for details. ## Redis or Valkey configuration Seqera Platform requires a Redis-compatible cache store for transient data, primarily Nextflow job metrics reporting. Both Redis and Valkey are supported. ### Supported versions | Cache / version | Status | | --------------- | ---------------------------- | | Redis 6.x | Not supported (EoL upstream) | | Redis 7.2 | Supported | | Redis 7.4 | Supported | | Valkey 7.x | Supported (from 26.1) | ### Connection URL Configure the connection URL in your Seqera environment using the scheme that matches your cache backend: | Backend | Scheme | Example | | --------------- | ------------ | ---------------------------------------- | | Redis | `redis://` | `TOWER_REDIS_URL=redis://:6379` | | Redis with TLS | `rediss://` | `TOWER_REDIS_URL=rediss://:6380` | The Redisson client embedded in Platform 26.1+ supports Valkey 7 dial schema — no further configuration is required. Redis password and ACL configuration carry over unchanged when migrating to Valkey. ### Managed service options Use a managed cache service for production: - [Amazon ElastiCache](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) (`cache.m4.large` or larger) - [Azure Managed Redis](https://learn.microsoft.com/azure/redis/overview) (production-capable tier appropriate for your workload) - [Google Memorystore](https://cloud.google.com/memorystore/docs/redis) (M2 tier or larger) :::caution Microsoft is retiring Azure Cache for Redis. As of April 1, 2026, new customers cannot create instances, and from October 1, 2026, no new instances can be created. For new Azure deployments, use [Azure Managed Redis](https://learn.microsoft.com/azure/redis/overview). ::: For migration guidance from Redis to Valkey on an existing installation, see [Cache layer changes](./upgrade#cache-layer-changes-redis-eol-and-valkey-support). ## Deploy Seqera Enterprise ### Create a namespace Create a namespace for Seqera resources: ```bash kubectl create namespace seqera-platform kubectl config set-context --current --namespace=seqera-platform ``` ### Seqera ConfigMap Download and configure a [ConfigMap](_templates/k8s/configmap.yml). See [Configuration](./configuration/overview.mdx) for more information. Deploy the ConfigMap to your cluster after it is configured: ```bash kubectl apply -f configmap.yml ``` :::note The `configmap.yml` manifest includes both the `tower.env` and `tower.yml` files. These files are made available to the other containers through volume mounts. ::: ### Seqera cron service Download the [cron service manifest](_templates/k8s/tower-cron.yml) file. To deploy the manifest to your cluster, run the following: ```bash kubectl apply -f tower-cron.yml ``` :::caution This container creates the required database schema the first time it instantiates. This process can take a few minutes to complete and must finish before you instantiate the Seqera backend. Ensure this container is in the `READY` state before proceeding to the next step. ::: ### Seqera frontend and backend Download the [manifest](_templates/k8s/tower-svc.yml). To deploy the manifest to your cluster, run the following: ```bash kubectl apply -f tower-svc.yml ``` #### Seqera frontend unprivileged An unprivileged version of the Seqera frontend image is also available. This image listens on an unprivileged port and therefore doesn't need to be run as the root user. Replace the tag of the frontend image `cr.seqera.io/enterprise/platform/frontend:v24.x.x` with `cr.seqera.io/enterprise/platform/frontend:v24.x.x-unprivileged`. In the `frontend` service below, specify the `targetPort` to match the environment variable `NGINX_LISTEN_PORT` (see below): ```yaml --- apiVersion: apps/v1 kind: Deployment metadata: name: frontend labels: app: frontend spec: ... containers: - name: frontend image: cr.seqera.io/enterprise/platform/frontend:v25.3.0-unprivileged env: - name: NGINX_LISTEN_PORT # If not defined, defaults to 8000. value: 8000 --- apiVersion: v1 kind: Service metadata: name: frontend spec: ports: - port: 80 targetPort: 8000 ``` The external `port` of the `frontend` service is independent of `NGINX_LISTEN_PORT`. Leave the `port` at `80` and change only the `targetPort` to match the port NGINX listens on inside the container: - If `NGINX_LISTEN_PORT` is unset, set `targetPort` to `8000`. - If you set `NGINX_LISTEN_PORT` to another value, set `targetPort` to that value. `NGINX_UPSTREAM_PORT` (default `8080`) sets the backend port that NGINX routes requests to, not the frontend listening port. The unprivileged Seqera image will soon deprecate the current image that requires root. The unprivileged image can be easily customized using environment variables: - `NGINX_LISTEN_PORT` (default `8000`): The port the NGINX process will listen on inside the container. - `NGINX_LISTEN_PORT_IPV6` (default `8000`): The NGINX listening port to open on the IPv6 address. - `NGINX_UPSTREAM_HOST` (default `backend`): The hostname of the backend service to which the NGINX process will route requests. - `NGINX_UPSTREAM_PORT` (default `8080`): The port where the backend service is exposed. If further customization of the config file is needed, mount a config map/secret over the templated NGINX configuration file at `/etc/nginx/templates/tower.conf.template`. See [SSL/TLS](./configuration/ssl_tls#configure-seqera-to-present-a-ssltls-certificate) for an example. ### Seqera ingress An ingress is used to make Seqera Enterprise publicly accessible, load-balance traffic, terminate TLS, and offer name-based virtual hosting. The included ingress manifest will create an external IP address and forward HTTP traffic to the Seqera frontend. Download and configure the appropriate manifest for your infrastructure: - [Amazon EKS](_templates/k8s/ingress.eks.yml) - [Azure AKS](_templates/k8s/ingress.aks.yml) - [Google Kubernetes Engine](_templates/k8s/ingress.gke.yml) To deploy the manifest to your cluster, run the following: ```bash kubectl apply -f ingress.*.yml ``` See [Kubernetes ingress][k8s-ingress] for more information. If you don't need to make Seqera externally accessible, use a service resource to expose a [node port][k8s-node-port] or a [load balancer][k8s-load-balancer] service to make it accessible within your intranet. See the cloud provider documentation for configuring an ingress service on each cloud provider: - [Amazon][aws-configure-ingress] - [Azure][azure-configure-ingress] - [Google Cloud][google-configure-ingress] ### Check status Check that all services are up and running: ```bash kubectl get pods ``` ### Test the application See [Test deployment](./testing). ## Optional features ### Pipeline optimization Seqera Platform offers a service that optimizes pipeline resource requests. Refer to [Pipeline optimization](./configuration/pipeline_optimization.md) for more information. ### Studios [Studios](../studios/overview) is an interactive analysis environment available in organizational workspaces. To enable Studios, see [Studios deployment](./install-studios). :::note Studios is available from Seqera Platform v24.1. If you experience any problems during the deployment process [contact Seqera support](https://support.seqera.io). Studios in Enterprise is not installed by default. ::: ### High availability To configure Seqera Enterprise for high availability, note that: - The `backend` service can be run in multiple replicas - The `frontend` service is replicable, however in most scenarios it is not necessary - The `cron` service may only have a single instance - The `groundswell` service may only have a single instance [aws-configure-ingress]: https://kubernetes-sigs.github.io/aws-load-balancer-controller/v2.2/guide/ingress/annotations/ [azure-configure-ingress]: https://docs.microsoft.com/en-us/azure/application-gateway/ingress-controller-annotations [google-configure-ingress]: https://cloud.google.com/kubernetes-engine/docs/concepts/ingress [k8s-ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/ [k8s-load-balancer]: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer [k8s-node-port]: https://kubernetes.io/docs/concepts/services-networking/service/#nodeport --- ## Studios: Docker Compose This guide describes how to deploy Studios for Seqera Platform Enterprise with Docker Compose. :::info Prerequisites Other than the basic requirements [already listed in the Studios installation overview](./install-studios#prerequisites), you will need: - Docker Engine and Docker Compose ::: ## Procedure 1. Create a folder for Connect metadata: ```bash mkdir -p $HOME/.tower/connect chmod 777 $HOME/.tower/connect ``` 1. Download the Studios [environment configuration file](./_templates/docker/data-studios.env). 1. Create an initial OIDC registration token: ```bash oidc_registration_token=$(openssl rand -base64 32 | tr -d /=+ | cut -c -32) ``` 1. Generate an RSA public/private key pair: ```bash openssl genrsa -out private.pem 2048 openssl rsa -pubout -in private.pem -out public.pem ``` 1. Download the [data-studios-rsa.pem](./_templates/docker/data-studios-rsa.pem) file and replace its contents with the content of your private and public key files (private key on top, public key directly beneath it). Save as `data-studios-rsa.pem` in the same directory as your `docker-compose.yml`. 1. Open `docker-compose.yml` and uncomment the volume mount for the PEM key file for the `backend` and `cron` services: ```yaml volumes: - $PWD/tower.yml:/tower.yml - $PWD/data-studios-rsa.pem:/data-studios-rsa.pem ``` 1. Open `data-studios.env` and set the following: - Uncomment the `connect-proxy` and `connect-server` services. - `PLATFORM_URL`: The same value as `TOWER_SERVER_URL` (e.g., `https://platform.example.com/` or `https://example.com/`). - `CONNECT_PROXY_URL`: A URL for the connect proxy subdomain (e.g., `https://connect.example.com`). - `CONNECT_OIDC_CLIENT_REGISTRATION_TOKEN`: The same value as `oidc_registration_token`. 1. Open `tower.env` and set the following: - `TOWER_DATA_EXPLORER_ENABLED`: Set to `true`. - `TOWER_DATA_STUDIO_CONNECT_URL`: The URL of the Studios connect proxy (e.g., `https://connect.example.com/`). - `TOWER_OIDC_REGISTRATION_INITIAL_ACCESS_TOKEN`: The same value as `oidc_registration_token`. - `TOWER_OIDC_PEM_PATH`: The file path to the PEM certificate (e.g., `/data-studios-rsa.pem`). 1. From Platform v26.1, Studios is enabled by default on all workspaces. To enable Studios on specific workspaces only, set the `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES` environment variable (e.g., `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES="12345,67890"`) on the Platform backend containers. To disable Studios for all workspaces, set `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES=""` (an empty string). 1. Start your Platform instance: ```bash docker compose up -d ``` 1. To confirm that Studios is available, log in to your Platform instance and navigate to an organizational workspace that has Studios enabled. The **Studios** tab is included with the available tabs. ## Tool configuration This guide assumes that all services will be run in the same container as the rest of your Seqera Platform services. If you were using Studios prior to GA (v25.1) please review the `tower.env` file and make sure you are using the latest version which includes a new variable `TOWER_DATA_STUDIO_TEMPLATES__TOOL`. This variable needs to be added to the default/Seqera-provided Studio templates: `TOWER_DATA_STUDIO_TEMPLATES__TOOL: ''` The `TEMPLATE_KEY` can be any string, but the `TOOL_NAME` has to be the template name (`jupyter`/`vscode`/`rstudio`/`xpra`). You can also check the current template configuration using `https://towerurl/api/studios/templates?workspaceId=`. The response should include the `TOOL` configuration and template name (`jupyter`/`vscode`/`rstudio`/`xpra`) - not `custom`. ## Next steps To enable SSH access for Studios, see [Studios: SSH configuration](./studios-ssh). --- ## Studios: Helm [Helm](https://helm.sh) is an open-source command line tool used for managing Kubernetes applications. Seqera offers a [Helm chart](https://github.com/seqeralabs/helm-charts/tree/studios-1.1.3/platform/charts/studios) to deploy Studios Enterprise on a Kubernetes cluster. :::info Prerequisites Other than the basic requirements [already listed in the Studios installation overview](./install-studios#prerequisites), you will need: - A Kubernetes cluster - [Helm v3](https://helm.sh/docs/intro/install) and [kubectl](https://kubernetes.io/docs/tasks/tools/) installed locally ::: ## Installation as part of Seqera Platform Enterprise The Studios Helm chart has been designed as a sub-chart of the main Seqera Platform Enterprise Helm chart, but can optionally be installed independently like the Platform chart. To install Studios as part of your Seqera Platform Enterprise deployment, make sure the `studios.enabled` value in your custom Platform's `values.yaml` file is set to `true`: ```yaml studios: enabled: true ``` At the same time, configure the desired Studios options as described in the [Studios Helm chart documentation](https://github.com/seqeralabs/helm-charts/tree/studios-1.1.3/platform/charts/studios), in particular the Studios service domain and the subdomains that it will use for incoming connections. Also refer to the [example](https://github.com/seqeralabs/helm-charts/tree/studios-1.1.3/platform/examples/studios) provided in the Helm charts repository. Then, follow the instructions in the Seqera Platform Enterprise installation guide [using Helm](./platform-helm) to install or upgrade your Platform deployment with Studios. ## Next steps To enable SSH access for Studios, see [Studios: SSH configuration](./studios-ssh). --- ## Studios: Kubernetes This guide describes how to deploy Studios for Seqera Platform Enterprise on Kubernetes. :::info Prerequisites Other than the basic requirements [already listed in the Studios installation overview](./install-studios#prerequisites), you will need: - A Kubernetes cluster - [kubectl](https://kubernetes.io/docs/tasks/tools/) installed locally ::: ## Tool configuration This procedure describes how to configure Studios for Seqera Enterprise deployments in Kubernetes. If you were using Studios prior to GA (v25.1) please review the `configmap.yaml` file and make sure you are using the latest version which includes a new variable `TOWER_DATA_STUDIO_TEMPLATES__TOOL`. This variable needs to be added to the default/Seqera-provided Studio templates: `TOWER_DATA_STUDIO_TEMPLATES__TOOL: ''` The `TEMPLATE_KEY` can be any string, but the `TOOL_NAME` has to be the template name (`jupyter`/`vscode`/`rstudio`/`xpra`). You can also check the current template configuration using `https://towerurl/api/studios/templates?workspaceId=`. The response should include the `TOOL` configuration and template name (`jupyter`/`vscode`/`rstudio`/`xpra`) - not `custom`. ## Procedure 1. Download the Kubernetes manifests for the Studios service: - [Proxy](./_templates/k8s/data_studios/proxy.yml) - [Server](./_templates/k8s/data_studios/server.yml) 1. Change your Kubernetes context to the namespace where your Platform instance runs: ```bash kubectl config set-context --current --namespace= ``` 1. Edit the `server.yml` file and set the `CONNECT_REDIS_ADDRESS` environment variable to the hostname or IP address of the Redis server configured for Platform. 1. Create an initial OIDC registration token, which can be any secure random string. For example, using openssl: ```bash oidc_registration_token=$(openssl rand -base64 32 | tr -d /=+ | cut -c -32) ``` 1. Edit the `proxy.yml` file and set the following variables: - `CONNECT_REDIS_ADDRESS`: The hostname or IP address of the Redis server configured for Seqera. - `CONNECT_PROXY_URL`: A URL for the connect proxy subdomain (e.g., `https://connect.example.com`). - `PLATFORM_URL`: The base URL for your installation (e.g., `https://platform.example.com/` or `https://example.com/`). - `CONNECT_OIDC_CLIENT_REGISTRATION_TOKEN`: The same value as the `oidc_registration_token` value created previously. 1. Edit the `ingress..yml` file appropriate for your Kubernetes environment: - Uncomment the `host` section at the bottom of the file. - Replace `` with the base domain of your installation. :::note In the case you're using AWS EKS, this assumes that you have an existing Seqera ingress already configured with the following fields: - `alb.ingress.kubernetes.io/certificate-arn`: The ARN of a wildcard TLS certificate that secures the Platform URL and connect proxy URL. For example, if `TOWER_SERVER_URL=https://example.com` and `CONNECT_PROXY_URL=https://connect.example.com`, the certificate must secure `example.com`, and `*.example.com` at the same time; otherwise, you may need to create a second ingress resource specifically for Studios. ::: 1. Generate an RSA public/private key pair. A key size of at least 2048 bits is recommended. In the following example, the `openssl` command is used to generate the key pair: ```bash openssl genrsa -out private.pem 2048 openssl rsa -pubout -in private.pem -out public.pem ``` 1. Download the [data-studios-rsa.pem](./_templates/docker/data-studios-rsa.pem) file and replace its contents with the content of your private and public key files created in the previous step, in the same order (private key on top, public key directly beneath it). 1. Apply a base64 encoding to the PEM file: ```bash base64_pem=$(cat data-studios-rsa.pem | base64 -w0) ``` 1. Create a secret file named `secret.yml`: ```yaml apiVersion: v1 kind: Secret metadata: name: platform-oidc-certs namespace: platform-stage data: oidc.pem: ``` 1. Create the secret: ```bash kubectl apply -f secret.yml ``` 1. Edit the `tower-svc.yml` file and uncomment the `volumes.cert-volume`, `volumeMounts.cert-volume`, and `env.TOWER_OIDC_PEM_PATH` fields. 1. Edit the ConfigMap named `platform-backend-cfg` in the `configmap.yml` by changing the following environment variables: - `TOWER_DATA_STUDIO_CONNECT_URL`: The URL of the Studios connect proxy, such as `https://connect.example.com/`. - `TOWER_OIDC_REGISTRATION_INITIAL_ACCESS_TOKEN`: The same value as the `oidc_registration_token` value created previously. 1. From Platform v26.1, Studios is enabled by default on all workspaces. To enable Studios on specific workspaces only, set the `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES` environment variable (e.g., `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES="12345,67890"`) on the Platform backend containers. To disable Studios for all workspaces, set `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES=""` (an empty string). 1. Apply the updated configuration: ```bash kubectl apply -f configmap.yml ``` 1. Apply the configuration change to Platform: ```bash kubectl apply -f tower-svc.yml ``` 1. Restart the cron service of your deployment to load the updated configuration. For example: ```bash kubectl rollout restart deployment/cron ``` 1. Restart the Platform backend service of your deployment to load the updated configuration. For example: ```bash kubectl rollout restart deployment/backend ``` 1. Apply the updated ingress file and the Studios manifests: ```bash kubectl apply -f ingress..yml proxy.yml server.yml ``` 1. To confirm that Studios is available, log into Seqera and navigate to an organizational workspace that has Studios enabled. The **Studios** tab should be displayed in the sidebar. ## Next steps To enable SSH access for Studios, see [Studios: SSH configuration](./studios-ssh). --- ## Studios SSH configuration (public preview) :::warning[Advanced configuration] Enabling SSH for running Studio sessions requires changes to platform configuration and therefore careful consideration of security and networking. This feature requires network-level changes to your infrastructure that may need coordination with your infrastructure or networking team. Improperly configured SSH access may introduce security vulnerabilities. ::: SSH access enables direct terminal connections to running Studio sessions using standard SSH clients, supporting [VS Code Remote SSH](https://code.visualstudio.com/docs/remote/ssh) and terminal access. ## Version requirements To enable SSH access to running Studio sessions, you need: - **Seqera Platform**: Version 25.3.3 or later - **Connect server and proxy**: Version 0.10.0 or later - **Connect client**: Version 0.10.0 or later If you have pinned Studio container images to specific versions, you will need to [migrate](../studios/managing#migrate-a-studio-from-an-earlier-container-image-template) them to the required Connect client version. :::info Prerequisites - Studios enabled (see [Studios installation](./install-studios)) - Access to Platform configuration - Administrative access to modify your deployment infrastructure - Ability to configure network routing and firewall rules ::: ## Requirements overview To enable SSH access for Studios you need: 1. **SSH key pair**: A key pair for the connect-proxy to authenticate to a Studio 2. **Platform configuration**: Environment variables to enable and configure SSH on the Platform backend pods 3. **Proxy configuration**: Environment variables to enable SSH on the connect-proxy 4. **Network configuration**: Layer 4 (TCP) access to the SSH port on the connect-proxy, typically via a dedicated service that separates SSH traffic from HTTPS traffic :::note Configuration variables are prefixed by service: `TOWER_` for Platform backend, `CONNECT_` for connect-proxy. ::: ## Step 1: Generate SSH key pair SSH access to Studios requires a dedicated SSH key pair that establishes trust between the connect-proxy and Studio containers. This key pair serves two purposes: 1. **Authentication**: The connect-proxy uses the private key to authenticate to SSH servers running in Studio containers 2. **Security validation**: Studio SSH Server can verify that SSH connections originate from your authorized connect-proxy rather than external sources Generate an SSH key pair for the connect-proxy. ```bash # Generate key ssh-keygen -t ed25519 -C "connect-proxy" -f /path/to/connect-proxy-key # Generate fingerprint ssh-keygen -lf /path/to/connect-proxy-key ``` Platform uses the fingerprint output (SHA256 hash) in configuration to enable an additional security layer. After you configure this fingerprint, Studio SSH servers only accept connections from clients presenting this specific key, preventing unauthorized SSH access. :::warning[Key consistency] All Connect proxy instances must use a **shared SSH key** to prevent host key verification errors. In high availability deployments, ensure all replicas access the shared key. ::: ### Key distribution The SSH private key must be securely stored and accessible to all connect-proxy service instances. The method for distributing and mounting the key depends on your deployment platform's secrets management capabilities. ## Step 2: Configure Platform Add the following environment variables to your Platform backend configuration. All Platform configuration variables use the `TOWER_` prefix: ```yaml TOWER_DATA_STUDIO_CONNECT_SSH_KEY_FINGERPRINT: "SHA256:NEu6MAPGJpImFJ3raQzv6+NubCPy/92hqR+CVyMjKvM" TOWER_DATA_STUDIO_SSH_ALLOWED_WORKSPACES: "12345,67890" TOWER_SSH_KEYS_MANAGEMENT_ENABLED: "true" TOWER_DATA_STUDIO_CONNECT_SSH_PORT: "2222" TOWER_DATA_STUDIO_CONNECT_SSH_ADDRESS: "" ``` **Configuration details:** - `TOWER_DATA_STUDIO_CONNECT_SSH_KEY_FINGERPRINT`: SSH key fingerprint from Step 1. After you configure this fingerprint, Studio SSH servers only accept connections using this key. This rejects connections not originating from your connect-proxy (recommended for security). - `TOWER_DATA_STUDIO_SSH_ALLOWED_WORKSPACES`: Comma-separated workspace IDs allowed to use SSH. Set to an empty string to enable for all Platform Workspaces. Don't set the environment variable to disable the feature entirely. - `TOWER_SSH_KEYS_MANAGEMENT_ENABLED`: Set to `true` to enable SSH key management in Platform. - `TOWER_DATA_STUDIO_CONNECT_SSH_PORT`: SSH port (must match proxy configuration). - `TOWER_DATA_STUDIO_CONNECT_SSH_ADDRESS`: Set this when SSH traffic uses a different DNS address than the regular connect URL. Use this when SSH traffic needs to bypass Layer 7 load balancers used for HTTPS traffic. If not set, the regular connect URL is used for SSH. ## Step 3: Configure proxy Add the following configuration to the connect-proxy service. All connect-proxy configuration variables use the `CONNECT_` prefix: **Environment variables:** - `CONNECT_SSH_ENABLED`: Set to `true` - `CONNECT_SSH_ADDR`: Set to `:2222` (or your chosen SSH port) - `CONNECT_SSH_KEY_PATH`: Path to the SSH private key file (e.g., `/secrets/ssh-key`) **Volume mounts:** - Mount the SSH private key at the path specified in `CONNECT_SSH_KEY_PATH` - Ensure the key is mounted read-only for security The specific implementation depends on your deployment method (Kubernetes manifests, Helm values, Docker Compose, etc.). ## Step 4: Network access requirements SSH access requires the following networking configuration in your infrastructure: **Required:** - Layer 4 (TCP) network access to the connect-proxy on the configured SSH port (default: 2222) - DNS resolution to the connect-proxy SSH endpoint - Firewall rules permitting SSH traffic on the configured port **Recommended:** - Separate network routing for SSH traffic from HTTP/HTTPS traffic for security - If your existing load balancers operate at Layer 7 (HTTP/HTTPS), configure a separate endpoint for Layer 4 (TCP) SSH traffic and set `TOWER_DATA_STUDIO_CONNECT_SSH_ADDRESS` to this endpoint :::note Network configuration is specific to your infrastructure and deployment environment. This may require coordination with your infrastructure or networking team to ensure proper routing and security controls are in place. ::: ## Step 5: Apply configuration After configuring all the required settings: 1. Apply the updated Platform configuration and restart the Platform backend and cron services to load the new settings 2. Apply the updated connect-proxy configuration and restart the connect-proxy service 3. Implement the network access requirements from Step 4 Verify that all services restart successfully and the configuration changes are active. ## Verify SSH access 1. Ensure Studios is enabled for your workspace. 2. Add a Studio with **SSH Connection** enabled. 3. Start the Studio. 4. Test SSH connection: ```bash ssh @@ -p 2222 ``` For detailed usage instructions and VS Code setup, see [Connect to a Studio via SSH](../studios/managing#connect-to-a-studio-via-ssh-public-preview). ## Troubleshooting For SSH connection issues, see [Studios troubleshooting](../troubleshooting_and_faqs/studios_troubleshooting#ssh-connections-public-preview). --- ## Configure Studios data transfer quotas Studio sessions stream data between users and their interactive environments through the Connect proxy. Apply _data transfer quotas_ to cap how many bytes a user or client IP transfers over a set time window. Data transfer quotas are available in Seqera Platform Enterprise only. The Connect proxy (`connect-proxy`) enforces quotas. Quotas are opt-in. If you do not define a policy, the proxy does no counting or enforcement and adds no overhead. :::warning[Advanced configuration] You configure data transfer quotas through deployment settings that depend on your Redis backend and load-balancer networking. The `ip` bucket requires network-level changes that you might need to coordinate with your infrastructure or networking team. ::: :::info[**Prerequisites**] You need the following: - Connect server and proxy version `0.12.0` or later. - Studios enabled. See [Studios installation](./install-studios). - Access to the Connect proxy deployment configuration. - A Redis 7.0 or later backend with server-side scripting enabled. See [Redis requirements](#redis-requirements). - For the `ip` bucket, the ability to configure client-IP resolution on your load balancer. ::: ## Quota enforcement You define a _policy_ that groups traffic into _buckets_. A bucket is a logical counter keyed by an identity, such as a user ID or a client IP. Each bucket has one or more _quotas_, and each quota sets a byte limit over a time window. The proxy counts the bytes transferred in each direction (client to Studio and Studio to client) and totals them against the applicable buckets. When a bucket exceeds a quota, the proxy denies further traffic for that bucket until the window resets. Proxy pods reconcile their counts in a shared Redis instance. Quotas apply consistently regardless of which pod serves a request. ### Fixed time windows Each quota window is _fixed_. It starts on the first byte counted and expires a set duration later, regardless of activity in between. When a window expires, the counter resets, and the next transfer opens a fresh window. :::caution Because windows are independent, a user can transfer close to a full quota immediately before a window resets and another full quota immediately after. A single boundary therefore allows up to roughly twice the cap. Averaged over time, usage converges to the configured rate. Use shorter windows to tighten this bound. ::: ### Behavior when a bucket exceeds a quota When a bucket is over quota, the proxy stops the transfer. On a standard HTTP request, the user receives an `HTTP 429` (Too Many Requests) response. On an active streaming connection (WebSocket or SSH), the proxy tears down the connection. :::note Some interactive clients, including VS Code, might not recover cleanly after a denied transfer and require the user to reconnect. ::: ## Redis requirements Data transfer quotas require a Redis backend that exposes the `incrby`, `expire`, `ttl`, `mget`, `hincrby`, `hset`, `hsetnx`, `eval`, and `evalsha` commands. If you configure a policy and any of these commands is missing, renamed, or blocked by access control lists (ACLs), the proxy fails to start rather than enforce quotas incorrectly. :::caution Enforcement relies on server-side Lua scripting (`eval`/`evalsha`). A managed Redis service with scripting disabled cannot enforce quotas. Redis 7.0 or later is recommended for correct time-to-live (TTL) handling on quota counters. ::: ## Define a policy A policy is a JSON document that lists the buckets to track. Each bucket has a `name`, one or more `quotas`, and one or more `extractors` that bind a protocol to the value that identifies the bucket. ```json { "buckets": [ { "name": "user_id", "quotas": [ { "bytes": "1TB", "window": "720h", "on_exceed": "deny" } ], "extractors": [ { "protocol": "http", "source": { "type": "header", "name": "X-Connect-Sub" } }, { "protocol": "ssh", "source": { "type": "permissions", "field": "userId" } } ] }, { "name": "ip", "quotas": [ { "bytes": "50GB", "window": "24h", "on_exceed": "deny" }, { "bytes": "3GB", "window": "1h", "on_exceed": "deny" } ], "extractors": [ { "protocol": "any", "source": { "type": "client_ip" } } ] } ] } ``` ### Quota fields Each entry in a bucket's `quotas` array defines one limit: - `bytes` — The transfer limit. Use binary multipliers, where `KB` is 2^10 bytes, `MB` is 2^20, `GB` is 2^30, and `TB` is 2^40. The proxy reads a bare integer as bytes. - `window` — The time window, in Go duration syntax (for example, `1h`, `24h`, `720h`). - `on_exceed` — The action to take on breach. The proxy supports only `deny`. Quotas in the same bucket share the same byte counters. For example, you can combine a long-window fair-use ceiling with a short-window burst cap. ### Extractor source types Each extractor's `source.type` determines how the proxy identifies the bucket. The proxy supports only the following values: | `type` | Fields | Protocol | Identifies by | |--------|--------|----------|---------------| | `header` | `name` | HTTP | The value of the named HTTP header | | `permissions` | `field` | SSH | An entry from the SSH permissions data set at authentication | | `jwt` | `token`, `claim` | HTTP | A claim from the validated JSON Web Token (JWT) | | `client_ip` | _(none)_ | `any` | The proxy-resolved client IP | :::caution Use a `header` source only with a header that the proxy sets itself. The identity header `X-Connect-Sub` is safe because the proxy overwrites or strips any client-supplied value during authentication. Pointing a `header` source at a header the proxy does not control lets a user forge it and charge their traffic to another user's quota. ::: The proxy validates the policy at startup. Unknown source types, duplicate bucket names, two bindings for the same protocol in one bucket, or mixing `any` with a specific protocol all prevent startup. ## Apply the policy Configure quotas with the following environment variables. Set either `CONNECT_POLICY_B64` or `CONNECT_POLICY_FILE`, not both. | Environment variable | Default | Description | |----------------------|---------|-------------| | `CONNECT_POLICY_B64` | _(empty)_ | Base64-encoded JSON traffic policy. Empty or unset disables telemetry and quota enforcement. Mutually exclusive with `CONNECT_POLICY_FILE`. | | `CONNECT_POLICY_FILE` | _(empty)_ | Path to a JSON traffic policy file. Mutually exclusive with `CONNECT_POLICY_B64`. | | `CONNECT_TELEMETRY_FLUSH_INTERVAL` | `30s` | How often the proxy writes in-memory byte counters to Redis. | | `CONNECT_TELEMETRY_TTL` | `168h` | TTL for cumulative per-bucket telemetry keys in Redis (7 days). | | `CONNECT_TELEMETRY_STREAM_EMIT_INTERVAL` | `1s` | How often long-lived streams (WebSocket and SSH) report transferred bytes. | In a Kubernetes deployment, store the policy in a `ConfigMap` and inject it into the proxy configuration as base64. :::info The proxy reads the policy once at startup and does not reload it at runtime. To change a quota, update the policy `ConfigMap`, then perform a rolling restart of the proxy Deployment. Editing the `ConfigMap` alone has no effect on running pods. ::: ## Resolve the client IP for the `ip` bucket The `ip` bucket keys on the client IP as the proxy resolves it. Behind a load balancer, that resolution needs explicit configuration. If you skip this step, the proxy counts traffic against Kubernetes node IPs instead of client IPs. Because many users share the same nodes, one busy node can exceed the limit and deny traffic to unrelated users. A single user's traffic also fragments across nodes. :::note This section applies only to policies that use the `ip` bucket. A policy that uses only `user_id` quotas needs no load-balancer configuration. ::: The proxy resolves the client IP differently for HTTP and SSH traffic. Configure each separately. ### Trust `X-Forwarded-For` for HTTP traffic An HTTP(S) load balancer, for example an AWS Application Load Balancer, terminates the connection and appends the real client IP to `X-Forwarded-For`. Set `CONNECT_TRUSTED_PROXY_CIDRS` to the CIDR ranges of the hops between your load balancer and the proxy: ```bash CONNECT_TRUSTED_PROXY_CIDRS="10.0.0.0/8 172.16.0.0/12 192.168.0.0/16" ``` The proxy walks `X-Forwarded-For` from the right, skips trusted hops, and takes the first untrusted address as the client. - Set the CIDRs to the node or virtual private cloud (VPC) ranges between your load balancer and the proxy. Use whichever address the proxy sees as its immediate peer. - The default `127.0.0.1/32` is a deliberate no-op. If you leave it unset, the proxy trusts nothing and falls back to the socket peer. - Trust only as narrow a range as necessary. Any client whose address falls inside a trusted CIDR can forge `X-Forwarded-For` and charge its traffic to another IP's bucket. ### Preserve the source IP for SSH traffic SSH runs at Layer 4, through a network load balancer. Layer 4 carries no `X-Forwarded-For` header, and `CONNECT_TRUSTED_PROXY_CIDRS` has no effect. The real client IP must survive the network path instead. For a `NodePort` SSH service, set the following: ```yaml externalTrafficPolicy: Local ``` `Local` skips the kube-proxy source network address translation (NAT) and gives the pod the real client IP. As a trade-off, only nodes running a proxy pod stay healthy in the load balancer's target group. Configure the load balancer health check to probe the `NodePort` so that nodes without a proxy pod drop out of rotation. Alternatively, enable the PROXY protocol on the load balancer. Without one of these two options, SSH sessions bucket on node IPs. ### Confirm client-IP resolution Generate traffic and confirm the resolved address is a real client IP, not a node IP: - **HTTP** — At `debug` log level, the `telemetry http` log line shows `keys: ["ip:", ...]`, and the reverse-proxy log shows `client_ip`. Both should be the public client address. - **SSH** — The proxy logs each connection's `remote address`. The value should be the client IP, not a private node address such as `172.16`–`172.31.x`. If the `ip:` key (or `client_ip` / `remote address`) shows a private or node range (`10.x`, `172.16`–`172.31.x`, or `192.168.x`), resolution is not configured correctly. Revisit [Trust `X-Forwarded-For` for HTTP traffic](#trust-x-forwarded-for-for-http-traffic) and [Preserve the source IP for SSH traffic](#preserve-the-source-ip-for-ssh-traffic). :::note The proxy emits the per-request `telemetry http` lines at `debug` level only. They do not appear at the default `INFO` level. Set `CONNECT_LOG_LEVEL=debug` temporarily while you verify, then revert it. ::: ## Monitor data transfer ### Prometheus metrics When you load a policy, the proxy registers three metrics, labeled by bucket _name_ only (for example, `user_id` or `ip`) and never by the extracted value. Metric cardinality therefore stays bounded by your policy rather than by the number of users or IP addresses. Each configured bucket also gets a zero-valued series so that dashboards show a baseline before the first breach. | Metric | Type | Meaning | |--------|------|---------| | `connect_proxy_quota_exceeded_total{bucket}` | Counter | Number of times a bucket crossed a quota and the proxy denied traffic | | `connect_proxy_quota_cleared_total{bucket}` | Counter | Number of times a bucket returned under quota and the proxy resumed traffic | | `connect_proxy_quota_breached_keys{bucket}` | Gauge | Number of bucket keys currently over quota | :::note Metric scraping and dashboards are available in Seqera Platform Cloud only. For self-managed Enterprise deployments, use the Redis and log-based checks described later on this page to observe quotas. ::: ### Inspect counters in Redis The proxy stores quota data in Redis under the `connect:telemetry` prefix. For each bucket value, the proxy maintains a cumulative record for analytics and a separate counter per quota window for enforcement. The enforcement counters carry a `q` suffix, for example `:q60` for a 60-second window. Use the following commands to inspect a user's counters during troubleshooting: ```bash # List telemetry keys. Use SCAN, not KEYS — KEYS blocks the whole Redis server. SCAN 0 MATCH connect:telemetry:* COUNT 100 # A user's quota counter and time remaining in the window GET connect:telemetry:user_id:42:q60 TTL connect:telemetry:user_id:42:q60 # A user's cumulative transfer totals HGETALL connect:telemetry:user_id:42 ``` Interpret the quota counter as follows: - Value below the cap — the bucket is within quota. - Value at or above the cap — the bucket is breached, and the proxy denies traffic until the window expires. - Key absent (`TTL` returns `-2`, `GET` returns nil) — the window has expired, and the next transfer opens a new one. ### Log messages Watch for these proxy log lines: - `telemetry flushed {entries: N}` — a healthy flush to Redis. - `telemetry flush failed, will retry next tick` — a Redis write error. The proxy retains the counters and retries them. - `quota exceeded, denying traffic for bucket` / `quota cleared, resuming traffic` — enforcement transitions. ## Troubleshooting For quota enforcement and client-IP issues, see [Studios troubleshooting](../troubleshooting_and_faqs/studios_troubleshooting#data-transfer-quotas). --- ## Test deployment After your [Docker Compose](./platform-docker-compose) or [Kubernetes](./platform-kubernetes) installation is complete, follow these steps to test whether the application is running as expected: 1. Log in to the application. 2. Create an [organization](../orgs-and-teams/organizations). 3. Create a [workspace](../orgs-and-teams/workspace-management) within the organization. 4. Create a new [compute environment](../compute-envs/overview). 5. Add your [GitHub credentials](../git/overview). 6. Select **Quick Launch** from the **Launchpad** tab in your workspace. 7. Enter the repository URL for the `nf-core/rnaseq` pipeline (`https://github.com/nf-core/rnaseq`). 8. In the **Config profiles** drop-down, select the `test` profile. 9. In **Pipeline parameters**, change the output directory to a location based on your compute environment: ```yaml # Uncomment to save to an S3 bucket # outdir: s3:///results # Uncomment to save to a scratch directory (Kubernetes) # outdir: /scratch/results ``` 10. Select **Launch**. You'll be redirected to the **Runs** tab for the workflow. After a few minutes, progress logs will be listed in that workflow's **Execution log** tab. --- ## Upgrade deployment This page outlines the steps to upgrade your database instance and Platform Enterprise installation to version 26.1, including special considerations for upgrading from earlier versions. :::note - Make a backup of your Platform database prior to upgrade. - If you are upgrading from a version prior to 25.1, complete all intermediate major version upgrades before upgrading to 26.1, for example from 23.1 upgrade to 24.1, then 25.1, and finally 26.1. More specific requirements are detailed below for each major version. - Ensure that no pipelines are in a running state during this upgrade as active run data may be lost. ::: ## Upgrading from versions prior to 24.1 - If you are upgrading from a version older than 23.4.1, update your installation to version 23.4.4 **first**, before updating to version 26.1 with the steps on this page. - **MySQL 8 required** From Seqera Enterprise version 23.4, MySQL 8 was the only supported database version. If you are running MySQL 5.6 or 5.7, you must upgrade your database to a supported MySQL version (see the [26.1 database considerations below](#database-changes) for the new baseline) before upgrading. ## Upgrading from versions 24.1 - 25.1 - **OIDC Secrets injection modifications** The `auth-oidc-secrets` Micronaut environment has been replaced with `oidc-token-import`. If you use this configuration, you must change the `MICRONAUT_ENV` environment variable in the manifest during the migration process. If you activate the feature with the `TOWER_OIDC_TOKEN_IMPORT` environment variable, no changes are needed. - **MariaDB driver: New MySQL connection parameter required** MariaDB driver 3.x requires the `permitMysqlScheme=true` parameter in the connection URL to connect to a MySQL database: `jdbc:mysql://:/tower?permitMysqlScheme=true` All deployments using a MySQL database (regardless of version) must be updated when upgrading to Platform version 24.1 or later. - **Redis version change and property deprecation** - From Seqera Enterprise version 24.2, Redis version 6.2 or greater was required. **In 26.1, Redis 6.x is no longer supported — see the [26.1 cache considerations](#cache-layer-changes-redis-eol-and-valkey-support) below.** - From Seqera Enterprise version 24.2, `redisson.*` configuration properties are deprecated. If you previously set `redisson.*` properties directly: - Replace `/redisson/*` references in AWS Parameter Store entries with `TOWER_REDIS_*` environment variables. - Replace `redisson.*` references in `tower.yml` with `TOWER_REDIS_*` environment variables. - **Micronaut property key changes** In version 24.1, the property that determines the expiration time of the JWT access token (used for authenticating web sessions and Nextflow-Platform interactions) changed: | Previous | New | | --- | --- | | `micronaut.security.token.jwt.generator.access-token.expiration` | `micronaut.security.token.generator.access-token.expiration` | Enterprise deployments that have customized this value previously will need to adopt the new format. ## Upgrading from version 25.3.x to 26.1 You can upgrade directly from 25.3.x to 26.1. However, take note of the breaking changes as well as the upgrade steps in this document. - **Secret key rotation requires backup and careful configuration** To configure [secret key rotation](https://docs.seqera.io/platform-enterprise/enterprise/configuration/overview#secret-key-rotation): - To prevent data loss, perform a backup of your Platform database and securely back up your current crypto secret key before enabling and performing key rotation. - All backend pods or containers for your Enterprise deployment must contain the same previous and new secret key values in their configuration. - All backend pods or containers must be in a ready/running state before starting the Platform cron service. ## 26.1 upgrade breaking changes ### Audit log versions in 26.1 Seqera Platform Enterprise 26.1 introduces the audit log v2 schema as a **breaking change** for direct database consumers and custom ETL jobs. - The legacy audit log schema remains in the `tw_audit_log` table. This table is now deprecated. - The new audit log v2 schema is written to a separate table. - The v2 schema is not backward-compatible with the legacy schema. Field names, structure, and pagination behavior differ. - The v2 Admin panel view and CSV export are available when `TOWER_AUDIT_LOG_V2_WRITE_MODE` is set to `dual` or `v2`. Use `TOWER_AUDIT_LOG_V2_WRITE_MODE` to control how new audit events are written: - `dual`: Default. Write new events to both `v1` schema and `v2` schema. This is the recommended 26.1 migration mode if you need to validate the v2 schema while keeping existing v1 integrations unchanged. - `v2`: Write new events to `v2` schema only. #### Upgrade path for existing integrations If you have existing scripts, exports, or ETL processes that read from the legacy audit log schema, plan the 26.1 upgrade in two stages: 1. Upgrade to 26.1. 2. Validate your integrations against v2 while your existing v1 readers continue to work from the legacy table. In the 26.1 migration plan, dual-write is transitional. Plan for 26.2 to make v2 the only write-side schema, while the legacy v1 data remains available for reads as long as your retention policy still covers the required historical period. ## Database changes 26.1 changes the supported database baseline. Review your current database against the table below **before upgrading**. | Database / version | 26.1 status | Action | | --- | --- | --- | | MySQL 5.7 | No longer tested or supported (upstream EoL) | Upgrade to MySQL 8.4 before upgrading to 26.1 | | MySQL 8.0 | No longer tested or supported (upstream EoL April 2026) | Upgrade to MySQL 8.4 | | MySQL 8.4 (LTS) | Recommended default | No action | | MariaDB | MariaDB driver 3.x | No action | | AWS Aurora MySQL (provisioned) | Supported | No action | | AWS Aurora Serverless | Not supported (existing guidance) | Migrate to a supported configuration | If you are running on MySQL 5.7, MySQL 8.0, or MariaDB, complete your database migration **before** running the 26.1 application upgrade. The Seqera-supplied `migrate-db` container will not run against an unsupported database version. ## Cache layer changes: Redis EoL and Valkey support 26.1 introduces Valkey support and tightens Redis version requirements. | Cache / version | 26.1 status | Action | | --- | --- | --- | | Redis 6.x | EoL upstream — no longer supported | Upgrade to Redis 7.2+ or migrate to Valkey 7+ | | Redis 7.2 | Supported | No action | | Redis 7.4 | Supported | No action | | Valkey 7.x | Newly supported in 26.1 | Optional migration path from Redis | ### Migrating from Redis to Valkey To migrate from Redis to Valkey, update the `TOWER_REDIS_URL` environment variable. The Redisson client embedded in Platform 26.1 has been upgraded to support Valkey 7 dial schema; no further configuration is required. :::note Redis password and ACL configuration carry over unchanged when migrating to Valkey. ::: ## Frontend image root user deprecation The frontend image running as root user is deprecated in 26.1 in favor of the unprivileged ("rootless") image. The privileged image running as root will be removed in a future major release. If you have not already migrated, update your [Kubernetes](../enterprise/platform-kubernetes) or [Docker Compose](../enterprise/platform-docker-compose) manifests to reference the unprivileged image when downloading the new templates in the General upgrade steps below. See the [unprivileged frontend image documentation](../enterprise/platform-kubernetes#seqera-frontend-unprivileged) for security context, file system, and port differences. The unprivileged image is a requirement for the installation via the [Helm chart](../enterprise/platform-helm). ## Studios enabled on all workspaces by default In 26.1, Studios is enabled on every workspace in your instance by default. This is a behavior change from earlier versions where Studios required explicit per-workspace enablement. The [`TOWER_DATA_STUDIO_ALLOWED_WORKSPACES`](./configuration/overview#data-features) environment variable controls Studios availability: | Value | Behavior | | --- | --- | | Unset (new default) | Studios enabled on **all workspaces** | | `""` (empty string) | Studios disabled on all workspaces | | Comma-separated workspace IDs | Studios enabled only on the listed workspaces | To preserve previous opt-in behavior after upgrading, set `TOWER_DATA_STUDIO_ALLOWED_WORKSPACES=""` before the upgrade, or set it to a comma-separated list of workspace IDs to allow. ### Studios container template version The recommended Studios container template version for 26.1 is **0.12**. If you have customized your Studios container templates, update them to the 0.12 base images during this upgrade. Templates pinned to earlier Connect versions may no longer be supported. See the [Studios migration documentation](../studios/managing#migrate-a-studio-from-an-earlier-container-image-template). ## AWS data lineage tracking via SQS (preview, AWS only) 26.1 introduces a preview of AWS data lineage tracking that depends on an Amazon SQS queue. This feature is AWS-only and disabled by default. If you plan to enable it, ensure your IAM policies grant the Seqera role the relevant [SQS permissions](../data/data-lineage#additional-iam-permissions-required) in addition to the existing [Seqera IAM permissions](../compute-envs/aws-batch#iam-user-creation). ## General upgrade steps :::caution The database volume is persistent on the local machine by default if you use the `volumes` key in the `db` or `redis` section of your `docker-compose.yml` file to specify a local path to the DB or Redis instance. If your database is not persistent, you must back up your database before performing any application or database upgrades. ::: 1. Make a backup of the Seqera database. If you use the pipeline optimization service and your `groundswell` database resides in a database instance separate from your Seqera database, make a backup of your `groundswell` database as well. 1. Download the latest versions of your deployment templates and update your Seqera container versions: - [docker-compose.yml](./_templates/docker/docker-compose.yml) for Docker Compose deployments - [tower-cron.yml](./_templates/k8s/tower-cron.yml) and [tower-svc.yml](./_templates/k8s/tower-svc.yml) for Kubernetes deployments 1. **JVM memory defaults (recommended)**: The deployment templates you downloaded in the previous step include the following `JAVA_OPTS` environment variable to tune JVM memory settings: ```bash JAVA_OPTS="-Xms1000M -Xmx2000M -XX:MaxDirectMemorySize=800m -Dio.netty.maxDirectMemory=0 -Djdk.nio.maxCachedBufferSize=262144" ``` These baseline values suit most deployments with moderate concurrent workflow loads. :::tip These are starting values that may need tuning for your workload. See [Backend memory requirements](./configuration/overview.mdx#backend-memory-requirements) for when and how to adjust them. ::: 1. If you're using Studios, download and apply the latest versions of the Kubernetes manifests: - [proxy.yml](./_templates/k8s/data_studios/proxy.yml) - [server.yml](./_templates/k8s/data_studios/server.yml) :::warning If you have customized the default Studios container template images, you must ensure that you update to latest recommended versions. Templates using earlier versions of Connect (than defined in the latest `proxy.yml` and `server.yml`) may no longer be supported in your existing Studios environments. Refer to the [Studios migration documentation](../studios/managing#migrate-a-studio-from-an-earlier-container-image-template) for guidance on migrating to the most recent versions of Connect server and clients. ::: 1. Restart the application. 1. If you're using a containerized database as part of your implementation: 1. Stop the application. 1. Upgrade the MySQL image. 1. Restart the application. 1. If you're using Amazon RDS or other managed database services: 1. Stop the application. 1. Upgrade your database instance. 1. Restart the application. 1. If you're using the pipeline optimization service (`groundswell` database) in a database separate from your Seqera database, update the MySQL image for your `groundswell` database instance while the application is down (during step 4 or 5 above). If you're using the same database instance for both, the `groundswell` update will happen automatically during the Seqera database update. ### Database migrations Database migrations run automatically during upgrade. No manual steps required. ### Custom deployments - Run the `/migrate-db.sh` script provided in the `migrate-db` container. This will migrate the database schema. - Deploy Seqera following your usual procedures. ## Nextflow launcher image If you host your nf-launcher container image on a private image registry, copy the [nf-launcher image](https://quay.io/seqeralabs/nf-launcher:j21-26.04.x) to your private registry. Then set the launch container environment variable on your backend environment: ``` TOWER_LAUNCH_CONTAINER= ``` :::caution If you're using AWS Batch, you will need to [configure a custom job definition](../enterprise/advanced-topics/custom-launch-container) and populate the `TOWER_LAUNCH_CONTAINER` with the job definition name instead. ::: --- ## Default version compatibility Seqera supports the two most recent major Seqera Platform versions (for example, 25.3.x and 26.1.x) at any given time. Each Seqera Platform version uses `nf-launcher` to set its baseline Nextflow version. To use a different Nextflow version in your pipeline runs, add a [pre-run script](../launch/advanced#pre-and-post-run-scripts) during launch. Seqera Platform may not work reliably with Nextflow versions other than the baseline. If you do not specify a Nextflow version in your configuration, Seqera Platform uses the baseline version listed in the following table: | Platform version | nf-launcher version | Nextflow version | Fusion version | Connect client version | | ---------------- | ------------------- | ---------------- | -------------- | ---------------------- | | 26.1.2 | j21-26.04 | 26.04 | 2.4 | 0.12.0 | | 26.1.0 | j21-26.04 | 26.04 | 2.4 | 0.12.0 | | 25.3.6 | j21-25.10.2 | 25.10.2 | 2.4 | 0.11.0 | | 25.3.4 | j21-25.10.2 | 25.10.2 | 2.4 | 0.9.0 | | 25.3.1 | j21-25.10.2 | 25.10.2 | 2.4 | 0.9.0 | | 25.3.0 | j21-25.04.8 | 25.04.8 | 2.4 | | | 25.2.4 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.2.3 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.2.2 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.2.3 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.2.1 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.1.3 | j17-24.10.9-b1 | 24.10.9 | 2.4 | | | 25.2.0 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.1.5 | j17-24.10.9-b1 | 24.10.9 | 2.4 | | | 25.1.4 | j17-24.10.9-b1 | 24.10.9 | 2.4 | | | 25.1.3 | j17-24.10.9-b1 | 24.10.9 | 2.4 | | | 25.2.3 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.2.1 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.1.3 | j17-24.10.9-b1 | 24.10.9 | 2.4 | | | 25.1.1 | j17-24.10.5 | 24.10.5 | 2.4 | | | 25.1.0 | j17-24.10.5 | 24.10.5 | 2.4 | | | 24.2.7 | j17-24.10.9-a1 | 24.10.9 | 2.4 | | | 24.2.4 | j17-24.10.4 | 24.10.4 | 2.4 | | | 24.2.1 | j17-24.10.2 | 24.10.2 | 2.4 | | | 25.1.0 | j17-24.10.5 | 24.10.5 | 2.4 | | | 24.2.7 | j17-24.10.9-a1 | 24.10.9 | 2.4 | | | 24.2.6 | j17-24.10.9-a1 | 24.10.9 | 2.4 | | | 25.1.0 | j17-24.10.5 | 24.10.5 | 2.4 | | | 24.2.7 | j17-24.10.9-a1 | 24.10.9 | 2.4 | | | 24.2.4 | j17-24.10.4 | 24.10.4 | 2.4 | | | 24.2.1 | j17-24.10.2 | 24.10.2 | 2.4 | | | 24.2.4 | j17-24.10.4 | 24.10.4 | 2.4 | | | 24.2.3 | j17-24.10.4 | 24.10.4 | 2.4 | | | 24.2.2 | j17-24.10.0 | 24.10.0 | 2.4 | | | 24.2.1 | j17-24.10.2 | 24.10.2 | 2.4 | | | 24.2.0 | j17-24.10.0 | 24.10.0 | 2.4 | | `nf-launcher` versions prefixed with `j21` use Java 21, and versions prefixed with `j17` use Java 17. --- ## Deploy Platform [Seqera Platform Enterprise](../enterprise/overview) is installed in an organization's own cloud or on-premises infrastructure. It includes: - Monitoring, logging, and observability - Pipeline execution Launchpad - Cloud resource provisioning - Pipeline actions and event-based execution - LDAP and OpenID authentication - Enterprise role-based access control (RBAC) - Full-featured API - Dedicated support for Nextflow and Seqera Platform To install Platform in your organization's infrastructure, [contact us](https://cloud.seqera.io/demo/) for a demo to discuss your requirements. ## How to use Platform You can access your Seqera instance through the UI, the [API](https://docs.seqera.io/platform-api), the [CLI](https://docs.seqera.io/platform-cli), or in Nextflow directly using the `-with-tower` option. ### Platform web-based UI 1. Create an account and log in to Seqera Cloud at [cloud.seqera.io](https://cloud.seqera.io). :::note Platform login sessions remain active as long as the application browser window remains open and active. When the browser window is terminated, automatic logout occurs within 6 hours by default. ::: 2. Create and configure a new [compute environment](../compute-envs/overview). 3. Start [launching pipelines](../launch/launchpad). ### Seqera API See [API](https://docs.seqera.io/platform-api). :::tip To find the organization and workspace IDs that API endpoints use, see [Automation](./quickstart-demo/automation#find-your-organization-and-workspace-ids). ::: ### Seqera CLI See [CLI](https://docs.seqera.io/platform-cli). ### Nextflow `-with-tower` If you have an existing environment where you run Nextflow directly, you can still leverage Seqera Platform capabilities by executing your Nextflow run with a `with-tower` flag: 1. Create an account and log in to Seqera at [cloud.seqera.io](https://cloud.seqera.io). 2. From your personal workspace: Go to the user menu and select **Settings > Your tokens**. 3. Select **Add token**. 4. Enter a unique name for your token, then select **Add**. 5. Copy and store your token securely. :::caution The access token is displayed only once. Save the token value before closing the **Personal Access Token** window. ::: 6. Open a terminal window and create environment variables to store the Seqera access token and Nextflow version. Replace `` with your newly-created token. ```bash export TOWER_ACCESS_TOKEN= export NXF_VER=23.10.1 ``` :::note Bearer token support requires Nextflow version 20.10.0 or later. Set with the `NXF_VER` environment variable. ::: 7. To submit a pipeline to a [workspace](../orgs-and-teams/workspace-management) using Nextflow, add the workspace ID to your environment: ```bash export TOWER_WORKSPACE_ID=000000000000000 ``` To find your workspace ID, select your organization in Seqera and navigate to the **Workspaces** tab. 8. Run your Nextflow pipeline with the `-with-tower` flag: ```bash nextflow run main.nf -with-tower ``` Replace `main.nf` with the filename of your Nextflow script. You can now monitor your workflow runs in the Seqera interface. To configure and execute Nextflow pipelines in cloud environments, see [compute environments](../compute-envs/overview). :::tip See the [Nextflow documentation](https://docs.seqera.io/nextflow/config.html?highlight=tower#scope-tower) for further run configuration options using Nextflow configuration files. ::: --- ## Run a pipeline On this page, learn how to run a pipeline with sample data and get started running your own pipelines. :::tip [**Sign up**](https://tower.nf "Seqera Platform") to try Seqera for free, or request a [**demo**](https://cloud.tower.nf/demo/ "Seqera Platform Demo") for deployments in your own on-premises or cloud environment. ::: The Community Showcase [Launchpad](../launch/launchpad) is an example workspace provided by Seqera. The showcase is pre-configured with compute environments, credentials, and pipelines to start running Nextflow workflows immediately. A pipeline consists of a pre-configured workflow repository, compute environment (with 100 free CPU hours), and launch parameters. From version 23.1.3, the Community Showcase comes pre-loaded with two AWS Batch compute environments to run showcase pipelines. ### Components - [Datasets](../data/datasets) are collections of versioned, structured data (usually in the form of a samplesheet) in CSV or TSV format. A dataset is used as the input for a pipeline run. Sample datasets are used in pipelines with the same name, e.g., the _nf-core-rnaseq-test_ dataset is used as input when you run the _nf-core-rnaseq_ pipeline. - [Compute environments](../compute-envs/overview) are the platforms where workflows are executed. A compute environment consists of access credentials, configuration settings, and storage options for the environment. - [Credentials](../credentials/overview) are the authentication keys Seqera uses to access compute environments, private code repositories, and external services. Credentials are SHA-256 encrypted before secure storage. The Community Showcase includes all the credentials you need to run pipelines in the included AWS Batch compute environments. - [Secrets](../secrets/overview) are retrieved and used during pipeline execution. In your private or organization workspace, you can store the access keys, licenses, or passwords required for your pipeline execution to interact with third-party services. The secrets included in the Community Showcase contain license keys to run _nf-dragen_ and _nf-sentieon_ pipelines in the showcase compute environments. ## Run a pipeline with sample data 1. From the [Launchpad](../launch/launchpad), select a pipeline to view the pipeline detail page. _nf-core-rnaseq_ is a good first pipeline example. 2. Optional: Select the URL under **Workflow repository** to view the pipeline code repository in another tab. 3. Select **Launch** from the pipeline detail page. 4. On the **Launch pipeline** page, enter a unique **Workflow run name** or use the pre-filled random name. 5. Optional: Enter labels to be assigned to the run in the **Labels** field. 6. Under **Input/output options**, select the dataset named after your chosen pipeline from the drop-down under **input**. 7. Under **outdir**, specify an output directory where run results will be saved. This must be an absolute path to storage on cloud infrastructure and defaults to `./results`. 8. Under **email**, enter an email address where you wish to receive the run completion summary. 9. Under **multiqc_title**, enter a title for the MultiQC report. This is used as both the report page header and filename. The remaining launch form fields will vary depending on the pipeline you have selected. Parameters required for the pipeline to run are pre-filled by default, and empty fields are optional. Once you've filled the necessary launch form details, select **Launch**. Your new run will be displayed at the top of the list in the **Runs** tab with a **submitted** status. Select the run name to navigate to the run detail page and view the configuration, parameters, status of individual tasks, and run report. ## Run your own pipelines To run pipelines on your own infrastructure, you first need to create your own organization. * [Organizations](../orgs-and-teams/organizations) are the top-level structure in Seqera. They contain the building blocks of your organizational infrastructure. * [Workspaces](../orgs-and-teams/workspace-management) are where resources are managed. All team members can access the organization workspace. In addition to this, each user has a unique personal workspace to manage resources such as pipelines, compute environments, and credentials. * [Teams](../orgs-and-teams/organizations) are collections of members. * [Members](../administration/overview#members) belong to an organization and can have different levels of access across workspaces. You can create multiple workspaces within an organization context and associate each of these workspaces with dedicated teams of users, while providing fine-grained access control for each of the teams. See [Administration](../orgs-and-teams/organizations). --- ## Production checklist This guide is for Platform administrators preparing a Seqera deployment for production use by scientific teams. It covers common configuration decisions, policies, and checks to consider before you run production workloads. Because every deployment is different, your Seqera account team can help you tailor these recommendations to your environment and workloads. Cloud infrastructure setup, such as networking, IAM, and compute provisioning, is the responsibility of your infrastructure team and is not covered here. ## Organizations and workspaces Organizations are the top-level structure in Seqera Platform and contain workspaces, members, and teams. You can create multiple organizations, each with multiple workspaces, to customize resource use and maintain access control across teams. Best practices for organizations and workspaces include: - Plan your organization and workspace structure, considering the roles and work streams you expect to start with and scale to. - Use separate workspaces to isolate production from development and test environments. See [Organizations](../orgs-and-teams/organizations) for more information. ## Users and roles Roles define an organization member's access and permissions within Platform. Each member has an organization role and can operate in one or more workspaces, where a participant role governs what they can do within that workspace. Best practices for users and roles include: - Map out expected users and their roles before go-live to ensure your access model is scalable. - Assign roles at the level of access each user actually requires rather than granting broad permissions by default. - Limit organization owner assignment to users responsible for managing members, teams, and organization-level settings. See [User roles](../orgs-and-teams/roles) for more information. ## Version pinning and compatibility Incompatibilities between Nextflow and Platform versions are a leading cause of production failures, and often only surface during pipeline resumption after an interruption. Best practices for version pinning and compatibility include: - Set the Nextflow version in the compute environment configuration before handing workspaces to scientific teams, and document it alongside the Seqera Platform version in use. - Avoid performing Nextflow and Platform upgrades simultaneously, and validate all version changes in a non-production environment first. - Coordinate with pipeline developers to confirm the current working version combination and agree on a rollback plan before you schedule any upgrades. - Before promoting a version change to production, ask pipeline teams to test resumption explicitly: launch a representative pipeline, interrupt it, and confirm it resumes from the last successful task. :::warning Resumption failure after an upgrade typically indicates a version incompatibility issue. If pipeline teams cannot resume after a version upgrade, roll back to the last documented working version combination before investigating further. ::: ## Cache management Nextflow uses content-addressed caching to resume pipelines from the last successful task. Cache misconfiguration can lead to unexpected behavior during pipeline resumption. The administrator's role is to configure the storage environment that cache depends on, and to coordinate with pipeline teams to validate cache behavior before go-live. Best practices for cache management include: - Configure storage lifecycle policies to ensure that intermediate work directory objects are not removed while pipelines are still running or may need to resume. Coordinate these policies with your cloud team before go-live. - Ask pipeline teams to validate cache integrity before go-live: run a representative pipeline, run it again, and confirm that cache hits occur and outputs match a clean run. - Schedule Platform or Nextflow upgrades with pipeline teams in advance, and plan for the first post-upgrade production runs to take longer and cost more if cache is invalidated by a hash algorithm change. Your Seqera account team can help assess cache configuration for your specific workloads and storage setup. :::warning After a Nextflow or Platform version upgrade, hash algorithms or cache key generation may change, causing all previously cached tasks to re-run. Inform pipeline teams before any upgrade so they can plan capacity and schedule accordingly; this is an expected behavior, but it may cause alarm if it happens unexpectedly. ::: ## Credentials and token lifecycle Credentials in Seqera Platform require active management. Expired or rotated credentials that are not updated in Platform are a common cause of silent pipeline failures. Before you go live: - Identify all credentials used by production pipelines: cloud provider credentials, Git tokens, container registry credentials, and API tokens. - Record when each credential was created and when it expires. - Assign a named owner responsible for rotating each credential. **When rotating credentials** 1. Add the new credential to the correct Seqera organization and workspaces. 2. Launch a test pipeline using the new credential and confirm it runs successfully. 3. Remove or deactivate the old credential only after step 2 is confirmed. :::warning Do not rotate credentials during active pipeline runs. Schedule rotations during maintenance windows. ::: Use [Pipeline Secrets](../secrets/overview) to manage sensitive values such as API keys for third-party services. Secrets are injected at runtime and are not exposed in pipeline logs or configuration files. ## Compute environment permissions Permissions within shared compute environments can cause unexpected behavior, particularly when multiple teams use the same workspace. Best practices for compute environment permissions include: - Use dedicated compute environments for production and avoid sharing production compute environments with development or test workloads. - Assign workspace roles at the level of access each user actually requires. The **Launch** role is appropriate for most researchers running established pipelines; **Maintain** is for users who need to configure compute environments and pipelines. - Use separate workspaces if your organization requires run isolation between teams or projects. Users in the same workspace can see and cancel each other's pipeline runs. :::note Admin-level workspace access grants the ability to modify compute environments and credentials, which can affect all pipelines in the workspace. Assign Admin only to users who are responsible for workspace configuration. ::: ## Compute environment sizing Correctly sizing compute environments before go-live prevents resource contention, job failures, and unexpected costs in production. Best practices for compute environment sizing include: - A typical starting range for max CPUs is 2000 to 5000, depending on your workload volume and concurrency needs. Your Seqera account team can advise on the best sizing for your environment. - Consider enabling Fusion v2 with fast instance storage (NVMe) for I/O-intensive workloads on AWS. In tested benchmarks, this showed a 34% reduction in total pipeline runtime and up to 49% reduction in CPU hours compared to plain S3 storage. See [RNA-Seq performance benchmarks](../getting-started/rnaseq#nf-corernaseq-performance-in-platform) for details. - Use the [pipeline optimization feature](../pipeline-optimization/overview) to right-size resource allocations based on actual usage data. After a successful run, select the lightbulb icon next to the pipeline in the Launchpad to view and apply an optimized configuration profile. - For GPU workloads such as protein structure prediction, use GPU-enabled instance families (`g4dn`, `g5`, or `p3` on AWS) and ensure the GPU ECS AMI is enabled in the compute environment configuration. :::warning Studios do not support AWS Fargate. If you share a compute environment between pipelines and Studios, do not enable **Use Fargate for head job**. Enabling Fargate on a shared compute environment will prevent Studios sessions from starting. ::: :::note Studio sessions compete for compute resources with pipeline runs in the same compute environment. For production workloads, use a dedicated compute environment for pipelines, or ensure the shared environment has sufficient capacity to accommodate both concurrently. ::: See [RNA-Seq](../getting-started/rnaseq) and [Protein structure prediction](../getting-started/proteinfold) for workload-specific compute environment recommendations. ## Cost tagging Without resource labels, cloud billing reports cannot attribute compute costs to specific teams, projects, or pipelines. Best practices for cost tagging include: - Define a tagging strategy before running production workloads. At minimum, tag by `environment`, `team`, and `pipeline`. Add `project` or `cost_center` tags if you need chargeback reporting. - Use [dynamic resource labels](../resource-labels/overview) to apply pipeline-specific tags to AWS Batch jobs automatically at run time. This enables cost attribution at the individual run level without manual configuration. :::warning Cancelling a pipeline run in Seqera Platform does not guarantee immediate termination of the underlying cloud compute jobs. Configure spend alerts in your cloud provider's billing tools independently of Platform, so that runaway compute costs are detected even if Platform does not surface them. ::: :::note The cost estimator in Seqera Platform is for estimation purposes and doesn't account for inefficiencies in how cloud batch executors provision instances. For billing, budgeting, or chargeback, use your cloud provider's native cost reporting tools: AWS Cost Explorer, GCP Billing, or Azure Cost Management. ::: ## Cost management and alerts Managing compute spend before your workloads go live reduces the risk of unexpected charges in production. Best practices for cost management and alerts include: - Enable billing exports to your cloud provider's analytics tooling before running production workloads: AWS Cost Explorer or S3 export, GCP billing export to BigQuery, or Azure Cost Management. These give you the raw data needed to investigate unexpected charges. - Set budget alerts in your cloud provider's billing tools to detect unexpected daily or weekly spend changes. On AWS, configure CloudWatch billing alarms; on GCP, use Cloud Monitoring budget alerts; on Azure, use Cost Management alert rules. - On AWS, use [dynamic resource labels](../resource-labels/overview) to tag Batch jobs with pipeline-specific values at run time. Dynamic labels do not appear in AWS Cost Explorer's graphical UI. Costs are tracked via AWS split cost allocation data in Cost and Usage Reports (CUR). Enable split cost allocation in the AWS billing console before expecting to see per-pipeline costs. See the [Seqera blog post on AWS labels cost tracking](https://seqera.io/blog/aws-labels-cost-tracking/) for setup guidance. - On GCP, apply labels to Cloud Storage buckets, Filestore instances, and Compute Engine VMs in addition to Cloud Batch jobs. Label all resources consistently so BigQuery billing exports can attribute costs at the workload level. - Account for CloudWatch fees separately on AWS as these are not included in Seqera Platform run cost estimates. ## Spot instance retry strategy Spot reclamation interrupts pipeline execution when cloud providers reclaim capacity. The administrator configures the compute environment and Platform settings that make Spot workloads resilient; pipeline developers are responsible for the Nextflow-level retry configuration in their pipelines. Both should be in place before production runs begin. **Administrator configuration** - Decide on the Spot vs On-Demand provisioning model for each production compute environment and configure the retry logic accordingly. - Enable [Fusion Snapshots](https://docs.seqera.io/fusion/guide/snapshots) in the compute environment for Spot workloads. When a Spot instance is reclaimed, Fusion Snapshots allows the interrupted task to resume automatically from a checkpoint rather than restart from scratch. **Pipeline developer configuration** - `aws.batch.maxSpotAttempts` controls how many times a task is retried at the AWS Batch level before Nextflow sees it as a failure. See [Handle retries in AWS](../compute-envs/aws-spot-interruptions#handle-retries-in-aws-by-setting-awsbatchmaxspotattempts). - `errorStrategy` and `maxRetries` in Nextflow handle failures that survive all AWS-native retries. See [Handle retries in Nextflow](../compute-envs/aws-spot-interruptions#handle-retries-in-nextflow-by-setting-errorstrategy-and-maxretries). - Spot to On-Demand fallback logic should be implemented for tasks where interruption is unacceptable. See [Spot to On-Demand fallback](../compute-envs/aws-spot-interruptions#implement-spot-to-on-demand-fallback-logic). :::note `aws.batch.maxSpotAttempts` and Nextflow's `maxRetries` operate at independent layers. AWS-native Spot retries happen silently — Nextflow only sees the task as failed after all AWS retries are exhausted. Pipeline developers must set both values intentionally; neither is configured by Platform automatically. ::: :::note On GCP, Spot preemption notices can be as short as 6 seconds (compared to 120 seconds on AWS), making Fusion Snapshots especially important. Add the following to your Nextflow configuration: ```groovy fusion { enabled = true snapshots = true } ``` ::: ## Connectivity requirements Seqera Platform requires outbound connectivity from compute worker nodes to specific endpoints. Blocked connections cause pipelines to fail to start or stall mid-run. Worker nodes must be able to reach your cloud provider's service endpoints (Batch, EC2, or Compute Engine, object storage, container registry), any container registries used by your pipelines, and any external data sources accessed at runtime. In addition, the following Seqera-operated domains must be reachable from your worker nodes. If your firewall supports DNS wildcards, add `*.seqera.io.cdn.cloudflare.net`. Otherwise, add each domain individually: - `wave.seqera.io` and `community.wave.seqera.io` - `fusionfs.seqera.io` - `nf-xpack.seqera.io` - `cr.seqera.io`, `public.cr.seqera.io`, and `auth.cr.seqera.io` - `hub.seqera.io` - `licenses.seqera.io` - `registry.nextflow.io` — required from Nextflow 25.10 onwards - `api.multiqc.info` - For Seqera Cloud deployments: `cloud.seqera.io` and `api.cloud.seqera.io`. - For Enterprise (self-hosted) deployments: your Platform instance hostname. If your allowlist is based on IP addresses rather than DNS names, allow all Cloudflare IP ranges listed at [https://www.cloudflare.com/ips/](https://www.cloudflare.com/ips/). For a dynamic list of Seqera Platform egress IPs, query `https://meta.seqera.io`. If your environment uses SSL inspection or a corporate proxy, verify that it does not interfere with connections to Seqera Platform endpoints, object storage, or container registries. For Enterprise deployments in restricted or air-gapped environments, configure proxy settings on both the Platform instance and worker nodes, and provision an internal plugin registry to replace `registry.nextflow.io`. :::warning From Nextflow 25.10, `registry.nextflow.io` is required for plugin resolution and is not included in older firewall allowlists. Pipelines will fail to start after upgrading to 25.10 if this domain is blocked. If your organization requires an internal plugin registry instead, see the [Nextflow 25.10 migration guide](https://www.nextflow.io/docs/latest/migrations/25-10.html). ::: :::note If pipelines fail to start or tasks cannot pull container images, connectivity to one of the above endpoints is the most common cause. Check worker node outbound access before investigating other causes. See [Firewall configuration](../enterprise/advanced-topics/firewall-configuration) for the full allowlist reference. ::: --- ## Protein structure prediction This guide details how to perform best-practice analysis for protein 3D structure prediction on an AWS Batch compute environment in Platform. It includes: - Creating AWS Batch compute environments to run your pipeline and downstream analysis - Adding the *nf-core/proteinfold* pipeline to your workspace - Importing your pipeline input data - Launching the pipeline and monitoring execution from your workspace - Setting up a custom analysis environment with Studios :::info[**Prerequisites**] You will need the following to get started: - [Admin](../orgs-and-teams/roles) permissions in an existing organization workspace. See [Set up your workspace](./workspace-setup) to create an organization and workspace from scratch. - An existing AWS cloud account with access to the AWS Batch service. - Existing access credentials with permissions to create and manage resources in your AWS account. See [IAM](../compute-envs/aws-batch#iam-user-creation) for guidance to set up IAM permissions for Platform. ::: ## Compute environment The compute and storage requirements for protein structure prediction depend on the number and length of protein sequences being analyzed and the size of the database used for prediction by the deep learning models, such as AlphaFold2 and ColabFold. Input sequences typically range from a few kilobytes for single proteins to several megabytes for large datasets, and reference databases can be extremely large, from 100 GB to several TB. Protein folding pipelines generate intermediate files during execution, such as for alignments and feature representations, the sizes of which vary based on the number of sequences and the complexity of the analysis. Given the data sizes and computational intensity, production pipelines perform best with NVIDIA A10 or larger GPUs and low-latency, high-throughput cloud storage file handling. ### GPUs The *nf-core/proteinfold* pipeline performs protein folding prediction using one of three deep learning models: AlphaFold2, ColabFold, or ESMFold. The computationally intensive tasks for protein structure prediction perform better on GPUs due to their ability to handle large matrix operations efficiently and perform parallel computations. GPUs can dramatically reduce the time required for protein structure predictions, making it feasible to analyze larger datasets or perform more complex simulations. Platform supports the allocation of both CPUs and GPUs in the same compute environment. For example, specify `m6id`, `c6id`, `r6id`, `g5`, `p3` instance families in the **Instance types** field when creating your AWS Batch compute environment. See [Create compute environment](#create-compute-environment) below. When you launch *nf-core/proteinfold* in Platform, enable **use_gpu** to instruct Nextflow to run GPU-compatible pipeline processes on GPU instances. See [Launch pipeline](#launch-pipeline) below. ### Fusion file system The [Fusion](../supported_software/fusion/overview) file system enables seamless read and write operations to cloud object stores, leading to simpler pipeline logic and faster, more efficient execution. While Fusion is not required to run nf-core/proteinfold, it significantly enhances I/O-intensive tasks and eliminates the need for intermediate data copies, which is particularly beneficial when working with the large databases used by deep learning models for prediction. Fusion works best with AWS NVMe instances (fast instance storage) as this delivers the fastest performance when compared to environments using only AWS EBS (Elastic Block Store). Batch Forge selects instances automatically based on your compute environment configuration, but you can optionally specify instance types. To enable fast instance storage, you must select EC2 instances with NVMe SSD storage (`g4dn`, `g5`, or `P3` families or greater). :::note Fusion requires a license for use in Seqera Platform compute environments or directly in Nextflow. See [Fusion licensing](https://docs.seqera.io/fusion/licensing) for more information. ::: ### Create compute environment :::info The same compute environment can be used for pipeline execution and running your Studios notebook environment, but Studios does not support AWS Fargate. To use this compute environment for both *nf-core/proteinfold* execution and your Studio, leave **Enable Fargate for head job** disabled and include a CPU-based EC2 instance family (`c6id`, `r6id`, etc.) in your **Instance types**. Alternatively, create a second basic AWS Batch compute environment and a Studio with at least 2 CPUs and 8192 MB of RAM. ::: From the **Compute Environments** tab in your organization workspace, select **Add compute environment** and complete the following fields: | **Field** | **Description** | |---------------------------------------|------------------------------------------------------------| | **Name** | A unique name for the compute environment. | | **Platform** | AWS Batch | | **Credentials** | Select existing credentials, or **+** to create new credentials.| | **Access Key** | AWS access key ID. | | **Secret Key** | AWS secret access key. | | **Region** | The target execution region. | | **Pipeline work directory** | An S3 bucket path in the same execution region. | | **Enable Wave Containers** | Use the Wave containers service to provision containers. | | **Enable Fusion v2** | Access your S3-hosted data via the Fusion v2 file system. | | **Enable fast instance storage** | Use NVMe instance storage to speed up I/O and disk access. Requires Fusion v2.| | **Config Mode** | Batch Forge | | **Provisioning Model** | Choose between Spot and On-demand instances. | | **Max CPUs** | Sensible values for production use range between 2000 and 5000.| | **Enable Fargate for head job** | Run the Nextflow head job using the Fargate container service to speed up pipeline launch. Requires Fusion v2. Do not enable for Studios compute environments. | | **Use Amazon-recommended GPU-optimized ECS AMI** | When enabled, Batch Forge specifies the most current AWS-recommended GPU-optimized ECS AMI as the EC2 fleet AMI when creating the compute environment. | | **Allowed S3 buckets** | Additional S3 buckets or paths to be granted read-write permission for this compute environment. For the purposes of this guide, add `s3://proteinfold-dataset` to grant compute environment access to the DB and params used for prediction by AlphaFold2 and ColabFold. | | **Instance types** | Specify the instance types to be used for computation. You must include GPU-enabled instance types (`g4dn`, `g5`) when the Amazon-recommended GPU-optimized ECS AMI is in use. Include CPU-based instance families for Studios compute environments. | | **Resource labels** | `name=value` pairs to tag the AWS resources created by this compute environment.| ## Add pipeline to Platform :::info The [*nf-core/proteinfold*](https://github.com/nf-core/proteinfold) pipeline is a bioinformatics best-practice analysis pipeline for Protein 3D structure prediction. ![nf-core/proteinfold subway map](./_images/nf-core-proteinfold_metro_map_1.1.0.png) ::: [Seqera Pipelines](https://seqera.io/pipelines) is a curated collection of quality open source pipelines that can be imported directly to your workspace Launchpad in Platform. Each pipeline includes a curated test dataset to use in a test run to confirm compute environment compatibility in just a few steps. To use Seqera Pipelines to import the *nf-core/proteinfold* pipeline to your workspace: ![Seqera Pipelines add to Launchpad](./_images/pipelines-add-pf.gif) 1. Search for *nf-core/proteinfold* and select **Launch** next to the pipeline name in the list. In the **Add pipeline** tab, select **Cloud** or **Enterprise** depending on your Platform account type, then provide the information needed for Seqera Pipelines to access your Platform instance: - **Seqera Cloud**: Paste your Platform **Access token** and select **Next**. - **Seqera Enterprise**: Specify the **Seqera Platform URL** (hostname) and **Base API URL** for your Enterprise instance, then paste your Platform **Access token** and select **Next**. :::tip If you do not have a Platform access token, select **Get your access token from Seqera Platform** to open the Access tokens page in a new browser tab. ::: 1. Select your Platform **Organization**, **Workspace**, and **Compute environment** for the imported pipeline. 1. (Optional) Customize the **Pipeline Name** and **Pipeline Description**. 1. Select **Add Pipeline**. :::info To add a custom pipeline not listed in Seqera Pipelines to your Platform workspace, see [Add pipelines](./quickstart-demo/add-pipelines#) for manual Launchpad instructions. ::: ## Pipeline input data The [*nf-core/proteinfold*](https://github.com/nf-core/proteinfold) pipeline works with input datasets (samplesheets) containing sequence names and FASTA file locations (paths to FASTA files in cloud or local storage). The pipeline includes an example samplesheet that looks like this:
**nf-core/proteinfold example samplesheet** | sequence | fasta | | -------- | ----- | | T1024 | https://raw.githubusercontent.com/nf-core/test-datasets/proteinfold/testdata/sequences/T1024.fasta | | T1026 | https://raw.githubusercontent.com/nf-core/test-datasets/proteinfold/testdata/sequences/T1026.fasta |
In Platform, samplesheets and other data can be made easily accessible in one of two ways: - Use **Data Explorer** to browse and interact with remote data from AWS S3, Azure Blob Storage, and Google Cloud Storage repositories, directly in your organization workspace. - Use **Datasets** to upload structured data to your workspace in CSV (Comma-Separated Values) or TSV (Tab-Separated Values) format.
**Add a cloud bucket via Data Explorer** Private cloud storage buckets accessible with the credentials in your workspace are added to Data Explorer automatically by default. However, you can also add custom directory paths within buckets to your workspace to simplify direct access. For example, to add the proteinfold open database to your workspace: ![Add public bucket](./_images/data-explorer-add-proteinfold.gif) 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - The cloud **Provider**: AWS - An existing cloud **Bucket path**: `s3://proteinfold-dataset` - A unique **Name** for the bucket: "proteinfold-dataset" - The **Credentials** used to access the bucket: select **Public**. - An optional bucket **Description**. 1. Select **Add**. You can now select data directly from this bucket as input when launching your pipeline, without the need to interact with cloud consoles or CLI tools.
**Add a dataset** From the **Datasets** tab, select **Add Dataset**. ![Add a dataset](./_images/proteinfold-dataset.gif) Specify the following dataset details: - A **Name** for the dataset, such as `proteinfold_samplesheet`. - A **Description** for the dataset. - Select the **First row as header** option to prevent Platform from parsing the header row of the samplesheet as sample data. - Select **Upload file** and browse to your CSV or TSV samplesheet file in local storage, or simply drag and drop it into the box. The dataset is now listed in your organization workspace datasets and can be selected as input when launching your pipeline. :::info Platform does not store the data used for analysis in pipelines. The dataset must specify the locations of data stored on your own infrastructure. :::
## Launch pipeline :::note This guide is based on [version 1.1.1](https://nf-co.re/proteinfold/1.1.1) of the *nf-core/proteinfold* pipeline. Launch form parameters and tools may differ in other versions. ::: With your compute environment created, *nf-core/proteinfold* added to your workspace Launchpad, and your samplesheet accessible in Platform, you are ready to launch your pipeline. Navigate to the Launchpad and select **Launch** next to *nf-core-proteinfold* to open the launch form. The launch form consists of **General config**, **Run parameters**, and **Advanced options** sections to specify your run parameters before execution, and an execution summary. Use section headings or select the **Previous** and **Next** buttons at the bottom of the page to navigate between sections. ### General config - **Pipeline to launch**: The pipeline Git repository name or URL: `https://github.com/nf-core/proteinfold`. For saved pipelines, this is prefilled and cannot be edited. - **Revision number**: A valid repository commit ID, tag, or branch name: `1.1.1`. For saved pipelines, this is prefilled and cannot be edited. - **Config profiles**: One or more [configuration profile](https://docs.seqera.io/nextflow/config#config-profiles) names to use for the execution. Config profiles must be defined in the `nextflow.config` file in the pipeline repository. Benchmarking runs for this guide used nf-core profiles with included test datasets — `test_full_alphafold2_multimer` for Alphafold2 and `test_full_alphafold2_multimer` for Colabfold. - **Workflow run name**: An identifier for the run, pre-filled with a random name. This can be customized. - **Labels**: Assign new or existing [labels](../labels/overview) to the run. - **Compute environment**: Your AWS Batch compute environment. - **Work directory**: The cloud storage path where pipeline scratch data is stored. Platform will create a scratch sub-folder if only a cloud bucket location is specified. :::note The credentials associated with the compute environment must have access to the work directory. ::: ![General config tab](./_images/proteinfold-lf1.gif) ### Run parameters There are three ways to enter **Run parameters** prior to launch: - The **Input form view** displays form fields to enter text or select attributes from lists, and browse input and output locations with [Data Explorer](../data/data-explorer). - The **Config view** displays raw configuration text that you can edit directly. Select JSON or YAML format from the **View as** list. - **Upload params file** allows you to upload a JSON or YAML file with run parameters. Platform uses the `nextflow_schema.json` file in the root of the pipeline repository to dynamically create a form with the necessary pipeline parameters. ![Run parameters](./_images/proteinfold-lf2.gif) Specify your pipeline input and output and modify other pipeline parameters as needed.
**input** Use **Browse** to select your pipeline input data: - In the **Data Explorer** tab, select the existing cloud bucket that contains your samplesheet, browse or search for the samplesheet file, and select the chain icon to copy the file path before closing the data selection window and pasting the file path in the input field. - In the **Datasets** tab, search for and select your existing dataset.
**outdir** Use the `outdir` parameter to specify where the pipeline outputs are published. `outdir` must be unique for each pipeline run. Otherwise, your results will be overwritten. **Browse** and copy cloud storage directory paths using Data Explorer, or enter a path manually.
- The **mode** menu allows you to select the deep learning model used for structure prediction (`alphafold2`, `colabfold`, or `esmfold`). - Enable **use_gpu** to run GPU-compatible tasks on GPUs. This requires **Use Amazon-recommended GPU-optimized ECS AMI** to be enabled and GPU-enabled instances to be specified under **Instance types** in your compute environment. ![Mode options](./_images/proteinfold-mode.gif) :::info For the purposes of this guide, run the pipeline in both `alphafold2` and `colabfold` modes. Specify unique directory paths for the `outdir` parameter (such as "Alphafold2" and "ColabFold") to ensure output data is kept separate and not overwritten. Predicted protein structures for each model will be visualized side-by-side in the [Interactive analysis](#interactive-analysis-with-studios) section. ::: ### Advanced settings - Use [resource labels](../resource-labels/overview) to tag the computing resources created during the workflow execution. While resource labels for the run are inherited from the compute environment and pipeline, workspace admins can override them from the launch form. Applied resource label names must be unique. - [Pipeline secrets](../secrets/overview) store keys and tokens used by workflow tasks to interact with external systems. Enter the names of any stored user or workspace secrets required for the workflow execution. - See [Advanced options](../launch/advanced) for more details. After you have filled the necessary launch details, select **Launch**. The **Runs** tab shows your new run in a **submitted** status at the top of the list. Select the run name to navigate to the [**View Workflow Run**](../monitoring/overview) page and view the configuration, parameters, status of individual tasks, and run report.
**Run monitoring** Select your new run from the **Runs** tab list to view the run details. #### Run details page As the pipeline runs, run details will populate with the following tabs: - **Command-line**: The Nextflow command invocation used to run the pipeline. This includes details about the pipeline version (`-r` flag) and profile, if specified (`-profile` flag). - **Parameters**: The exact set of parameters used in the execution. This is helpful for reproducing the results of a previous run. - **Resolved Nextflow configuration**: The full Nextflow configuration settings used for the run. This includes parameters, but also settings specific to task execution (such as memory, CPUs, and output directory). - **Execution Log**: A summarized Nextflow log providing information about the pipeline and the status of the run. - **Datasets**: Link to datasets, if any were used in the run. - **Reports**: View pipeline outputs directly in the Platform. ![View the nf-core/rnaseq run](./_images/pf-run-details.gif) #### View reports Most Nextflow pipelines generate reports or output files which are useful to inspect at the end of the pipeline execution. Reports can contain quality control (QC) metrics that are important to assess the integrity of the results. The paths to report files point to a location in cloud storage (in the `outdir` directory specified during launch), but you can view the contents directly and download each file without navigating to the cloud or a remote filesystem. :::info See [Reports](../reports/overview) for more information. ::: #### View general information The run details page includes general information about who executed the run, when it was executed, the Git commit ID and/or tag used, and additional details about the compute environment and Nextflow version used. ![General run information](./_images/pf-run-details-general.gif) #### View details for a task Scroll down the page to view: - The progress of individual pipeline **Processes** - **Aggregated stats** for the run (total walltime, CPU hours) - **Workflow metrics** (CPU efficiency, memory efficiency) - A **Task details** table for every task in the workflow The task details table provides further information on every step in the pipeline, including task statuses and metrics. #### Task details Select a task in the task table to open the **Task details** dialog. The dialog has three tabs: - The **About** tab contains extensive task execution details. - The **Execution log** tab provides a real-time log of the selected task's execution. Task execution and other logs (such as stdout and stderr) are available for download from here, if still available in your compute environment. - The **Data Explorer** tab allows you to view the task working directory directly in Platform. ![Task details window](./_images/pf-task-details.gif) Nextflow hash-addresses each task of the pipeline and creates unique directories based on these hashes. Data Explorer allows you to view the log files and output files generated for each task in its working directory, directly within Platform. You can view, download, and retrieve the link for these intermediate files in cloud storage from the **Data Explorer** tab to simplify troubleshooting.
## Interactive analysis with Studios [Studios](../studios/overview) streamlines the process of creating interactive analysis environments for Platform users. With built-in templates for platforms like Jupyter Notebook, RStudio, and VS Code, creating a Studio is as simple as adding and sharing pipelines or datasets. The Studio URL can also be shared with any user with the [Connect role](../orgs-and-teams/roles) for real-time access and collaboration. For the purposes of this guide, a Jupyter notebook environment will be used for interactive visualization of the predicted protein structures, optionally comparing AlphaFold2 and Colabfold structures for the same sequence data. ### Create a Jupyter notebookStudio From the **Studios** tab, select **Add a Studio** and complete the following: - In the **Compute & Data** tab: - Select your AWS Batch compute environment. :::info The same compute environment can be used for pipeline execution and running your Studios notebook environment, but Studios does not support AWS Fargate and sessions must run on CPUs. To use one compute environment for both *nf-core/proteinfold* execution and your Studio, leave **Enable Fargate for head job** disabled and include at least one CPU-based EC2 instance family (`c6id`, `r6id`, etc.) in your **Instance types**. Alternatively, create a second basic AWS Batch compute environment with at least 2 CPUs and 8192 MB of RAM for your Studio. ::: - Optional: Enter CPU and memory allocations. The default values are 2 CPUs and 8192 MB memory (RAM). :::note Studios compete for computing resources when sharing compute environments. Ensure your compute environment has sufficient resources to run both your pipelines and Studio sessions. ::: - Mount data using Data Explorer: Mount the S3 bucket or directory path that contains the pipeline work directory of your Proteinfold run. - In the **General config** tab: - Select the latest **Jupyter** container image template from the list. - Optional: Enter a unique name and description for the Studio. - Check **Install Conda packages** and paste the following Conda environment YAML snippet: ```yaml channels: - bioconda - conda-forge dependencies: - python=3.10 - conda-forge::biopython=1.84 - conda-forge::nglview=3.1.2 - conda-forge::ipywidgets=8.1.5 ``` - Confirm the Studio details in the **Summary** tab. - Select **Add** and choose whether to add and start the Studio immediately. - When the Studio is created and in a running state, **Connect** to it. ### Visualize protein structures The Jupyter environment can be configured with the packages and scripts you need for interactive analysis. For the purposes of this guide, run the following scripts in individual code cells to install the necessary packages and perform visualization: 1. Import libraries and check versions: ```python print(f"Python version: {sys.version}") print(f"Jupyter version: {jupyter_core.__version__}") print(f"nglview version: {nglview.__version__}") print(f"ipywidgets version: {ipywidgets.__version__}") print(f"Biopython version: {Bio.__version__}") print(f"Operating system: {sys.platform}") print("All required libraries imported successfully.") ``` 1. Define visualization functions: ```python from IPython.display import display, HTML def visualize_protein(pdb_file, width='400px', height='400px'): view = nglview.show_structure_file(pdb_file) view.add_representation('cartoon', selection='protein', color='residueindex') view.add_representation('ball+stick', selection='hetero') view._remote_call('setSize', target='Widget', args=[width, height]) # Set initial view view._remote_call('autoView') view._remote_call('centerView') # Adjust zoom level (you may need to adjust this value) view._remote_call('zoom', target='stage', args=[0.8]) return view def compare_proteins(pdb_files): views = [] for method, file_path in pdb_files.items(): if os.path.exists(file_path): view = visualize_protein(file_path) label = widgets.Label(method) views.append(widgets.VBox([label, view])) return widgets.HBox(views, layout=widgets.Layout(width='100%')) print("Visualization functions defined successfully.") ``` 1. Set up file paths and create file dictionary: ```python # Replace with the actual paths to your AlphaFold2 and ColabFold PDB files alphafold_pdb = "data/path/to/your/alphafold/output.pdb" colabfold_pdb = "data/path/to/your/colabfold/output.pdb" # Create a dictionary of files pdb_files = { "AlphaFold": alphafold_pdb, "ColabFold": colabfold_pdb } print("File paths set up successfully.") ``` 1. Display file information: ```python display(HTML("Protein Structure Prediction Output Files:")) for method, file_path in pdb_files.items(): if os.path.exists(file_path): display(HTML(f"{method}: {file_path}")) else: display(HTML(f"{method}: File not found at {file_path}")) ``` 1. Visualize structures: ```python valid_pdb_files = {method: file_path for method, file_path in pdb_files.items() if os.path.exists(file_path)} if valid_pdb_files: display(HTML("Protein Structure Visualization:")) comparison = compare_proteins(valid_pdb_files) display(comparison) else: display(HTML("No valid PDB files found. Please check the file paths and ensure that the files exist.")) ``` 1. Add interactive elements: ```python if valid_pdb_files: method_drop-down = widgets.Drop-down( options=[method for method, file in valid_pdb_files.items()], description='Select method:', disabled=False, ) info_output = widgets.Output() def on_change(change): with info_output: info_output.clear_output() selected_method = change['new'] selected_file = valid_pdb_files[selected_method] print(f"Selected method: {selected_method}") print(f"File path: {selected_file}") print(f"File size: {os.path.getsize(selected_file) / 1024:.2f} KB") method_drop-down.observe(on_change, names='value') display(HTML("Structure Information:")) display(widgets.VBox([method_drop-down, info_output])) ``` 1. Display usage instructions: ```python display(HTML(""" How to use this visualization: The protein structures from AlphaFold and ColabFold are shown side-by-side above. You can interact with each structure independently: Click and drag to rotate the structure. Scroll to zoom in and out. Right-click and drag to translate the structure. Use the drop-down to select a specific method and view its file information. """)) ``` ![Protein structure visualization](./_images/protein-structure-visualization.gif) --- ## Add data Most bioinformatics pipelines require an input of some sort. This is typically a samplesheet where each row consists of a sample, the location of files for that sample (such as FASTQ files), and other sample details. Reliable shared access to pipeline input data is crucial to simplify data management, minimize user data-input errors, and facilitate reproducible workflows. In Platform, samplesheets and other data can be made easily accessible in one of two ways: - Use **Data Explorer** to browse and interact with remote data from AWS S3, Azure Blob Storage, and Google Cloud Storage repositories, directly in your organization workspace. - Use **Datasets** to upload structured data to your workspace in CSV (Comma-Separated Values) or TSV (Tab-Separated Values) format. ## Data Explorer For pipeline runs in the cloud, users typically need access to buckets or blob storage to upload files (such as samplesheets and reference data) for analysis and to view pipeline results. Managing credentials and permissions for multiple users and training users to navigate cloud consoles and CLIs can be complicated. Data Explorer provides the simplified alternative of viewing your data directly in Platform. ### Add a cloud bucket Private cloud storage buckets accessible by the [credentials](../../credentials/overview) in your workspace are added to Data Explorer automatically by default. However, you can also add custom directory paths within buckets to your workspace to simplify direct access. To add individual buckets (or directory paths within buckets): 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - The cloud **Provider**. - An existing cloud **Bucket path**. - A unique **Name** for the bucket. - The **Credentials** used to access the bucket. For public cloud buckets, select **Public** from the drop-down. - An optional bucket **Description**. 1. Select **Add**. You can now use this data in your analysis without the need to interact with cloud consoles or CLI tools. #### Public data sources Select **Public** from the credentials drop-down to add public cloud storage buckets from resources such as: - [The Cancer Genome Atlas (TCGA)](https://registry.opendata.aws/tcga/) - [1000 Genomes Project](https://registry.opendata.aws/1000-genomes/) - [NCBI SRA](https://registry.opendata.aws/ncbi-sra/) - [Genome in a Bottle Consortium](https://registry.opendata.aws/giab/) - [MSSNG Database](https://research.mss.ng/) - [Genome Aggregation Database (gnomAD)](https://gnomad.broadinstitute.org/) ### View pipeline outputs In Data Explorer, you can: - **View bucket details**: Select the information icon next to a bucket in the list to view the cloud provider, bucket address, and credentials. - **View bucket contents**: Select a bucket name from the list to view the bucket contents. The file type, size, and path of objects are displayed in columns next to the object name. For example, view the outputs of an *nf-core/rnaseq* run: - **Preview files**: Select a file to open a preview window that includes a **Download** button. For example, view the resultant gene counts of the salmon quantification step of an *nf-core/rnaseq* run: ## Datasets Datasets in Platform are CSV (comma-separated values) and TSV (tab-separated values) files stored in a workspace. You can select stored datasets as input data when launching a pipeline.
**Example: nf-core/rnaseq test samplesheet** The [nf-core/rnaseq](https://github.com/nf-core/rnaseq) pipeline works with input datasets (samplesheets) containing sample names, FASTQ file locations, and indications of strandedness. The Seqera Community Showcase sample dataset for nf-core/rnaseq specifies the paths to seven small sub-sampled FASTQ files from a yeast RNAseq dataset: **Example nf-core/rnaseq dataset** | sample | fastq_1 | fastq_2 | strandedness | | ------------------- | ------------------------------------ | ------------------------------------ | ------------ | | WT_REP1 | s3://nf-core-awsmegatests/rnaseq/... | s3://nf-core-awsmegatests/rnaseq/... | reverse | | WT_REP1 | s3://nf-core-awsmegatests/rnaseq/... | s3://nf-core-awsmegatests/rnaseq/... | reverse | | WT_REP2 | s3://nf-core-awsmegatests/rnaseq/... | s3://nf-core-awsmegatests/rnaseq/... | reverse | | RAP1_UNINDUCED_REP1 | s3://nf-core-awsmegatests/rnaseq/... | | reverse | | RAP1_UNINDUCED_REP2 | s3://nf-core-awsmegatests/rnaseq/... | | reverse | | RAP1_UNINDUCED_REP2 | s3://nf-core-awsmegatests/rnaseq/... | | reverse | | RAP1_IAA_30M_REP1 | s3://nf-core-awsmegatests/rnaseq/... | s3://nf-core-awsmegatests/rnaseq/... | reverse |
Download the nf-core/rnaseq [samplesheet_test.csv](samplesheet_test.csv). ### Add a dataset From the **Datasets** tab, select **Add Dataset**. Specify the following dataset details: - A **Name** for the dataset, such as `nf-core-rnaseq-test-dataset`. - A **Description** for the dataset. - Select the **First row as header** option to prevent Platform from parsing the header row of the samplesheet as sample data. - Select **Upload file** and browse to your CSV or TSV file in local storage, or simply drag and drop it into the box. Notice the location of the files in the *nf-core/rnaseq* example dataset point to a path on S3. This could also be a path to a shared filesystem, if using an HPC compute environment. Nextflow will use these paths to stage the files into the task working directory. :::info Platform does not store the data used for analysis in pipelines. The datasets must provide the locations of data that is stored on your own infrastructure. ::: --- ## Add pipelines The Launchpad lists the preconfigured Nextflow pipelines that you can run on the [compute environments](../../compute-envs/overview) in your workspace. You can import pipelines to your workspace Launchpad in two ways: directly from Seqera Pipelines, or manually with **Add pipeline** in Seqera Platform. ## Import from Seqera Pipelines [Seqera Pipelines](https://seqera.io/pipelines) is a curated collection of open-source pipelines that you can import directly to your workspace Launchpad. Each pipeline includes a dataset for a test run that confirms compute environment compatibility. To import a pipeline: 1. Select **Launch** next to the pipeline name in the list. In the **Add pipeline** tab, select **Cloud** or **Enterprise** depending on your Platform account type, then provide the information needed for Seqera Pipelines to access your Platform instance: - **Seqera Cloud**: Paste your Platform **Access token** and select **Next**. - **Seqera Enterprise**: Specify the **Seqera Platform URL** (hostname) and **Base API URL** for your Enterprise instance, then paste your Platform **Access token** and select **Next**. :::note If you do not have a Platform access token, select **Get your access token from Seqera Platform** to open the Access tokens page in a new browser window. ::: 1. Select the Platform **Organization**, **Workspace**, and **Compute environment** for the imported pipeline. 1. (Optional) Customize the **Pipeline Name** and **Pipeline Description**. :::note Pipeline names must be unique per workspace. ::: 1. Select **Add Pipeline**. ## Add from the Launchpad From your workspace Launchpad, select **Add Pipeline** and specify the following pipeline details: - (Optional) **Image**: Select the **Edit** icon on the pipeline image to open the **Edit image** window. From here, select **Upload file** to browse for an image file, or drag and drop the image file directly. Images must be in JPG or PNG format, with a maximum file size of 200 KB. :::note You can upload custom icons when adding or updating a pipeline. If no user-uploaded icon is defined, Platform retrieves and attaches a pipeline icon in the following order of precedence: 1. A valid `icon` key:value pair defined in the `manifest` object of the `nextflow.config` file. 2. The GitHub organization avatar (if the repository is hosted on GitHub). 3. If none of the above are defined, Platform auto-generates and attaches a pipeline icon. ::: - **Name**: A custom name of your choice. Pipeline names must be unique per workspace. - (Optional) **Description**: A summary of the pipeline, or any information useful to workspace participants when they select a pipeline to launch. - (Optional) **Labels**: Categorize the pipeline by criteria such as research group or reference genome version to help workspace participants select the right pipeline for their analysis. - **Compute environment**: Select an existing workspace [compute environment](../../compute-envs/overview). - **Pipeline to launch**: The URL of any public or private Git repository that contains Nextflow source code. - **Revision**: A valid repository commit ID, tag, or branch name. Determines the version of the pipeline to launch. :::tip Selecting a specific pipeline version is important for reproducibility. Each run with the same input data then generates the same results. ::: - **Commit ID**: Pin pipeline revision to the most recent HEAD commit ID. If no commit ID is pinned, the latest revision of the repository branch or tag is used. - **Pull latest**: Fetch the most recent HEAD commit ID of the pipeline revision at launch time. Unpins the **Commit ID**, if set. :::info See [Git revision management](../../pipelines/revision.md) for more information on **Commit ID**, **Pull latest**, and **Revision** behavior. ::: - (Optional) **Config profiles**: Select a predefined profile for the Nextflow pipeline. :::info nf-core pipelines include a `test` profile that is associated with a minimal test dataset. This profile runs the pipeline with heavily sub-sampled input data for the purposes of [CI/CD](https://resources.github.com/devops/ci-cd/) and to quickly confirm that the pipeline runs on your infrastructure. ::: - (Optional) **Pipeline parameters**: Set custom pipeline parameters that are prepopulated when users launch the pipeline from the Launchpad. For example, set the path to local reference genomes so users don't need to locate these files at launch. - (Optional) **Pre-run script**: Define Bash code that executes before the pipeline launches in the same environment where Nextflow runs. :::info Pre-run scripts are useful for defining executor settings, troubleshooting, and defining a specific version of Nextflow with the `NXF_VER` environment variable. ::: After you fill in the fields, select **Add**. Your pipeline is now available for workspace participants to launch in the preconfigured compute environment. --- ## Automation Seqera Platform provides several programmatic interfaces to automate pipeline execution, chain pipelines together, and integrate Platform with third-party services. ## Platform API The Seqera Platform public API is the lowest-level programmatic interface. It can perform every operation available in the user interface. Use the API to launch pipelines in response to a file event (such as a file upload to a bucket) or the completion of a previous run. The API is available at `https://api.cloud.seqera.io`. The full list of endpoints is available in Seqera's [OpenAPI schema](https://cloud.seqera.io/openapi/index.html). Every API request requires an authentication token. Create one from your user menu under **Your tokens**. The token is displayed only once. Store it securely and use it to authenticate API requests.
**Example pipeline launch API request** ``` curl -X POST "https://api.cloud.seqera.io/workflow/launch?workspaceId=38659136604200" \ -H "Accept: application/json" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept-Version:1" \ -d '{ "launch": { "computeEnvId": "hjE97A8TvD9PklUb0hwEJ", "runName": "first-time-pipeline-api-byname", "pipeline": "first-time-pipeline", "workDir": "s3://nf-ireland", "revision": "master" } }' ```
### Find your organization and workspace IDs Many API endpoints take an organization ID (for example, `org/{orgId}/workspaces`) or a workspace ID (for example, the `workspaceId` query parameter). The two are different numeric values: a workspace ID used where an endpoint expects an organization ID returns a permission error. - **Organization ID**: Select your organization, then **Settings**. The organization ID is the numeric value in the page URL. - **Workspace ID**: Select your organization, then the **Workspaces** tab. Each workspace lists its ID. To retrieve these IDs from the command line, use `tw organizations list` and `tw workspaces list`. ## Platform CLI For bioinformaticians and scientists who prefer the command line, Platform provides `tw`, a command-line tool to manage resources. Use the CLI to launch pipelines, manage compute environments, retrieve run metadata, and monitor runs on Platform. It provides a Nextflow-like experience and lets you store Seqera resource configuration, such as pipelines and compute environments, as code. The CLI is built on the [Seqera Platform API](#platform-api) but is simpler to use. For example, you can refer to resources by name instead of by unique identifier. ![Seqera Platform CLI](./assets/platform-cli.png) See [CLI](https://docs.seqera.io/platform-cli) for installation and usage details.
**Example pipeline launch CLI command** ```bash tw launch hello --workspace community/showcase ```
## seqerakit `seqerakit` is a Python wrapper for the Platform CLI that automates the creation of Platform entities from a single YAML configuration file. It can create everything from organizations and workspaces to pipelines and compute environments, and launch workflows. The key features are: - **Simple configuration**: Define all Platform CLI command-line options in YAML format. - **Infrastructure as code**: Manage and provision your infrastructure specifications. - **Automation**: Create entities end-to-end, from adding an organization to launching pipelines within it. See the [seqerakit GitHub repository](https://github.com/seqeralabs/seqera-kit/) for installation and usage details.
**Example pipeline launch seqerakit configuration and command** Create a YAML file called `hello.yaml`: ```yaml launch: - name: "hello-world" url: "https://github.com/nextflow-io/hello" workspace: "seqeralabs/showcase" ``` Then run seqerakit: ```bash $ seqerakit hello.yaml ```
## Resources Common use cases for these automation methods include executing a pipeline as data arrives from a sequencer, or integrating Platform into a broader user-facing application. For a step-by-step guide to setting up these automation methods, see [Workflow automation for Nextflow pipelines](https://seqera.io/blog/workflow-automation/). For examples of how to use automation methods, see [Automating pipeline execution with Nextflow and Tower](https://seqera.io/blog/automating-workflows-with-nextflow-and-tower/). --- ## Launch pipelines From the Launchpad in every workspace, you can create and share Nextflow pipelines that run on any supported infrastructure, including all public clouds and most HPC schedulers. A Launchpad pipeline consists of a preconfigured workflow Git repository, [compute environment](../../compute-envs/overview), and launch parameters. This tutorial walks you through launching the nf-core/rnaseq pipeline. :::info[**Prerequisites**] You need the following: - An organization and workspace. See [Set up an organization and workspace](../workspace-setup). - A workspace [compute environment](../../compute-envs/overview) for your cloud or HPC compute infrastructure. - A [pipeline](./add-pipelines) added to your workspace. - [Pipeline input data](./add-data) added to your workspace. ::: ## Launch a pipeline Navigate to the Launchpad and select **Launch** next to your pipeline to open the launch form. The launch form consists of **General config**, **Run parameters**, and **Advanced options** sections to specify your run parameters before execution, and an execution summary. Use section headings or select the **Previous** and **Next** buttons at the bottom of the page to navigate between sections.
Nextflow parameter schema The launch form configures the pipeline run. Platform renders the pipeline parameters in this form from a [pipeline schema](../../pipeline-schema/overview) file in the root of the pipeline Git repository. `nextflow_schema.json` is a JSON-based schema that describes pipeline parameters. Pipeline developers use it to adapt their in-house Nextflow pipelines to run in Platform. :::tip See [Best Practices for Deploying Pipelines with the Seqera Platform](https://seqera.io/blog/best-practices-for-deploying-pipelines-with-seqera-platform/) to learn how to build the parameter schema for any Nextflow pipeline automatically with tooling maintained by the nf-core community. :::
### General config - **Pipeline to launch**: The pipeline Git repository name or URL. For saved pipelines, this is prefilled and cannot be edited. - **Version name**: The version that will be selected as default for this pipeline. - **Version ID**: The ID of the pipeline version. - **Revision**: A valid repository commit ID, tag, or branch name. Determines the version of the pipeline to launch. - **Commit ID**: Pin pipeline revision to the most recent HEAD commit ID. If no commit ID is pinned, the latest revision of the repository branch or tag is used. - **Pull latest**: Fetch the most recent HEAD commit ID of the pipeline revision at launch time. Unpins the **Commit ID**, if set. :::info See [Git revision management](../../pipelines/revision.md) for more information on **Commit ID**, **Pull latest**, and **Revision** behavior. ::: - **Main script**: The script file to execute (default: `main.nf`). Config profiles suggestions may update when this field changes. - **Config profiles**: One or more [configuration profile](https://docs.seqera.io/nextflow/config#config-profiles) names to use for the execution. - **Workflow run name**: An identifier for the run, pre-filled with a random name. This can be customized. - **Labels**: Assign new or existing [labels](../../labels/overview) to the run. - **Compute environment**: Select an existing workspace [compute environment](../../compute-envs/overview). - **Work directory**: The (cloud or local) file storage path where pipeline scratch data is stored. If you specify only a cloud bucket location, Platform creates a scratch subfolder. :::note The credentials associated with the compute environment must have access to the work directory. ::: - **Schema**: The schema to validate pipeline parameters and prevent runtime failures. - **Repository default**: The default schema provided by the pipeline repository. - **Repository path**: A schema at a specific path in the repository. - **Seqera Platform schema**: A schema stored in Seqera Platform. ### Run parameters There are three ways to enter **Run parameters** prior to launch: - The **Input form view** displays form fields to enter text or select attributes from lists, and browse input and output locations with [Data Explorer](../../data/data-explorer). - The **Config view** displays raw configuration text that you can edit directly. Select JSON or YAML format from the **View as** list. - **Upload params file** allows you to upload a JSON or YAML file with run parameters. Specify your pipeline input and output and modify other pipeline parameters as needed: #### input Use **Browse** to select your pipeline input data: - In the **Data Explorer** tab, select the existing cloud bucket that contains your samplesheet, browse or search for the samplesheet file, and select the chain icon to copy the file path before closing the data selection window and pasting the file path in the input field. - In the **Datasets** tab, search for and select your existing dataset. #### outdir Use the `outdir` parameter to specify where the pipeline publishes outputs. `outdir` must be unique for each run to avoid overwriting results from a previous run. **Browse** and copy cloud storage directory paths using Data Explorer, or enter a path manually. #### Pipeline-specific parameters Modify other parameters to customize the pipeline execution through the parameters form. For example, in [nf-core/rnaseq](https://github.com/nf-core/rnaseq) (version 3.15.1), change the `trimmer` under **Read trimming options** to `fastp` instead of `trimgalore`. ![Read trimming options](./assets/trimmer-settings.png) ### Advanced settings - Use [resource labels](../../resource-labels/overview) to tag the computing resources created during the workflow execution. While resource labels for the run are inherited from the compute environment and pipeline, workspace admins can override them from the launch form. Applied resource label names must be unique. - Use [Pipeline secrets](../../secrets/overview) to store keys and tokens used by workflow tasks to interact with external systems. Enter the names of any stored user or workspace secrets required for the workflow execution. - See [Advanced options](../../launch/advanced) for more details. After you fill in the launch details, select **Launch**. The **Runs** tab shows your new run in a **submitted** status at the top of the list. Select the run name to open the [**View Workflow Run**](../../monitoring/overview) page, where you can view the configuration, parameters, status of individual tasks, and run report. --- ## Monitor runs After you [launch a pipeline](./launch-pipelines), Seqera Platform provides three views to monitor the progress and status of your runs: - The [**Runs** page](#runs) lists the runs in a single workspace. - The [**All runs** page](#all-runs) lists runs across all your organizations and workspaces. - The [**Dashboard**](#dashboard) summarizes run status totals across all your organizations and workspaces. ## Runs Select **Runs** in the left-hand navigation to view the full run history of a workspace. Each row corresponds to one run and displays its status. Select a run to view its [run details](../../monitoring/run-details), including the tasks, jobs, metrics, configuration, inputs, outputs, containers, and run info. ## All runs Access the **All runs** page from the user menu. This page lists runs across the entire Platform instance. The default view includes all organizations and workspaces you can access. To limit the view to specific workspaces, select the drop-down next to **View**. Filter the list with free text and one or more `keyword:value` terms in the search field: - `status`: Runs with a given status: `submitted`, `running`, `succeeded`, `failed`, `cancelled`, or `unknown`. - `label`: Runs with a given label. Repeat the keyword to filter by multiple labels. - `workflowId`: The run with a given workflow ID. - `runName`: Runs with a given run name. - `username`: Runs launched by a given user. - `projectName`: Runs of a given pipeline project. - `after`: Runs submitted on or after a date, in `YYYY-MM-DD` format. - `before`: Runs submitted on or before a date, in `YYYY-MM-DD` format. - `sessionId`: Runs with a given Nextflow session ID. - `is:starred`: Runs you have starred. Keyword terms use exact matches and combine with AND logic. Free text matches partially against the run name, project name, session ID, and manifest name. For example, to list the successful runs launched by `johndoe` after January 1, 2024 that match `rnaseq`: ```console rnaseq username:johndoe status:succeeded after:2024-01-01 ``` See [All runs view](../../monitoring/overview#all-runs-view) for the full search syntax. ## Dashboard Access the **Dashboard** from the user menu. This page displays run totals across the Platform instance, grouped by run status. The default view includes all organizations and workspaces you can access: - To limit the view to specific workspaces, select the drop-down next to **View**. - To filter by time, select a preset period or a custom date range of up to 12 months. Times are displayed in the local timezone defined in your device's system settings. - To download the displayed data as a CSV file, select **Export data**. See [Dashboard](../../monitoring/dashboard) for the Studios, Fusion, and resource usage views. --- ## Pipeline optimization(Quickstart-demo) Seqera Platform's task-level resource usage metrics allow you to determine the resources requested for a task and what was actually used. This information helps you fine-tune your configuration more accurately. However, manually adjusting resources for every task in your pipeline is impractical. Instead, you can leverage the pipeline optimization feature available on the Launchpad. Pipeline optimization analyzes resource usage data from previous runs to optimize the resource allocation for future runs. After a successful run, optimization becomes available, indicated by the lightbulb icon next to the pipeline turning black. ### Optimize nf-core/rnaseq Navigate back to the Launchpad and select the lightbulb icon next to the *nf-core/rnaseq* pipeline to view the optimized profile. You have the flexibility to tailor the optimization's target settings and incorporate a retry strategy as needed. ### View optimized configuration When you select the lightbulb, you can access an optimized configuration profile in the second tab of the **Customize optimization profile** window. This profile consists of Nextflow configuration settings for each process and each resource directive (where applicable): **cpus**, **memory**, and **time**. The optimized setting for a given process and resource directive is based on the maximum use of that resource across all tasks in that process. Once optimization is selected, subsequent runs of that pipeline will inherit the optimized configuration profile, indicated by the black lightbulb icon with a checkmark. :::note Optimization profiles are generated from one run at a time, defaulting to the most recent run, and _not_ an aggregation of previous runs. ::: ![Optimized configuration](assets/optimize-configuration.gif) Verify the optimized configuration of a given run by inspecting the resource usage plots for that run and these fields in the run's task table: | Description | Key | | ------------ | ---------------------- | | CPU usage | `pcpu` | | Memory usage | `peakRss` | | Runtime | `start` and `complete` | --- ## Studios(Quickstart-demo) :::info This guide provides an introduction to Studios using a demo Studio in the Community Showcase workspace. See [Studios](../../studios/overview) to learn how to create Studios in your own workspace. ::: Interactive analysis of pipeline results is often performed in platforms like Jupyter Notebook or an R-IDE. Setting up the infrastructure for these platforms, including accessing pipeline data and the necessary bioinformatics packages, can be complex and time-consuming. Studios streamlines the process of creating interactive analysis environments for Platform users. With built-in templates, creating a Studio is as simple as adding and sharing pipelines or datasets. Platform manages all the details, enabling you to easily select your preferred interactive tool and analyze your data. In the **Studios** tab, you can monitor and see the details of the Studios in the Community Showcase workspace. Select the options menu next to a Studio to: - See Studio details - Start or stop the Studio, and connect to a running Studio session - Copy the Studio URL to share it with collaborators ### Analyze RNAseq data in Studios Studios is used to perform bespoke analysis on the results of upstream workflows. For example, in the Community Showcase workspace we have run the *nf-core/rnaseq* workflow to quantify gene expression, followed by *nf-core/differentialabundance* to derive differential expression statistics. The workspace contains a Studio with these results from cloud storage mounted into the Studio to perform further analysis. One of these outputs is a web app, which can be deployed for interactive analysis. ### Open the RNAseq analysis Studio Select the *rnaseq_to_differentialabundance* Studio. This Studio consists of an R-IDE that uses an existing compute environment available in the showcase workspace. The Studio also contains mounted data generated from the *nf-core/rnaseq* and subsequent *nf-core/differentialabundance* pipeline runs, directly from AWS S3. :::info Studios allows you to specify the resources each Studio will use. When [creating your own Studios](../../studios/overview) with shared compute environment resources, you must allocate sufficient resources to the compute environment to prevent Studio or pipeline run interruptions. ::: ### Connect to the Studio This Studio will start an R-IDE which already contains the necessary R packages for deploying a web app to interact with various visualizations of the RNAseq data. The Studio also contains an R Markdown document with the commands in place to generate the application. Deploy the web app in the Studio by selecting the play button on the last chunk of the R script: ![Run RShiny app](./assets/rnaseq-diffab-run-rshiny-app.png) ### Explore results in the web app The web app will deploy in a separate browser window, providing a data interface. Here you can view information about your sample data, perform QC or exploratory analysis, and view the differential expression analyses. #### Sample clustering with PCA plots In the **QC/Exploratory** tab, select the PCA (Principal Component Analysis) plot to visualize how the samples group together based on their gene expression profiles. In this example, we used RNA sequencing data from the publicly-available ENCODE project, which includes samples from four different cell lines: - **GM12878**: a lymphoblastoid cell line - **K562**: a chronic myelogenous leukemia cell line - **MCF-7**: a breast cancer cell line - **H1-hESC**: a human embryonic stem cell line What to look for in the PCA plot: - **Replicate clustering**: Ideally, replicates of the same cell type should cluster closely together. For example, replicates of the MCF-7 cells group together. This indicates consistent gene expression profiles among replicates. - **Cell type separation**: Different cell types should form distinct clusters. For instance, GM12878, K562, MCF-7, and H1-hESC cells should each form their own separate clusters, reflecting their unique gene expression patterns. From this PCA plot, you can gain insights into the consistency and quality of your sequencing data, identify any potential issues, and understand the major sources of variation among your samples - all directly in Platform. #### Gene expression changes with Volcano plots In the **Differential** tab, select **Volcano plots** to compare genes with significant changes in expression between two samples. For example, filter for `Type: H1 vs MCF-7` to view the differences in expression between these two cell lines. 1. **Identify upregulated and downregulated genes**: The x-axis of the volcano plot represents the log2 fold change in gene expression between the H1 and MCF-7 cell lines, while the y-axis represents the statistical significance of the changes. - **Upregulated genes in MCF-7**: Genes on the left side of the plot (negative fold change) are upregulated in the MCF-7 samples compared to H1. For example, the _SHH_ gene, which is known to be upregulated in cancer cell lines, prominently appears here. 2. **Filtering for specific genes**: If you are interested in specific genes, use the filter function. For example, filter for the _SHH_ gene in the table below the plot. This allows you to quickly locate and examine this gene in more detail. 3. **Gene expression bar plot**: After filtering for the _SHH_ gene, select it to navigate to a gene expression bar plot. This plot will show you the expression levels of _SHH_ across all samples, allowing you to see in which samples it is most highly expressed. - Here, _SHH_ is most highly expressed in MCF-7, which aligns with its known role in cancer cell proliferation. Using the volcano plot, you can effectively identify and explore the genes with the most significant changes in expression between your samples, providing a deeper understanding of the molecular differences. ![RShiny volcano plot](assets/rnaseq-diffab-rshiny-volcano-plot.gif) ### Collaborate in the Studio To share the results of your RNAseq analysis or allow colleagues to perform exploratory analysis, share a link to the Studio by selecting the options menu for the Studio you want to share, then select **Copy Studio URL**. With this link, other authenticated users with the **Connect** [role](../../orgs-and-teams/roles) (or greater) can access the session directly. --- ## View run information When you launch a pipeline, you are directed to the **Runs** tab, which contains all runs in the workspace, with your submitted run at the top of the list. Each new or resumed run is given a random name, which can be customized prior to launch. Each row corresponds to a specific run. As a job executes, it can transition through the following states: - **submitted**: Pending execution - **running**: Running - **succeeded**: Completed successfully - **failed**: Successfully executed, where at least one task failed with a terminate error strategy - **cancelled**: Stopped forcibly during execution - **unknown**: Indeterminate status ### View run details for *nf-core/rnaseq* The pipeline launched [previously](./launch-pipelines) is listed on the **Runs** tab. Select it from the list to view the run details. #### Run details page As the pipeline runs, the run details populate with the following tabs: - **Command-line**: The Nextflow command invocation used to run the pipeline. This contains details about the pipeline version (`-r 3.14.0` flag) and profile, if specified (`-profile test` flag). - **Parameters**: The exact set of parameters used in the execution. This is helpful for reproducing the results of a previous run. - **Configuration**: The full Nextflow configuration settings used for the run. This includes parameters, but also settings specific to task execution (such as memory, CPUs, and output directory). - **Datasets**: Link to datasets, if any were used in the run. - **Execution Log**: A summarized Nextflow log with information about the pipeline and the status of the run. - **Reports**: View pipeline outputs directly in Platform. {/* TODO (EDU-842): replace with updated screenshot of the run details page */} ### View reports Most Nextflow pipelines generate reports or output files worth inspecting at the end of a run. Reports can contain quality control (QC) metrics to assess the integrity of the results. ![Reports tab](assets/reports-tab.png) For example, for the *nf-core/rnaseq* pipeline, view the generated [MultiQC](https://docs.seqera.io/multiqc) report. MultiQC generates aggregate statistics and summaries from bioinformatics tools. ![Reports MultiQC preview](assets/reports-preview.png) The paths to report files point to a location in cloud storage (in the `outdir` directory specified during launch), but you can view the contents directly and download each file without navigating to the cloud or a remote filesystem. #### Specify outputs in reports To tell Platform where to find the reports generated by the pipeline, include a [tower.yml](https://github.com/nf-core/rnaseq/blob/master/tower.yml) file that lists the report locations in the pipeline repository. In the *nf-core/rnaseq* pipeline, the `MULTIQC` process step generates a MultiQC report file in HTML format: ```yaml reports: multiqc_report.html: display: "MultiQC HTML report" ``` :::info See [Reports](../../reports/overview) to configure reports for pipeline runs in your own workspace. ::: ### View general information The run details page includes general information about who executed the run and when, the Git hash and tag used, and additional details about the compute environment and Nextflow version used. {/* TODO (EDU-842): replace with updated screenshot of the General run information panel */} The **General** panel displays top-level information about a pipeline run: - Unique workflow run ID - Workflow run name - Timestamp of pipeline start (the time displayed is based on your local timezone defined in your device's system settings) - Pipeline version and Git commit ID - Nextflow session ID - Username of the launcher - Work directory path ### View details for a task Scroll down the page to view: - The progress of individual pipeline **Processes** - **Aggregated stats** for the run (total walltime, CPU hours) - A **Task details** table for every task in the workflow - **Workflow metrics** (CPU efficiency, memory efficiency) The task details table provides further information on every step in the pipeline, including task statuses and metrics. ### Task details Select a task in the task table to open the **Task details** dialog. The dialog has three tabs: **About**, **Execution log**, and **Data Explorer**. #### About The **About** tab includes: 1. **Name**: Process name and tag 2. **Command**: Task script, defined in the pipeline process 3. **Status**: Exit code, task status, and number of attempts 4. **Work directory**: Directory where the task was executed 5. **Environment**: Environment variables that were supplied to the task 6. **Execution time**: Metrics for task submission, start, and completion time (the time displayed is based on your local timezone defined in your device's system settings) 7. **Resources requested**: Metrics for the resources requested by the task 8. **Resources used**: Metrics for the resources used by the task {/* TODO (EDU-842): replace with updated screenshot of the Task details dialog */} #### Execution log The **Execution log** tab provides a real-time log of the selected task's execution. You can download task execution and other logs (such as stdout and stderr) here, if they remain in your compute environment. ### Task work directory in Data Explorer If a task fails, a good place to begin troubleshooting is the task's work directory. Nextflow hash-addresses each task of the pipeline and creates unique directories based on these hashes. Instead of navigating through a bucket on the cloud console or filesystem to find the contents of this directory, use the **Data Explorer** tab in the Task window to view the work directory. Data Explorer shows the log files and output files generated for each task in its working directory, directly within Platform. You can view, download, and copy the link for these intermediate files in cloud storage from the **Data Explorer** tab to simplify troubleshooting. {/* TODO (EDU-842): replace with updated screenshot of the task Data Explorer tab */} ### Resume a pipeline Platform uses [Nextflow resume](../../launch/cache-resume) to resume a failed or cancelled workflow run with the same parameters, using the cached results of previously completed tasks and only executing failed and pending tasks. ![Resume a run](assets/sp-cloud-resume-a-run.gif) :::info To resume a run in your own workspace: - Select **Resume** from the options menu next to the run. - Edit the parameters before launch, if needed. - If you have the appropriate [permissions](../../orgs-and-teams/roles), you may edit the compute environment if needed. ::: --- ## RNA-Seq This guide details how to run bulk RNA sequencing (RNA-Seq) data analysis, from quality control to differential expression analysis, on an AWS Batch compute environment in Platform. It includes: - Creating an AWS Batch compute environment to run your pipeline and analysis environment - Adding pipelines to your workspace - Importing your pipeline input data - Launching the pipeline and monitoring execution from your workspace - Setting up a custom analysis environment with Studios - Resource allocation guidance for RNA-Seq data :::info[**Prerequisites**] You will need the following to get started: - [Admin](../orgs-and-teams/roles) permissions in an existing organization workspace. See [Set up your workspace](./workspace-setup) to create an organization and workspace from scratch. - An existing AWS cloud account with access to the AWS Batch service. - Existing access credentials with permissions to create and manage resources in your AWS account. See [IAM](../compute-envs/aws-batch#iam-user-creation) for guidance to set up IAM permissions for Platform. ::: ## Compute environment Compute and storage requirements for RNA-Seq analysis are dependent on the number of samples and the sequencing depth of your input data. See [RNA-Seq data and requirements](#rna-seq-data-and-requirements) for details on RNA-Seq datasets and the CPU and memory requirements for important steps of RNA-Seq pipelines. In this guide, you will create an AWS Batch compute environment with sufficient resources allocated to run the [nf-core/rnaseq](https://github.com/nf-core/rnaseq) pipeline with a large dataset. This compute environment will also be used to run a Studios R-IDE session for interactive analysis of the resulting pipeline data. :::note The compute recommendations below are based on internal benchmarking performed by Seqera. See [RNA-Seq data and requirements](#rna-seq-data-and-requirements) for more information. ::: ### Recommended compute environment resources The following compute resources are recommended for production RNA-Seq pipelines, depending on the size of your input dataset: | **Setting** | **Value** | |--------------------------------|---------------------------------------| | **Instance Types** | `m5,r5` | | **vCPUs** | 2 - 8 | | **Memory (GiB)** | 8 - 32 | | **Max CPUs** | >500 | | **Min CPUs** | 0 | #### Fusion file system The [Fusion](../supported_software/fusion/overview) file system enables seamless read and write operations to cloud object stores, leading to simpler pipeline logic and faster, more efficient execution. While Fusion is not required to run *nf-core/rnaseq*, it is recommended for optimal performance. See [nf-core/rnaseq performance in Platform](#nf-corernaseq-performance-in-platform) at the end of this guide. Fusion works best with AWS NVMe instances (fast instance storage) as this delivers the fastest performance when compared to environments using only AWS EBS (Elastic Block Store). Batch Forge selects instances automatically based on your compute environment configuration, but you can optionally specify instance types. To enable fast instance storage (see Create compute environment below), you must select EC2 instances with NVMe SSD storage (`m5d` or `r5d` families). :::note Fusion requires a license for use in Seqera Platform compute environments or directly in Nextflow. See [Fusion licensing](https://docs.seqera.io/fusion/licensing) for more information. ::: ### Create compute environment From the **Compute Environments** tab in your organization workspace, select **Add compute environment** and complete the following fields: | **Field** | **Description** | |---------------------------------------|------------------------------------------------------------| | **Name** | A unique name for the compute environment. | | **Platform** | AWS Batch | | **Credentials** | Select existing credentials, or **+** to create new credentials:| | **Access Key** | AWS access key ID. | | **Secret Key** | AWS secret access key. | | **Region** | The target execution region. | | **Pipeline work directory** | An S3 bucket path in the same execution region. | | **Enable Wave Containers** | Use the Wave containers service to provision containers. | | **Enable Fusion v2** | Access your S3-hosted data via the Fusion v2 file system. | | **Enable fast instance storage** | Use NVMe instance storage to speed up I/O and disk access. Requires Fusion v2.| | **Config Mode** | Batch Forge | | **Provisioning Model** | Choose between Spot and On-demand instances. | | **Max CPUs** | Sensible values for production use range between 2000 and 5000.| | **Enable Fargate for head job** | Run the Nextflow head job using the Fargate container service to speed up pipeline launch. Requires Fusion v2.| | **Allowed S3 buckets** | Additional S3 buckets or paths to be granted read-write permission for this compute environment. Add data paths to be mounted in your data studio here, if different from your pipeline work directory.| | **Resource labels** | `name=value` pairs to tag the AWS resources created by this compute environment.| ## Add pipeline to Platform :::info The [nf-core/rnaseq](https://github.com/nf-core/rnaseq) pipeline is a highly configurable and robust workflow designed to analyze RNA-Seq data. It performs quality control, alignment and quantification. ![nf-core/rnaseq subway map](./_images/nf-core-rnaseq_metro_map_grey_static.svg) ::: [Seqera Pipelines](https://seqera.io/pipelines) is a curated collection of quality open-source pipelines that can be imported directly to your workspace Launchpad in Platform. Each pipeline includes a dataset to use in a test run to confirm compute environment compatibility in just a few steps. To use Seqera Pipelines to import the *nf-core/rnaseq* pipeline to your workspace: ![Seqera Pipelines add to Launchpad](./_images/pipelines-add.gif) 1. Search for *nf-core/rnaseq* and select **Launch** next to the pipeline name in the list. In the **Add pipeline** tab, select **Cloud** or **Enterprise** depending on your Platform account type, then provide the information needed for Seqera Pipelines to access your Platform instance: - **Seqera Cloud**: Paste your Platform **Access token** and select **Next**. - **Seqera Enterprise**: Specify the **Seqera Platform URL** (hostname) and **Base API URL** for your Enterprise instance, then paste your Platform **Access token** and select **Next**. :::tip If you do not have a Platform access token, select **Get your access token from Seqera Platform** to open the Access tokens page in a new browser tab. ::: 1. Select your Platform **Organization**, **Workspace**, and **Compute environment** for the imported pipeline. 1. (Optional) Customize the **Pipeline Name** and **Pipeline Description**. 1. Select **Add Pipeline**. :::info To add a custom pipeline not listed in Seqera Pipelines to your Platform workspace, see [Add pipelines](./quickstart-demo/add-pipelines#) for manual Launchpad instructions. ::: ## Pipeline input data The [nf-core/rnaseq](https://github.com/nf-core/rnaseq) pipeline works with input datasets (samplesheets) containing sample names, FASTQ file locations (paths to FASTQ files in cloud or local storage), and strandedness. For example, the dataset used in the `test_full` profile is derived from the publicly available iGenomes collection of datasets, commonly used in bioinformatics analyses. This dataset represents RNA-Seq samples from various human cell lines (GM12878, K562, MCF7, and H1) with biological replicates, stored in an AWS S3 bucket (`s3://ngi-igenomes`) as part of the iGenomes resource. These RNA-Seq datasets consist of paired-end sequencing reads, which can be used to study gene expression patterns in different cell types.
**nf-core/rnaseq test_full profile dataset** | sample | fastq_1 | fastq_2 | strandedness | |--------|---------|---------|--------------| | GM12878_REP1 | s3://ngi-igenomes/test-data/rnaseq/SRX1603629_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX1603629_T1_2.fastq.gz | reverse | | GM12878_REP2 | s3://ngi-igenomes/test-data/rnaseq/SRX1603630_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX1603630_T1_2.fastq.gz | reverse | | K562_REP1 | s3://ngi-igenomes/test-data/rnaseq/SRX1603392_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX1603392_T1_2.fastq.gz | reverse | | K562_REP2 | s3://ngi-igenomes/test-data/rnaseq/SRX1603393_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX1603393_T1_2.fastq.gz | reverse | | MCF7_REP1 | s3://ngi-igenomes/test-data/rnaseq/SRX2370490_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX2370490_T1_2.fastq.gz | reverse | | MCF7_REP2 | s3://ngi-igenomes/test-data/rnaseq/SRX2370491_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX2370491_T1_2.fastq.gz | reverse | | H1_REP1 | s3://ngi-igenomes/test-data/rnaseq/SRX2370468_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX2370468_T1_2.fastq.gz | reverse | | H1_REP2 | s3://ngi-igenomes/test-data/rnaseq/SRX2370469_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX2370469_T1_2.fastq.gz | reverse |
In Platform, samplesheets and other data can be made easily accessible in one of two ways: - Use **Data Explorer** to browse and interact with remote data from AWS S3, Azure Blob Storage, and Google Cloud Storage repositories, directly in your organization workspace. - Use **Datasets** to upload structured data to your workspace in CSV (Comma-Separated Values) or TSV (Tab-Separated Values) format.
**Add a cloud bucket via Data Explorer** Private cloud storage buckets accessible with the credentials in your workspace are added to Data Explorer automatically by default. However, you can also add custom directory paths within buckets to your workspace to simplify direct access. To add individual buckets (or directory paths within buckets): ![Add public bucket](./quickstart-demo/assets/data-explorer-add-bucket.gif) 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - The cloud **Provider**. - An existing cloud **Bucket path**. - A unique **Name** for the bucket. - The **Credentials** used to access the bucket. For public cloud buckets, select **Public**. - An optional bucket **Description**. 1. Select **Add**. You can now select data directly from this bucket as input when launching your pipeline, without the need to interact with cloud consoles or CLI tools.
**Add a dataset** From the **Datasets** tab, select **Add Dataset**. ![Add a dataset](./quickstart-demo/assets/sp-cloud-add-a-dataset.gif) Specify the following dataset details: - A **Name** for the dataset, such as `nf-core-rnaseq-dataset`. - A **Description** for the dataset. - Select the **First row as header** option to prevent Platform from parsing the header row of the samplesheet as sample data. - Select **Upload file** and browse to your CSV or TSV samplesheet file in local storage, or simply drag and drop it into the box. The dataset is now listed in your organization workspace datasets and can be selected as input when launching your pipeline. :::info Platform does not store the data used for analysis in pipelines. The dataset must specify the locations of data stored on your own infrastructure. :::
## Launch pipeline :::note This guide is based on version 3.15.1 of the *nf-core/rnaseq* pipeline. Launch form parameters and tools may differ in other versions. ::: With your compute environment created, *nf-core/rnaseq* added to your workspace Launchpad, and your samplesheet accessible in Platform, you are ready to launch your pipeline. Navigate to the Launchpad and select **Launch** next to **nf-core-rnaseq** to open the launch form. The launch form consists of **General config**, **Run parameters**, and **Advanced options** sections to specify your run parameters before execution, and an execution summary. Use section headings or select the **Previous** and **Next** buttons at the bottom of the page to navigate between sections. ### General config - **Pipeline to launch**: The pipeline Git repository name or URL. For saved pipelines, this is prefilled and cannot be edited. - **Revision number**: A valid repository commit ID, tag, or branch name. For saved pipelines, this is prefilled and cannot be edited. - **Config profiles**: One or more [configuration profile](https://docs.seqera.io/nextflow/config#config-profiles) names to use for the execution. Config profiles must be defined in the `nextflow.config` file in the pipeline repository. - **Workflow run name**: An identifier for the run, pre-filled with a random name. This can be customized. - **Labels**: Assign new or existing [labels](../labels/overview) to the run. - **Compute environment**: Your AWS Batch compute environment. - **Work directory**: The cloud storage path where pipeline scratch data is stored. Platform will create a scratch sub-folder if only a cloud bucket location is specified. :::note The credentials associated with the compute environment must have access to the work directory. ::: ### Run parameters There are three ways to enter **Run parameters** prior to launch: - The **Input form view** displays form fields to enter text or select attributes from lists, and browse input and output locations with [Data Explorer](../data/data-explorer). - The **Config view** displays raw configuration text that you can edit directly. Select JSON or YAML format from the **View as** list. - **Upload params file** allows you to upload a JSON or YAML file with run parameters. Platform uses the `nextflow_schema.json` file in the root of the pipeline repository to dynamically create a form with the necessary pipeline parameters. Specify your pipeline input and output and modify other pipeline parameters as needed.
**input** Use **Browse** to select your pipeline input data: - In the **Data Explorer** tab, select the existing cloud bucket that contains your samplesheet, browse or search for the samplesheet file, and select the chain icon to copy the file path before closing the data selection window and pasting the file path in the input field. - In the **Datasets** tab, search for and select your existing dataset.
**outdir** Use the `outdir` parameter to specify where the pipeline outputs are published. `outdir` must be unique for each pipeline run. Otherwise, your results will be overwritten. **Browse** and copy cloud storage directory paths using Data Explorer, or enter a path manually.
Modify other parameters to customize the pipeline execution through the parameters form. For example, under **Read trimming options**, change the `trimmer` and select `fastp` instead of `trimgalore`. ![Read trimming options](./quickstart-demo/assets/trimmer-settings.png) ### Advanced settings - Use [resource labels](../resource-labels/overview) to tag the computing resources created during the workflow execution. While resource labels for the run are inherited from the compute environment and pipeline, workspace admins can override them from the launch form. Applied resource label names must be unique. - [Pipeline secrets](../secrets/overview) store keys and tokens used by workflow tasks to interact with external systems. Enter the names of any stored user or workspace secrets required for the workflow execution. - See [Advanced options](../launch/advanced) for more details. After you have filled the necessary launch details, select **Launch**. The **Runs** tab shows your new run in a **submitted** status at the top of the list. Select the run name to navigate to the [**View Workflow Run**](../monitoring/overview) page and view the configuration, parameters, status of individual tasks, and run report.
**Run monitoring** Select your new run from the **Runs** tab list to view the run details. #### Run details page As the pipeline runs, run details will populate with the following tabs: - **Command-line**: The Nextflow command invocation used to run the pipeline. This includes details about the pipeline version (`-r` flag) and profile, if specified (`-profile` flag). - **Parameters**: The exact set of parameters used in the execution. This is helpful for reproducing the results of a previous run. - **Resolved Nextflow configuration**: The full Nextflow configuration settings used for the run. This includes parameters, but also settings specific to task execution (such as memory, CPUs, and output directory). - **Execution Log**: A summarized Nextflow log providing information about the pipeline and the status of the run. - **Datasets**: Link to datasets, if any were used in the run. - **Reports**: View pipeline outputs directly in the Platform. ![View the nf-core/rnaseq run](./quickstart-demo/assets/sp-cloud-run-info.gif) #### View reports Most Nextflow pipelines generate reports or output files which are useful to inspect at the end of the pipeline execution. Reports can contain quality control (QC) metrics that are important to assess the integrity of the results. ![Reports tab](./quickstart-demo/assets/reports-tab.png) For example, for the *nf-core/rnaseq* pipeline, view the [MultiQC](https://docs.seqera.io/multiqc) report generated. MultiQC is a helpful reporting tool to generate aggregate statistics and summaries from bioinformatics tools. ![Reports MultiQC preview](./quickstart-demo/assets/reports-preview.png) The paths to report files point to a location in cloud storage (in the `outdir` directory specified during launch), but you can view the contents directly and download each file without navigating to the cloud or a remote filesystem. :::info See [Reports](../reports/overview) for more information. ::: #### View general information The run details page includes general information about who executed the run, when it was executed, the Git commit ID and/or tag used, and additional details about the compute environment and Nextflow version used. #### View details for a task Scroll down the page to view: - The progress of individual pipeline **Processes** - **Aggregated stats** for the run (total walltime, CPU hours) - **Workflow metrics** (CPU efficiency, memory efficiency) - A **Task details** table for every task in the workflow The task details table provides further information on every step in the pipeline, including task statuses and metrics. #### Task details Select a task in the task table to open the **Task details** dialog. The dialog has three tabs: - The **About** tab contains extensive task execution details. - The **Execution log** tab provides a real-time log of the selected task's execution. Task execution and other logs (such as stdout and stderr) are available for download from here, if still available in your compute environment. - The **Data Explorer** tab allows you to view the task working directory directly in Platform. Nextflow hash-addresses each task of the pipeline and creates unique directories based on these hashes. Data Explorer allows you to view the log files and output files generated for each task in its working directory, directly within Platform. You can view, download, and retrieve the link for these intermediate files in cloud storage from the **Data Explorer** tab to simplify troubleshooting.
## Interactive analysis with Studios **Studios** streamline the process of creating interactive analysis environments for Platform users. With built-in templates for platforms like Jupyter Notebook, an R-IDE, and VSCode, creating a Studio is as simple as adding and sharing pipelines or datasets. The Studio URL can also be shared with any user with the [Connect role](../orgs-and-teams/roles) for real-time access and collaboration. For the purposes of this guide, an R-IDE will be used to normalize the pipeline output data, perform differential expression analysis, and visualize the data with exploratory plots. ### Prepare your data #### Gene counts Salmon is the default tool used during the `pseudo-aligner` step of the *nf-core/rnaseq* pipeline. In the pipeline output data, the `/salmon` directory contains the tool's output, including a `salmon.merged.gene_counts_length_scaled.tsv` file. #### Sample info The analysis script provided in this section requires a sample information file to parse the counts data in the `salmon.merged.gene_counts_length_scaled.tsv` file. *nf-core/rnaseq* does not produce this sample information file automatically. See below to create a sample information file based on the genes in your `salmon.merged.gene_counts_length_scaled.tsv` file.
**Create a sample info file** 1. Note the names of the columns (excluding the first column, which typically contains gene IDs) in your `salmon.merged.gene_counts_length_scaled.tsv` file. These are your sample names. 1. Identify the group or condition that each sample belongs to. This information should come from your experimental design. 1. Create a new text file named `sampleinfo.txt`, with two columns: - First column header: Sample - Second column header: Group 1. For each sample in your `salmon.merged.gene_counts_length_scaled.tsv` file: - In the "Sample" column, write the exact sample name as it appears in the gene counts file. - In the "Group" column, write the corresponding group name. For example, for the dataset used in a `test_full` run of *nf-core/rnaseq*, the `sampleinfo.txt` looks like this: ``` Sample Group GM12878_REP1 GM12878 GM12878_REP2 GM12878 H1_REP1 H1 H1_REP2 H1 K562_REP1 K562 K562_REP2 K562 MCF7_REP1 MCF7 MCF7_REP2 MCF7 ``` To make your `sampleinfo.txt` file accessible to the data studio, upload it to the directory that contains your pipeline output data. Select this bucket or directory when you **Mount data** during data studio setup.
### Create an R-IDE analysis environment with Studios From the **Studios** tab, select **Add a studio** and complete the following: - Select the latest **R-IDE** container image template from the list. - Select your AWS Batch compute environment. :::note Studio sessions compete for computing resources when sharing compute environments. Ensure your compute environment has sufficient resources to run both your pipelines and sessions. The default CPU and memory allocation for a Studio is 2 CPUs and 8192 MB RAM. ::: - Mount data using Data Explorer: Mount the S3 bucket or directory path that contains the pipeline work directory of your RNA-Seq run. - Optional: Enter CPU and memory allocations. The default values are 2 CPUs and 8192 MB memory (RAM). - Select **Add**. - Once the Studio has been created, select the options menu next to it and select **Start**. - When the Studio is in a running state, **Connect** to it. ### Perform the analysis and explore results The R-IDE can be configured with the packages you wish to install and the R script you wish to run. For the purposes of this guide, run the following scripts in the R-IDE console to install the necessary packages and perform the analysis: 1. Install and load the necessary packages and libraries: ```r # Install required packages if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager") BiocManager::install(c("limma", "edgeR", "ggplot2", "gplots")) # Load required libraries library(limma) library(edgeR) library(ggplot2) library(gplots) ``` 1. Read and convert the count data and sample information: :::info Replace `` and `` with the paths to your `salmon.merged.gene_counts_length_scaled.tsv` and `sampleinfo.txt` files. ::: ```r # Read in the count data counts <- read.delim(file = "/workspace/data/", row.names = 1) # Remove the gene_name column if it exists if ("gene_name" %in% colnames(counts)) { counts <- counts[, -which(colnames(counts) == "gene_name")] } # Convert to matrix counts <- as.matrix(counts) # Read in the sample information targets <- read.table( file = "/workspace/data/", header = TRUE, stringsAsFactors = FALSE, sep = "", check.names = FALSE ) # Ensure column names are correct colnames(targets) <- c("Sample", "Group") ``` 1. Create a DGEList object and filter out low-count genes: ```r # Create a DGEList object y <- DGEList(counts, group = targets$Group) # Calculate CPM (counts per million) values mycpm <- cpm(y) # Filter low count genes thresh <- mycpm > 0.5 keep <- rowSums(thresh) >= 2 y <- y[keep, , keep.lib.sizes = FALSE] ``` 1. Normalize the data: ```r # Normalize the data y <- calcNormFactors(y) ``` 1. Print a summary of the filtered data: ```r # Print summary of filtered data print(dim(y)) print(y$samples) ``` 1. Create an MDS plot, displayed in the plots viewer (`a`) and saved as a PNG file (`b`): :::info MDS plots are used to visualize the overall similarity between RNA-Seq samples based on their gene expression profiles, helping to identify sample clusters and potential batch effects. ::: ```r # Create MDS plot # a. Display in RStudio plotMDS(y, col = as.numeric(factor(targets$Group)), labels = targets$Group) legend( "topright", legend = levels(factor(targets$Group)), col = 1:nlevels(factor(targets$Group)), pch = 20 ) # b. Save MDS plot to file (change `png` to `pdf` to create a PDF file) png("MDS_plot.png", width = 800, height = 600) plotMDS(y, col = as.numeric(factor(targets$Group)), labels = targets$Group) legend( "topright", legend = levels(factor(targets$Group)), col = 1:nlevels(factor(targets$Group)), pch = 20 ) dev.off() ``` 1. Perform differential expression analysis: ```r # Design matrix design <- model.matrix( ~ 0 + group, data = y$samples) colnames(design) <- levels(y$samples$group) # Estimate dispersion y <- estimateDisp(y, design) # Fit the model fit <- glmQLFit(y, design) # Define contrasts my.contrasts <- makeContrasts( GM12878vsH1 = GM12878 - H1, GM12878vsK562 = GM12878 - K562, GM12878vsMCF7 = GM12878 - MCF7, H1vsK562 = H1 - K562, H1vsMCF7 = H1 - MCF7, K562vsMCF7 = K562 - MCF7, levels = design ) # Perform differential expression analysis for each contrast results <- lapply(colnames(my.contrasts), function(contrast) { qlf <- glmQLFTest(fit, contrast = my.contrasts[, contrast]) topTags(qlf, n = Inf) }) names(results) <- colnames(my.contrasts) ``` :::info This script is written for the analysis of human data, based on *nf-core/rnaseq*'s `test_full` dataset. To adapt the script for your data, modify the contrasts based on the comparisons you want to make between your sample groups: ```r my.contrasts <- makeContrasts( Sample1vsSample2 = Sample1 - Sample2, Sample2vsSample3 = Sample2 - Sample3, ... levels = design ) ``` ::: 1. Print the number of differentially expressed genes for each comparison and save the results to CSV files: ```r # Print the number of differentially expressed genes for each comparison for (name in names(results)) { de_genes <- sum(results[[name]]$table$FDR < 0.05) print(paste("Number of DE genes in", name, ":", de_genes)) } # Save results for (name in names(results)) { write.csv(results[[name]], file = paste0("DE_genes_", name, ".csv")) } ``` 1. Create volcano plots for each differential expression comparison, displayed in the plots viewer and saved as PNG files: :::info Volcano plots in RNA-Seq analysis display the magnitude of gene expression changes (log2 fold change) against their statistical significance. This allows for quick identification of significantly up- and down-regulated genes between two conditions. ::: ```r # Create volcano plots for differential expression comparisons # Function to create a volcano plot create_volcano_plot <- function(res, title) { ggplot(res$table, aes(x = logFC, y = -log10(FDR))) + geom_point(aes(color = FDR < 0.05 & abs(logFC) > 1), size = 0.5) + scale_color_manual(values = c("black", "red")) + labs(title = title, x = "Log2 Fold Change", y = "-Log10 FDR") + theme_minimal() } # Create volcano plots for each comparison for (name in names(results)) { p <- create_volcano_plot(results[[name]], name) # Display in RStudio print(p) # Save to file (change `.png` to `.pdf` to create PDF files) ggsave( paste0("volcano_plot_", name, ".png"), p, width = 8, height = 6, dpi = 300 ) } ``` 1. Create a heatmap of the top 50 differentially expressed genes: :::info Heatmaps in RNA-Seq analysis provide a color-coded representation of gene expression levels across multiple samples or conditions, enabling the visualization of expression patterns and sample clustering based on similarity. ::: ```r # Create a heatmap of top 50 differentially expressed genes # Get top 50 DE genes from each comparison top_genes <- unique(unlist(lapply(results, function(x) rownames(x$table)[1:50]))) # Get log-CPM values for these genes log_cpm <- cpm(y, log = TRUE) top_gene_expr <- log_cpm[top_genes, ] # Print dimensions of top_gene_expr print(dim(top_gene_expr)) # Create a color palette my_palette <- colorRampPalette(c("blue", "white", "red"))(100) # Create a heatmap using heatmap.2 # Display in RStudio heatmap.2( as.matrix(top_gene_expr), scale = "row", col = my_palette, trace = "none", dendrogram = "column", margins = c(5, 10), labRow = FALSE, ColSideColors = rainbow(length(unique(y$samples$group)))[factor(y$samples$group)], main = "Top DE Genes Across Samples" ) # Save heatmap to file (change `png` to `pdf` to create a PDF file) png("heatmap_top_DE_genes.png", width = 1000, height = 1200) heatmap.2( as.matrix(top_gene_expr), scale = "row", col = my_palette, trace = "none", dendrogram = "column", margins = c(5, 10), labRow = FALSE, ColSideColors = rainbow(length(unique(y$samples$group)))[factor(y$samples$group)], main = "Top DE Genes Across Samples" ) dev.off() # Print the number of top genes in the heatmap print(paste("Number of top DE genes in heatmap:", length(top_genes))) ``` ![RStudio plots](./_images/rstudio.gif) ### Collaborate in the Studio To share your results or allow colleagues to perform exploratory analysis, share a link to the Studio by selecting the options menu for the Studio you want to share, then select **Copy Studio URL**. With this link, other authenticated users with the **Connect** [role](../orgs-and-teams/roles) (or greater) can access the session directly. ## RNA-Seq data and requirements RNA-Seq data typically consists of raw sequencing reads from high-throughput sequencing technologies. These reads are used to quantify gene expression levels and discover novel transcripts. A typical RNA-Seq dataset can range from a few GB to several hundred GB, depending on the number of samples and the sequencing depth. ### *nf-core/rnaseq* performance in Platform The compute recommendations in this guide are based on internal benchmarking performed by Seqera. Benchmark runs of [*nf-core/rnaseq*](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files (8 paired-end samples) and a total size of approximately 123.5 GB. This benchmark compares pipeline run metrics between single *nf-core/rnaseq* runs in an AWS Batch compute environment with Fusion file system and fast instance storage enabled (**Fusion** group) and an identical AWS Batch compute environment using S3 storage without Fusion (**AWS S3** group). ### Pipeline steps and computing resource requirements The *nf-core/rnaseq* pipeline involves several key steps, each with distinct computational requirements. Resource needs in this table are based on the `test_full` runs detailed previously: | **Pipeline step** | **Tools** | **Resource needs** | **Description** | |-------------------------------------|---------------------------|------------------------------|---------------------------------------------------------------------------------------------------| | **Quality Control (QC)** | FastQC, MultiQC | Low-moderate CPU (50-200% single-core usage), low memory (1-7 GB peak) | Initial quality checks of raw reads to assess sequencing quality and identify potential issues. | | **Read Trimming** | Trim Galore! | High CPU (up to 700% single-core usage), low memory (6 GB peak) | Removal of adapter sequences and low-quality bases to prepare reads for alignment. | | **Read Alignment** | HISAT2, STAR | Moderate-high CPU (480-600% single-core usage), high memory (36 GB peak) | Alignment of trimmed reads to a reference genome, typically the most resource-intensive step. | | **Pseudoalignment** | Salmon, Kallisto | Moderate-high CPU (420% single-core usage), moderate memory (18 GB peak) | A faster, more accurate method of gene expression quantification than alignment using read compatibility. | | **Quantification** | featureCounts, Salmon | Moderate-high CPU (500-600% single-core usage), moderate memory (18 GB peak) | Counting the number of reads mapped to each gene or transcript to measure expression levels. | | **Differential Expression Analysis**| DESeq2, edgeR | High CPU (650% single-core usage), low memory (up to 2 GB peak ) | Statistical analysis to identify genes with significant changes in expression between conditions. | #### Overall run metrics **Total pipeline run cost (USD)**: - Fusion file system with fast instance storage: $34.90 - Plain S3 storage without Fusion: $58.40 **Pipeline runtime**: The Fusion file system used with NVMe instance storage contributed to a 34% improvement in total pipeline runtime and a 49% reduction in CPU hours. ![Run metrics overview](./_images/cpu-table-2.png) #### Process run time The Fusion file system demonstrates significant performance improvements for most processes in the *nf-core/rnaseq* pipeline, particularly for I/O-intensive tasks: - The most time-consuming processes see improvements of 36.07% to 70.15%, saving hours of runtime in a full pipeline execution. - Most processes show significant performance improvements with Fusion, with time savings ranging from 35.57% to 99.14%. - The most substantial improvements are seen in I/O-intensive tasks like `SAMTOOLS_FLAGSTAT` (95.20% faster) and `SAMTOOLS_IDXSTATS` (99.14% faster). - `SALMON_INDEX` shows a notable 70.15% improvement, reducing runtime from 102.18 minutes to 30.50 minutes. - `STAR_ALIGN_IGENOMES`, one of the most time-consuming processes, is 53.82% faster with Fusion, saving nearly an hour of runtime. ![Average runtime of *nf-core/rnaseq* processes for eight samples using the Fusion file system and plain S3 storage. Error bars = standard deviation of the mean.](./_images/process-runtime-2.png) | Process | S3 Runtime (min) | Fusion Runtime (min) | Time Saved (min) | Improvement (%) | |---------|------------------|----------------------|------------------|-----------------| | SAMTOOLS_IDXSTATS | 18.54 | 0.16 | 18.38 | 99.14% | | SAMTOOLS_FLAGSTAT | 22.94 | 1.10 | 21.84 | 95.20% | | SAMTOOLS_STATS | 22.54 | 3.18 | 19.36 | 85.89% | | SALMON_INDEX | 102.18 | 30.50 | 71.68 | 70.15% | | BEDTOOLS_GENOMECOV_FW | 19.53 | 7.10 | 12.43 | 63.64% | | BEDTOOLS_GENOMECOV_REV | 18.88 | 7.35 | 11.53 | 61.07% | | PICARD_MARKDUPLICATES | 102.15 | 41.60 | 60.55 | 59.27% | | STRINGTIE | 17.63 | 7.60 | 10.03 | 56.89% | | RSEQC_READDISTRIBUTION | 16.33 | 7.19 | 9.14 | 55.97% | | STAR_ALIGN_IGENOMES | 106.42 | 49.15 | 57.27 | 53.82% | | SALMON_QUANT | 30.83 | 15.58 | 15.25 | 49.46% | | RSEQC_READDUPLICATION | 19.42 | 12.15 | 7.27 | 37.44% | | QUALIMAP_RNASEQ | 141.40 | 90.40 | 51.00 | 36.07% | | TRIMGALORE | 51.22 | 33.00 | 18.22 | 35.57% | | DUPRADAR | 49.04 | 77.81 | -28.77 | -58.67% |
**Pipeline optimization** Seqera Platform's task-level resource usage metrics allow you to determine the resources requested for a task and what was actually used. This information helps you fine-tune your configuration more accurately. However, manually adjusting resources for every task in your pipeline is impractical. Instead, you can leverage the pipeline optimization feature on the Launchpad. Pipeline optimization analyzes resource usage data from previous runs to optimize the resource allocation for future runs. After a successful run, optimization becomes available, indicated by the lightbulb icon next to the pipeline turning black. #### Optimize nf-core/rnaseq Select the lightbulb icon next to *nf-core/rnaseq* in your workspace Launchpad to view the optimized profile. You have the flexibility to tailor the optimization's target settings and incorporate a retry strategy as needed. #### View optimized configuration When you select the lightbulb, you can access an optimized configuration profile in the second tab of the **Customize optimization profile** window. This profile consists of Nextflow configuration settings for each process and each resource directive (where applicable): **cpus**, **memory**, and **time**. The optimized setting for a given process and resource directive is based on the maximum use of that resource across all tasks in that process. Once optimization is selected, subsequent runs of that pipeline will inherit the optimized configuration profile, indicated by the black lightbulb icon with a checkmark. :::info Optimization profiles are generated from one run at a time, defaulting to the most recent run, and _not_ an aggregation of previous runs. ::: ![Optimized configuration](./quickstart-demo/assets/optimize-configuration.gif) Verify the optimized configuration of a given run by inspecting the resource usage plots for that run and these fields in the run's task table: | Description | Key | | ------------ | ---------------------- | | CPU usage | `pcpu` | | Memory usage | `peakRss` | | Runtime | `start` and `complete` |
--- ## Studios for interactive analysis [Studios](../studios/overview) allows users to host a variety of container images directly in Seqera Platform compute environments for analysis using popular environments including [Jupyter](https://jupyter.org/) (Python) an [R-IDE](https://github.com/seqeralabs/r-ide), [Visual Studio Code](https://code.visualstudio.com/) IDEs, and [Xpra](https://xpra.org/index.html) remote desktops. Each Studio session provides a dedicated interactive environment that encapsulates the live environment. This guide explores how Studios integrates with your existing workflows, bridging the gap between pipeline execution and interactive analysis. It details how to set up and use each type of Studio, demonstrating a practical use case for each. :::info[**Prerequisites**] You will need the following to get started: - At least the **Maintain** workspace [user role](../orgs-and-teams/roles) to create and configure Studios. - An [AWS Batch compute environment](../compute-envs/aws-batch#automatic-configuration-of-batch-resources) (**without Fargate**) with sufficient resources (minimum: 2 CPUs, 8192 MB RAM). - Valid [credentials](../credentials/overview) for your cloud storage account and compute environment. - [Data Explorer](../data/data-explorer) enabled in your workspace. ::: :::note The scripts and instructions provided in this guide were tested on 24 February 2025. Library and package versions recommended here may become outdated and lead to unexpected results over time. ::: ## Jupyter: Python-based visualization of protein structure prediction data Jupyter notebooks enable interactive analysis using Python libraries and tools. For example, Py3DMol is a tool used for visualizing and comparing structures produced by workflows such as [*nf-core/proteinfold*](https://nf-co.re/proteinfold/1.1.1), a bioinformatics best-practice analysis pipeline for protein 3D structure prediction. This section demonstrates how to create an AWS Batch compute environment, add the nf-core AWS megatests public proteinfold data to your workspace, create a Jupyter Studio, and run the provided Python script to produce interactive composite 3D images of the [H1065 sequence](https://predictioncenter.org/casp14/multimer_results.cgi?target=H1065). :::note This script and instructions can also be used to visualize the structures from *nf-core/proteinfold* runs performed with your own public or private data. ::: #### Create an AWS Batch compute environment Studios require an AWS Batch compute environment. If you do not have an existing compute environment available, [create one](../compute-envs/aws-batch#automatic-configuration-of-batch-resources) with the following attributes: - **Region**: To minimize costs, your compute environment should be in the same region as your data. To browse the nf-core AWS megatests public data optimally, select **eu-west-1**. - **Provisioning model**: Use **On-demand** EC2 instances. - Studios does not support AWS Fargate. Do not enable **Use Fargate for head job**. - At least 2 available CPUs and 8192 MB of RAM. #### Add data using Data Explorer For the purposes of this guide, add the proteinfold results (H1065 sequence) from the nf-core AWS megatests S3 bucket to your workspace using Data Explorer: 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - **Provider**: AWS - **Bucket path**: `s3://nf-core-awsmegatests/proteinfold/results-9bea0dc4ebb26358142afbcab3d7efd962d3a820` - A unique **Name** for the bucket, such as `nf-core-awsmegatests-proteinfold-h1065` - **Credentials**: **Public** - An optional bucket **Description** 1. Select **Add**. :::info To use your own pipeline data for interactive visualization, add the cloud bucket that contains the results of your *nf-core/proteinfold* pipeline run. See [Add a cloud bucket](./quickstart-demo/add-data#add-a-cloud-bucket) for more information. ::: ### Create a Jupyter Studio From the **Studios** tab, select **Add a Studio** and complete the following: - In the **Compute & Data** tab: - Select your AWS Batch compute environment. :::note Studio sessions compete for computing resources when sharing compute environments. Ensure your shared compute environment has sufficient resources to run both your pipelines and Studio sessions. ::: - Optional: Enter CPU and memory allocations. The default values are 2 CPUs and 8192 MB memory (RAM). - Mount data using Data Explorer: Mount the S3 bucket or directory path that contains the nf-core AWS megatests proteinfold data, or the pipeline work directory of your *nf-core/proteinfold* run. - In the **General config** tab: - Select the latest **Jupyter** container image template from the list. - Optional: Enter a unique name and description for the Studio. - Check **Install Conda packages** and paste the following into the YAML textfield: ```yaml channels: - schrodinger - conda-forge - bioconda dependencies: - python=3.10 - conda-forge::libgl - pip - pip: - biopython==1.85 - mdtraj==1.10.3 - py3dmol==2.4.2 ``` - Select **Add** or choose to **Add and start** a Studio session immediately. - If you chose to **Add** the Studio in the preceding step, select **Connect** in the options menu to open a Studio session in a new browser tab. ### Visualize protein structures The following Python script visualizes and compares protein structures produced by Alphafold 2 and ESMFold, creating a composite interactive 3D image of the two structures with contrasting colors. The script aligns mobile structures to reference structures, retrieves lists of C-alpha atoms from both structures, creates views for individual and combined structures, and creates an interactive view of the individual and combined structures using Py3DMol. Run the following script in your Jupyter notebook to install the necessary packages and perform visualization:
Full Python script ```python from IPython.display import display from Bio import PDB from Bio.PDB import Superimposer # Keep file paths unchanged to visualize structures of the H1065 sequence in nf-core AWS megatests. # Update file paths (to PDB files) to visualize structures of your own nf-core/proteinfold output data. alphafold2_multimer_standard = "/workspace/data/nf-core-awsmegatests-proteinfold-h1065/mode_alphafold2_multimer/alphafold2/standard/H1065.alphafold.pdb" esmfold_multimer = "/workspace/data/nf-core-awsmegatests-proteinfold-h1065/mode_esmfold_multimer/esmfold/H1065.pdb" def align_structures(ref_pdb_path, mobile_pdb_path): """Align mobile structure to reference structure and return aligned coordinates""" # Set up parser parser = PDB.PDBParser() # Load structures ref_structure = parser.get_structure("reference", ref_pdb_path) mobile_structure = parser.get_structure("mobile", mobile_pdb_path) # Get lists of C-alpha atoms from both structures ref_atoms = [] mobile_atoms = [] for model in ref_structure: for chain in model: for residue in chain: if 'CA' in residue: ref_atoms.append(residue['CA']) for model in mobile_structure: for chain in model: for residue in chain: if 'CA' in residue: mobile_atoms.append(residue['CA']) # Align structures using Superimposer super_imposer = Superimposer() super_imposer.set_atoms(ref_atoms, mobile_atoms) super_imposer.apply(mobile_structure.get_atoms()) # Save aligned structure io = PDB.PDBIO() io.set_structure(mobile_structure) aligned_pdb_path = "./"+mobile_pdb_path.split("/")[-1].replace('.pdb', '_aligned.pdb') io.save(aligned_pdb_path) return aligned_pdb_path def create_structure_view(pdb_path, color, width=400, height=400, label=None): """Create a view for a single structure""" view = py3Dmol.view(width=width, height=height) with open(pdb_path, 'r') as f: pdb_data = f.read() view.addModel(pdb_data, "pdb") view.setStyle({'model': -1}, {'cartoon': {'color': color}}) view.zoomTo() if label: view.addLabel(label, { 'position': {'x': 0, 'y': 0, 'z': 0}, 'backgroundColor': color, 'fontColor': 'white' }) return view def visualize_structures(pdb1_path, pdb2_path): # Align the second structure to the first aligned_pdb2_path = align_structures(pdb1_path, pdb2_path) # Create three separate views view1 = create_structure_view(pdb1_path, 'blue', label="AlphaFold2") view2 = create_structure_view(aligned_pdb2_path, 'darkgrey', label="ESMFold") # Create combined view view3 = py3Dmol.view(width=800, height=400) # Load and display first structure (AlphaFold2) with open(pdb1_path, 'r') as f: pdb1_data = f.read() view3.addModel(pdb1_data, "pdb") view3.setStyle({'model': -1}, {'cartoon': {'color': 'blue'}}) # Load and display aligned second structure (ESMFold) with open(aligned_pdb2_path, 'r') as f: pdb2_data = f.read() view3.addModel(pdb2_data, "pdb") view3.setStyle({'model': 1}, {'cartoon': {'color': 'darkgrey'}}) # Set up the combined view view3.zoomTo() # Add labels for combined view view3.addLabel("AlphaFold2", {'position': {'x': -20, 'y': 0, 'z': 0}, 'backgroundColor': 'blue', 'fontColor': 'white'}) view3.addLabel("ESMFold", {'position': {'x': 20, 'y': 0, 'z': 0}, 'backgroundColor': 'darkgrey', 'fontColor': 'white'}) return view1, view2, view3 # Visualize the structures view1, view2, view3 = visualize_structures(alphafold2_multimer_standard, esmfold_multimer) # Display all views print("AlphaFold2 Structure:") view1.show() print("\nESMFold Structure:") view2.show() print("\nAligned Structures:") view3.show() ```
Python script individual steps 1. Import libraries: ```python from IPython.display import display from Bio import PDB from Bio.PDB import Superimposer ``` 1. Set up PDB file paths: ```python # Keep file paths unchanged to visualize structures of the H1065 sequence in nf-core AWS megatests. # Update file paths (to PDB files) to visualize structures of your own nf-core/proteinfold output data. alphafold2_multimer_standard = "/workspace/data/nf-core-awsmegatests-proteinfold-h1065/mode_alphafold2_multimer/alphafold2/standard/H1065.alphafold.pdb" esmfold_multimer = "/workspace/data/nf-core-awsmegatests-proteinfold-h1065/mode_esmfold_multimer/esmfold/H1065.pdb" ``` 1. Load structures from the PDB files and retrieve lists of C-alpha atoms from both structures: ```python def align_structures(ref_pdb_path, mobile_pdb_path): """Align mobile structure to reference structure and return aligned coordinates""" # Set up parser parser = PDB.PDBParser() # Load structures ref_structure = parser.get_structure("reference", ref_pdb_path) mobile_structure = parser.get_structure("mobile", mobile_pdb_path) # Get lists of C-alpha atoms from both structures ref_atoms = [] mobile_atoms = [] for model in ref_structure: for chain in model: for residue in chain: if 'CA' in residue: ref_atoms.append(residue['CA']) for model in mobile_structure: for chain in model: for residue in chain: if 'CA' in residue: mobile_atoms.append(residue['CA']) ``` 1. Align structures using Superimposer: ```python # Align structures using Superimposer super_imposer = Superimposer() super_imposer.set_atoms(ref_atoms, mobile_atoms) super_imposer.apply(mobile_structure.get_atoms()) # Save aligned structure io = PDB.PDBIO() io.set_structure(mobile_structure) aligned_pdb_path = "./"+mobile_pdb_path.split("/")[-1].replace('.pdb', '_aligned.pdb') io.save(aligned_pdb_path) return aligned_pdb_path ``` 1. Create a view for a single structure: ```python def create_structure_view(pdb_path, color, width=400, height=400, label=None): """Create a view for a single structure""" view = py3Dmol.view(width=width, height=height) with open(pdb_path, 'r') as f: pdb_data = f.read() view.addModel(pdb_data, "pdb") view.setStyle({'model': -1}, {'cartoon': {'color': color}}) view.zoomTo() if label: view.addLabel(label, { 'position': {'x': 0, 'y': 0, 'z': 0}, 'backgroundColor': color, 'fontColor': 'white' }) return view ``` 1. Create individual and combined structure views: ```python def visualize_structures(pdb1_path, pdb2_path): # Align the second structure to the first aligned_pdb2_path = align_structures(pdb1_path, pdb2_path) # Create three separate views view1 = create_structure_view(pdb1_path, 'blue', label="AlphaFold2") view2 = create_structure_view(aligned_pdb2_path, 'darkgrey', label="ESMFold") # Create combined view view3 = py3Dmol.view(width=800, height=400) # Load and display first structure (AlphaFold2) with open(pdb1_path, 'r') as f: pdb1_data = f.read() view3.addModel(pdb1_data, "pdb") view3.setStyle({'model': -1}, {'cartoon': {'color': 'blue'}}) # Load and display aligned second structure (ESMFold) with open(aligned_pdb2_path, 'r') as f: pdb2_data = f.read() view3.addModel(pdb2_data, "pdb") view3.setStyle({'model': 1}, {'cartoon': {'color': 'darkgrey'}}) # Set up the combined view view3.zoomTo() # Add labels for combined view view3.addLabel("AlphaFold2", {'position': {'x': -20, 'y': 0, 'z': 0}, 'backgroundColor': 'blue', 'fontColor': 'white'}) view3.addLabel("ESMFold", {'position': {'x': 20, 'y': 0, 'z': 0}, 'backgroundColor': 'darkgrey', 'fontColor': 'white'}) return view1, view2, view3 ``` 1. Display interactive 3D structure views: ```python # Visualize the structures view1, view2, view3 = visualize_structures(alphafold2_multimer_standard, esmfold_multimer) # Display all views print("AlphaFold2 Structure:") view1.show() print("\nESMFold Structure:") view2.show() print("\nAligned Structures:") view3.show() ```
![Visualize predicted protein structures in a Jupyter notebook Studio](./_images/protein-vis-short-gif-1080p-cropped.gif) #### Interactive collaboration To share a link to the running Studio session with collaborators inside your workspace, select the options menu for your Jupyter Studio session, then select **Copy Studio URL**. Using this link, other authenticated users can access the session directly to collaborate in real time. ## R-IDE: Analyze RNASeq data and differential expression statistics The R-IDE enables interactive analysis using R libraries and tools. For example, Shiny for R enables you to render functions in a reactive application and build a custom user interface to explore your data. The public data used in this section consists of RNA sequencing data that was processed by the *nf-core/rnaseq* pipeline to quantify gene expression, followed by *nf-core/differentialabundance* to derive differential expression statistics. This section demonstrates how to create a Studio to perform further analysis with these results from cloud storage. One of these outputs is a web application that can be deployed for interactive analysis. #### Create an AWS Batch compute environment Studios require an AWS Batch compute environment. If you do not have an existing compute environment available, [create one](../compute-envs/aws-batch#automatic-configuration-of-batch-resources) with the following attributes: - **Region**: To minimize costs, your compute environment should be in the same region as your data. To browse the nf-core AWS megatests public data optimally, select **eu-west-1**. - **Provisioning model**: Use **On-Demand** EC2 instances. - Studios does not support AWS Fargate. Do not enable **Use Fargate for head job**. - At least 2 available CPUs and 8192 MB of RAM. #### Add data using Data Explorer For the purposes of this guide, add the nf-core AWS megatests S3 bucket to your workspace using Data Explorer: 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - **Provider**: AWS - **Bucket path**: `s3://nf-core-awsmegatests` - A unique **Name** for the bucket, such as `nf-core-awsmegatests` - **Credentials**: **Public** - An optional bucket **Description** 1. Select **Add**. :::info To use your own pipeline data for interactive analysis, add the cloud bucket that contains the results of your *nf-core/differentialabundance* pipeline run. See [Add a cloud bucket](./quickstart-demo/add-data#add-a-cloud-bucket) for more information. ::: ### Create an R-IDE Studio From the **Studios** tab, select **Add a Studio** and complete the following: - In the **Compute & Data** tab: - Select your AWS Batch compute environment. :::note Studio sessions compete for computing resources when sharing compute environments. Ensure your compute environment has sufficient resources to run both your pipelines and Studio sessions. ::: - Optional: Enter CPU and memory allocations. The default values are 2 CPUs and 8192 MB memory (RAM). - Mount data using Data Explorer: Mount the nf-core AWS megatests S3 bucket, or the directory path that contains the results of your *nf-core/differentialabundance* pipeline run. - In the **General config** tab: - Select the latest **R-IDE** container image template from the list. - Optional: Enter a unique name and description for the Studio. - Select **Add** or choose to **Add and start** a Studio session immediately. - If you chose to **Add** the Studio in the preceding step, select **Start** in the options menu, then **Connect** to open a Studio session in a new browser tab when it is running. ### Configure environment and explore data in the web app The following R script installs and configures the prerequisite packages and libraries to deploy ShinyNGS, a web application created by members of the nf-core community to explore genomic data. The script also downloads the RDS file from nf-core AWS megatests to use as input data for the web app's various plots, heatmaps, and tables. To use your own *nf-core/rnaseq* and *nf-core/differentialabundance* results, modify the script as instructed in step 2 below:
R script individual steps 1. Configure the R-IDE with installed packages, including [ShinyNGS](https://github.com/pinin4fjords/shinyngs): ```r if (!require("BiocManager", quietly = TRUE)) install.packages("BiocManager") BiocManager::install(version = "3.20", ask = FALSE) BiocManager::install(c("SummarizedExperiment", "GSEABase", "limma")) install.packages(c("devtools", "matrixStats", "rmarkdown", "markdown")) install.packages("shiny", repos = "https://cran.rstudio.com/") devtools::install_version("cpp11", version = "0.2.1", repos = "http://cran.us.r-project.org") devtools::install_github('pinin4fjords/shinyngs', upgrade_dependencies = FALSE) ``` 1. Download the RDS file from nf-core AWS megatests or your own *nf-core/differentialabundance* results (see [Shiny app](https://nf-co.re/differentialabundance/1.5.0/docs/output/#shiny-app) from the nf-core documentation for file details): ```r # For nf-core AWS megatests download.file("https://nf-core-awsmegatests.s3-eu-west-1.amazonaws.com/differentialabundance/results-3dd360fed0dca1780db1bdf5dce85e5258fa2253/shinyngs_app/study/data.rds", 'data.rds') # For your nf-core/differentialabundance results, replace the URL with your RDS file URL) download.file("https://bucket.s3-region.amazonaws.com/differentialabundance/results/shinyngs_app/study-name/data.rds", 'data.rds') ``` 1. Import libraries, read your RDS data, and launch the app: ```r library(shinyngs) library(markdown) esel <- readRDS("data.rds") app <- prepareApp("rnaseq", esel) shiny::shinyApp(app$ui, app$server) ```
#### Interactive collaboration To share a link to the running session with collaborators inside your workspace, select the options menu for your R-IDE session, then select **Copy Studio URL**. Using this link, other authenticated users can access the session directly to collaborate in real time. ## Xpra: Visualize genetic variants with IGV Xpra provides remote desktop functionality that enables many interactive analysis and troubleshooting workflows. One such workflow is to perform genetic variant visualization using IGV desktop, a powerful open-source tool for the visual exploration of genomic data. This section demonstrates how to add public data from the [1000 Genomes project](https://www.coriell.org/1/NHGRI/Collections/1000-Genomes-Project-Collection/1000-Genomes-Project) to your workspace, set up an Xpra environment with IGV desktop pre-installed, and explore a variant of interest. #### Create an AWS Batch compute environment Studios require an AWS Batch compute environment. If you do not have an existing compute environment available, [create one](../compute-envs/aws-batch#automatic-configuration-of-batch-resources) with the following attributes: - **Region**: To minimize costs, your compute environment should be in the same region as your data. To browse the 1000 Genomes public data optimally, select **us-east-1**. - **Provisioning model**: Use **On-demand** EC2 instances. - Studios does not support AWS Fargate. Do not enable **Use Fargate for head job**. - At least 2 available CPUs and 8192 MB of RAM. #### Add data using Data Explorer Add the 1000 Genomes S3 bucket to your workspace using Data Explorer: 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - **Provider**: AWS - **Bucket path**: `s3://1000genomes` - A unique **Name** for the bucket, such as `1000G` - **Credentials**: **Public** - An optional bucket **Description** 1. Select **Add**. :::info To use your own data for interactive analysis, see [Add a cloud bucket](./quickstart-demo/add-data#add-a-cloud-bucket) for instructions to add your own public or private cloud bucket. ::: ### Create an Xpra Studio From the **Studios** tab, select **Add a Studio** and complete the following: - In the **Compute & Data** tab: - Select your AWS Batch compute environment. :::note Studio sessions compete for computing resources when sharing compute environments. Ensure your compute environment has sufficient resources to run both your pipelines and Studio sessions. ::: - Optional: Enter CPU and memory allocations. - Mount the 1000 Genomes S3 bucket you added previously using Data Explorer. - In the **General config** tab: - Select the latest **Xpra** container image template from the list. - Optional: Enter a unique name and description for the Studio. - Check **Install Conda packages** and paste the following into the YAML textfield: ```yaml channels: - conda-forge - bioconda dependencies: - igv - samtools ``` - Select **Add** or choose to **Add and start** a session immediately. - If you chose to **Add** the Studio in the preceding step, select **Connect** in the options menu to open a session in a new browser tab. ### View variants in IGV desktop 1. In the Xpra terminal, run `igv` to open IGV desktop. 1. In IGV, change the genome version to hg19. 1. Select **File**, then **Load from file**, then navigate to `/workspace/data/xpra-1000Genomes/phase3/data/HG00096/high_coverage_alignment` and select the `.bai` file, as shown below: ![Load BAM file in IGV desktop](./_images/xpra-data-studios-IGV-load-bam.png) 1. Search for PCSK9 and zoom into one of the exons of the gene. A coverage graph and reads should be shown, as below: ![BAM file view](./_images/xpra-data-studios-IGV-view-bam.png) #### Interactive collaboration To share a link to the running session with collaborators inside your workspace, select the options menu for your Xpra session, then select **Copy Studio URL**. Using this link, other authenticated users can access the session directly to collaborate in real time. ## VS Code: Create an interactive Nextflow development environment Using Studios and Visual Studio Code allows you to create a portable and interactive Nextflow development environment with all the tools you need to develop and run Nextflow pipelines. This section demonstrates how to set up a VS Code Studio with Conda and nf-core tools, add public data and run the *nf-core/fetchngs* pipeline with the `test` profile, and create a VS Code project to start coding your own Nextflow pipelines. The Studio includes the [Nextflow VS Code extension](https://marketplace.visualstudio.com/items?itemName=nextflow.nextflow), which makes use of the Nextflow language server to provide syntax highlighting, code navigation, code completion, and diagnostics for Nextflow scripts and configuration files. #### Create an AWS Batch compute environment Studios require an AWS Batch compute environment. If you do not have an existing compute environment available, [create one](../compute-envs/aws-batch#automatic-configuration-of-batch-resources) with the following attributes: - **Region**: To minimize costs, your compute environment should be in the same region as your data. To use the iGenomes public data bucket that contains the *nf-core/fetchngs* `test` profile data, select **eu-west-1**. - **Provisioning model**: Use **On-demand** EC2 instances. - Studios does not support AWS Fargate. Do not enable **Use Fargate for head job**. - At least 4 available CPUs and 16384 MB of RAM. #### Add data using Data Explorer The *nf-core/fetchngs* pipeline uses data from the NGI iGenomes public dataset for its `test` profile. To add this data to your workspace: 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - **Provider**: AWS - **Bucket path**: `s3://ngi-igenomes/test-data/` - A unique **Name** for the bucket, such as `ngi-igenomes-test-data` - **Credentials**: **Public** - An optional bucket **Description** 1. Select **Add**. ### Create a VS Code Studio From the **Studios** tab, select **Add a Studio** and complete the following: - In the **Compute & Data** tab: - Select your AWS Batch compute environment. :::note Studio sessions compete for computing resources when sharing compute environments. Shared compute environments must have sufficient resources to run both your pipelines and Studio sessions. ::: - Allocate at least 4 CPUs and 16384 MB RAM. - Mount data using Data Explorer: To run *nf-core/fetchngs* with the `test` profile, mount the NGI iGenomes S3 bucket you added previously. Mount any other data directories you need to run and code your own Nextflow pipelines. - In the **General config** tab: - Select the latest **VS Code** container image template from the list. - Optional: Enter a unique name and description for the Studio. - Check **Install Conda packages** and paste the following into the YAML textfield: ```yaml channels: - conda-forge - bioconda - anaconda dependencies: - nf-core - conda ``` - Select **Add** or choose to **Add and start** a Studio session immediately. - If you chose to **Add** the Studio in the preceding step, select **Connect** in the options menu to open a Studio session in a new browser tab. - Once inside the Studio session, run `code .` to use the clipboard. :::tip See [User and workspace settings](https://code.visualstudio.com/docs/editor/settings) if you wish to import existing VS Code configuration and preferences to your Studio session's VS Code environment. ::: ### Run *nf-core/fetchngs* with Conda Run the following Nextflow command to run *nf-core/fetchngs* with Conda: ```shell nextflow run nf-core/fetchngs -profile test,conda --outdir ./nf-core-fetchngs-conda-out -resume ``` ### Write a Nextflow pipeline with nf-core tools - Run `nf-core pipelines create` to create a new pipeline. Choose which parts of the nf-core template you want to use. - Run `code [NEW_PIPELINE]` to open the new pipeline as a project in VSCode. This allows you to code your pipeline with the help of the Nextflow language server and nf-core tools. ![VS Code Studio session](./_images/guide-vs-code-studio-nf-env-1080p-cropped.gif) #### Interactive collaboration To share a link to the running session with collaborators inside your workspace, select the options menu for your VS Code Studio session, then select **Copy Studio URL**. Using this link, other authenticated users can access the session directly to collaborate in real time. --- ## Set up your workspace Workspaces in Seqera Platform contain the resources to run your analyses and manage your computing infrastructure. Workspace members are granted various access roles to interact with the pipelines, compute environments, and data in a workspace. While each Platform user has a personal workspace, resource sharing and access management happens in an organization workspace context. To create an organization workspace and begin adding participants, first create your organization: ### Create an organization Organizations are the top-level structure and contain workspaces, members, and teams. You can also add external collaborators to an organization. See [Organization management](../orgs-and-teams/organizations) for more information. 1. Expand the **Organization | Workspace** drop-down and select **Add organization**. 1. Complete the organization details fields: - The **Name** to be associated with the organization in Platform. - The **Full name** of the organization. - A **Description** of the organization to provide contextual information that may be helpful to other organization members. - The organization's **Location**. - The organization's **Website URL**. - Drag and drop or upload an image to be used as the organization's **Logo** in Platform. 1. Select **Add**. You are the first **Owner** of the organizations that you create. Add other organization owners and members as needed from the organization's **Members** tab. ### Create a workspace 1. From the organization's **Workspaces** tab, select **Add Workspace**. 1. Complete the workspace details fields: - The **Name** to be displayed for the workspace in Platform. - The **Full name** of the workspace. - A **Description** of the workspace to provide contextual information that may be helpful to other workspace participants. - **Visibility**: Choose whether the workspace's pipelines must be **Shared** to all organization members, or only visible to workspace participants (**Private**). 1. Select **Add**. You are redirected to your organization's **Workspaces** tab with your new workspace listed. 1. Select your new workspace, then select the **Participants** tab to **Add Participants**. 1. Enter the names of existing organization members or teams and select **Add**. 1. Update a participant's access **Role** from the drop-down, if needed. ### Simplify workspace access with teams Teams simplify workspace role-based access control (RBAC) for groups of organization members. Per-workspace access roles assigned to teams are inherited by all team members. Create a new team, add team members, and add the team to workspaces from the **Teams** tab on your organization page: 1. Select **Add Team**, enter the team's details and an optional team avatar image, then select **Add**. 1. Select **Edit** next to the team name in the list, then select the **Members of team** tab to add new members by name or email. :::note Team members must be existing organization members. ::: 1. From the team edit screen's **Workspaces** tab, add workspaces by name and select an access **Role** from the drop-down next to each workspace in the list. All team members inherit the workspace access role for the team. --- ## Git integration Data pipelines are composed of many assets, including pipeline scripts, configuration files, dependency descriptors (such as for Conda or Docker), documentation, etc. When you manage complex data pipelines as Git repositories, all assets can be versioned and deployed with a specific tag, release, or commit ID. Version control and containerization are crucial to enable reproducible pipeline executions, and provide the ability to continuously test and validate pipelines as the code evolves over time. Seqera Platform has built-in support for [Git](https://git-scm.com) and several Git-hosting platforms. Pipelines can be pulled remotely from both public and private Git providers, including the most popular platforms: GitHub, GitLab, and BitBucket. ## Public repositories Launch a public Nextflow pipeline by entering its Git repository URL in the **Pipeline to launch** field. When you specify the **Revision number**, the list of available revisions are automatically pulled using the Git provider's API. By default, the default branch (usually `main` or `master`) will be used. :::tip [nf-core](https://nf-co.re/pipelines) is a great resource for public Nextflow pipelines. ::: :::note The GitHub API imposes [rate limits](https://docs.github.com/en/developers/apps/building-github-apps/rate-limits-for-github-apps) on API requests. You can increase your rate limit by adding [GitHub credentials](#github) to your workspace as shown below. ::: ## Private repositories To access private Nextflow pipelines, add the credentials for your private Git hosting provider to Seqera. :::note Credentials are encrypted with the AES-256 cypher before secure storage and are never exposed in an unencrypted way by any Seqera API. ::: ### Multiple credential filtering When you have multiple stored credentials, Seqera selects the most relevant credential for your repository in the following order: 1. Seqera evaluates all the stored credentials available to the current workspace. 2. Credentials are filtered by Git provider (GitHub, GitLab, Bitbucket, etc.) 3. Seqera selects the credential with a **Repository base URL** most similar to the target repository. 4. If no **Repository base URL** values are specified in the workspace credentials, the most long-lived credential is selected. **Credential filtering example** Workspace A contains four credentials: _Credential A_ Type: GitHub Repository base URL: _Credential B_ Type: GitHub Repository base URL: https://github.com/ _Credential C_ Type: GitHub Repository base URL: https://github.com/pipeline-repo _Credential D_ Type: GitLab Repository base URL: https://gitlab.com/repo-a If you launch a pipeline with a Nextflow workflow in the https://github.com/pipeline-repo, Seqera will use **Credential C**. For the application to select the most appropriate credential for your repository, we recommend that you: - Specify the **Repository base URL** values as completely as possible for each Git credential used in the workspace. - Favor the use of service account type credentials where possible (such as GitLab group access tokens). - Avoid storing multiple user-based tokens with similar permissions. ### Azure DevOps repositories You can authenticate to Azure Devops repositories using a [personal access token (PAT)](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows#about-pats). Once you have created and copied your access token, create a new credential in Seqera using these steps: **Create AzureDevOps credentials** 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 3. Enter a **Name** for the new credentials. 4. Select _Azure DevOps_ as the **Provider**. 5. Enter your **Username** and **Access token**. 6. (Recommended) Enter the **Repository base URL** for which the credentials should be applied. This option is used to apply the provided credentials to a specific repository, e.g., `https://dev.azure.com//`. ### GitHub Use an access token to connect Seqera to a private [GitHub](https://github.com/) repository. Personal (classic) or fine-grained access tokens can be used. :::note A user's personal access token (classic) can access every repository that the user has access to. GitHub recommends using fine-grained personal access tokens (currently in beta) instead, which you can restrict to specific repositories. Fine-grained personal access tokens also enable you to specify granular permissions instead of broad scopes. ::: For **personal (classic)** tokens, you must grant access to the private repository by selecting the main `repo` scope when the token is created. See [Creating a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic) for instructions to create your personal access token (classic). For **fine-grained** tokens, the repository's organization must [opt in](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) to the use of fine-grained tokens. Tokens can be restricted by _resource owner (organization)_, _repository access_, and _permissions_. See [Creating a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) for instructions to create your fine-grained access token. After you've created and copied your access token, create a new credential in Seqera: **Create GitHub credentials** 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 2. Enter a **Name** for the new credentials. 3. Select _GitHub_ as the **Provider**. 4. Enter your **Username** and **Access token**. 5. (Recommended) Enter the **Repository base URL** for which the credentials should be applied. This option is used to apply the provided credentials to a specific repository, e.g., `https://github.com/seqeralabs`. ### GitHub App As an alternative to personal access tokens, you can authenticate Seqera Platform to GitHub using a [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps). GitHub Apps are the GitHub-recommended way to integrate with the GitHub API: they act on their own behalf rather than impersonating a user, support fine-grained permissions scoped to specific repositories, and use short-lived installation tokens that are not tied to a single account. When you select _GitHub_ as the **Provider**, the credentials form shows a **GitHub credential type** selector with two tabs: - **Access token** — Authenticate using a personal access token (PAT) for API access. This is the legacy flow described in the [GitHub](#github) section above. - **GitHub App** — Set up app-based authentication with dedicated credentials. When you select this tab, a second selector lets you choose between two flows: - **Create and add** — Use the GitHub App manifest flow to create a new app on GitHub directly from Seqera. Seqera generates a pre-filled manifest, redirects you to GitHub for approval, then automatically retrieves and stores the resulting App ID, private key, client secret, and webhook secret. - **Add preexisting** — Register an app you have already created on GitHub by entering its App ID, installation ID, private key, and other security keys manually. The manifest flow (**Create and add**) is recommended for new integrations: it eliminates the manual copy-paste of multiple secrets, ensures the app is created with the minimum required permissions (`contents: read`, `metadata: read`), and avoids configuration errors. Use **Add preexisting** only when the app already exists or when you must create the app outside of Seqera. ![GitHub App credentials form showing the Access token / GitHub App tabs and the Create and add / Add preexisting sub-selector](./_images/credentials-github-app-form.png) **Create a new GitHub App from Seqera** To create and install a GitHub App from Seqera using the manifest flow: 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 2. Enter a **Name** for the new credentials, e.g., `my-github-app`. Underscores in the credential name are replaced with spaces in the resulting GitHub App name (`Seqera Platform - my github app`). 3. Select _GitHub_ as the **Provider**, set the **GitHub credential type** to **GitHub App**, then select **Create and add**. 4. Enter the **GitHub URL**: - For GitHub.com, leave the default value (`https://github.com`). - For a GitHub Enterprise Server instance, enter the base URL of your instance (for example, `https://github.example.com`). HTTPS is required, and private or loopback addresses are rejected. 5. (Optional) Enter the **GitHub repository URL** to scope access to a single repository, e.g., `https://github.com/seqeralabs/nf-tower`. Leave this field empty to create credentials that are not bound to a specific repository. 6. Select the **App scope**: - **Organization** — App owned by an organization (requires admin access). Enter the **GitHub organization name** (case-sensitive). You must be an **owner** of the target organization to create an app on its behalf. - **Personal** — App owned by your personal GitHub account. The **GitHub organization name** field is hidden. 7. Select **Create app on GitHub**. Seqera redirects you to GitHub: - For personal scope: `https://github.com/settings/apps/new` - For organization scope: `https://github.com/organizations//settings/apps/new` - For GitHub Enterprise Server, the equivalent path on your instance. The manifest is pre-filled with the app name, callback URL, webhook URL, and the required permissions (`contents: read`, `metadata: read`). ![GitHub "Create GitHub App" page with the manifest pre-filled, showing the app name "Seqera Platform - new github app"](./_images/credentials-github-mainfest-page.png) 8. On GitHub, review the requested permissions and select **Create GitHub App**. GitHub redirects you back to Seqera, which exchanges the temporary code for the app credentials and stores them in your workspace or personal credentials. 9. After the redirect, install the app on the repositories you want Seqera to access: - Open the new app on GitHub: **Settings > Developer settings > GitHub Apps > [your app] > Install App**. - For an organization-owned app, select the organization. For a personal app, select your user account. - Choose **Only select repositories** and add the specific repositories Seqera should access, or **All repositories** to grant access to all current and future repositories. - Select **Install** to complete installation. ![GitHub App installation page showing "Only select repositories" with one or more repositories selected](./_images/credentials-github-install-app.png) The new credential appears in the **Credentials** list with the GitHub App icon. Credentials created from a workspace credentials page are scoped to that workspace; credentials created from your personal credentials page are scoped to your user and are not visible to any workspace. :::note If you cancel the manifest flow on GitHub or close the browser tab before approving the app, no credential is created on the Seqera side. The temporary state that protects the redirect against CSRF expires after 10 minutes and cannot be reused — restart the flow from the credentials form. ::: **Add an existing GitHub App** If you have already created and installed a GitHub App, register it in Seqera by setting the **GitHub credential type** to **GitHub App** and selecting **Add preexisting**, then entering the app's security keys (App ID, installation ID, app slug, private key, client secret, and webhook secret) along with the same **GitHub URL**, **App scope**, and optional **GitHub repository URL** fields described above. You can find these values under **Settings > Developer settings > GitHub Apps > [your app]** on GitHub. **Handling duplicate credentials** Seqera enforces uniqueness of GitHub App credentials by **Repository URL** within the same workspace or user context. If you attempt to create a credential — through either the manifest flow or the existing-app flow — for a repository URL that already has a GitHub App credential, the operation fails with a duplicate error and no new credential is stored. To resolve a duplicate: - **Reuse the existing credential** — In most cases the existing credential already grants Seqera the access it needs. Open it from the **Credentials** list to confirm the installed app and repository association. - **Delete the obsolete credential first** — If the existing credential is stale (for example, the app has been uninstalled or the private key was rotated outside of Seqera), delete it from the **Credentials** list and then re-run the creation flow. - **Use a different repository URL or leave the field empty** — If you need a second credential covering a broader scope, omit the **Repository URL** or use a different one. Seqera's credential filtering then selects the most specific match at launch time. ### GitLab GitLab supports [Personal](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), [Group](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html#group-access-tokens), and [Project](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) access tokens for authentication. Your access token must have the `api`, `read_api`, and `read_repository` scopes to work with Seqera. For all three token types, use the token value in both the **Password** and **Access token** fields in the Seqera credential creation form. After you have created and copied your access token, create a new credential in Seqera with these steps: **Create GitLab credentials** 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 2. Enter a **Name** for the new credentials. 3. Select _GitLab_ as the **Provider**. 4. Enter your **Username**. For Group and Project access tokens, the username can be any non-empty value. 5. Enter your token value in both the **Password** and **Access token** fields. 6. Enter the **Repository base URL** (recommended). This option is used to apply the credentials to a specific repository, e.g. `https://gitlab.com/seqeralabs`. ### Gitea To connect to a private [Gitea](https://gitea.io/) repository, use your Gitea user credentials to create a new credential in Seqera with these steps: **Create Gitea credentials** 1. From an organization workspace, go to the **Credentials** tab and select **Add Credentials**. From your personal workspace, select **Your credentials** from the user menu, then select **Add credentials**. 2. Enter a **Name** for the new credentials. 3. Select _Gitea_ as the **Provider**. 4. Enter your **Username**. 5. Enter your **Password**. 6. Enter your **Repository base URL** (required). ### Bitbucket To connect to a private BitBucket repository, see the [BitBucket documentation](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) to learn how to create a BitBucket App password. Then, create a new credential in Seqera with these steps: **Create BitBucket credentials** 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 2. Enter a **Name** for the new credentials. 3. Select _BitBucket_ as the **Provider**. 4. Enter your **Username** and **Password**. 5. Enter the **Repository base URL** (recommended). This option can be used to apply the credentials to a specific repository, e.g., `https://bitbucket.org/seqeralabs`. ### AWS CodeCommit To connect to a private AWS CodeCommit repository, see the [AWS documentation](https://docs.aws.amazon.com/codecommit/latest/userguide/auth-and-access-control-iam-identity-based-access-control.html) to learn more about IAM permissions for CodeCommit. Then, use your IAM account access key and secret key to create a credential in Seqera with these steps: **Create AWS CodeCommit credentials** 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 2. Enter a **Name** for the new credentials. 3. Select _CodeCommit_ as the **Provider**. 4. Enter the **Access key** and **Secret key** of the AWS IAM account that will be used to access the target CodeCommit repository. 5. Enter the **Repository base URL** for which the credentials should be applied (recommended). This option can be used to apply the credentials to a specific region, e.g., `https://git-codecommit.eu-west-1.amazonaws.com`. ### Self-hosted Git Seqera Platform Enterprise supports Git server endpoints. For more information, see [Git configuration](../enterprise/configuration/overview#git-integration). --- ## Labels Labels are workspace-specific free-text annotations that can be applied to pipelines, actions, or workflow runs, either during or after creation. Use labels to organize your work and filter key information. Labels aren't propagated to Nextflow during workflow execution. ### Limits :::caution Label names must contain a minimum of 2 and a maximum of 39 alphanumeric characters, separated by dashes or underscores, and must be unique in each workspace. ::: - Label names cannot begin or end with dashes `-` or underscores `_`. - Label names cannot contain a consecutive combination of `-` or `_` characters (`--`, `__`, `-_`, etc.) - A maximum of 25 labels can be applied to each resource. - A maximum of 1000 labels can be used in each workspace. ### Create and apply labels Labels can be created, applied, and edited by a workspace owner, admin, or maintainer. When applying a label, users can select from existing labels or add new ones on the fly. ### Labels applied to a pipeline :::caution Labels are applied to elements in a workspace-specific context. This means that labels applied to a shared pipeline in `workspace A` will not be shown when viewing the pipeline from `workspace B`. ::: The labels applied to each pipeline are displayed in both list and card views on the **Launchpad**. Select a pipeline to view all applied labels. Apply a label when adding a new pipeline or editing an existing pipeline. If a label is applied to a pipeline, all workflow runs of that pipeline will inherit the label. If the labels applied to the pipeline are changed, this change will only be applied to future runs, not past runs. ### Labels applied to an action Apply a label when adding a new action or editing an existing action. Labels applied to an action are displayed in the action card on the **Actions** screen. Hover over labels with **+** to see all labels. If a label is applied to an action, all workflow runs triggered by this action inherit the label. If the labels applied to the action are changed, this change will only be applied to future runs, not past runs. ### Labels applied to a workflow run Labels applied to a workflow run are displayed on the **Runs** list screen and on the workflow run detail screen. Hover over labels with **+** to see all labels. Apply a label to a workflow run during launch, on the workflow runs list screen, or on the run detail screen. ### Search and filter with labels You can search and filter pipelines and workflow runs using one or more labels — filter and search are complementary. ### Overview of labels in a workspace All labels used in a workspace can be viewed, added, edited, and deleted by a workspace owner, admin, or maintainer in the workspace **Settings** tab. If a label is edited or deleted on this screen, the change is propagated to all items where the label was used. :::caution You cannot undo editing or deleting a label. ::: --- ## Advanced options You can modify the configuration and execution of a pipeline with advanced launch options. ## Nextflow config file Add additional or modified Nextflow configuration settings. Use the same syntax as the [Nextflow configuration file](https://docs.seqera.io/nextflow/config#config-syntax). ### Nextflow configuration order of priority When launching pipelines in Platform, Nextflow configuration is resolved from four sources. If the same parameter is defined in more than one source, the highest-priority source is used: | Priority | Nextflow configuration | Source | |----------|----------------------------------------------------------|----------------------------------------------------------------------------------------------------| | Highest | The pipeline launch form **Nextflow config file** field | User-defined at launch | | | Platform-managed compute settings | Derived from CE definition (see [Platform-managed configuration](#platform-managed-configuration)) | | | The compute environment **Global Nextflow config** field | User-defined during CE creation | | Lowest | The pipeline repository `nextflow.config` file | Pipeline Git repository | :::note **Global Nextflow config** values are pre-filled in the launch form's **Nextflow config file** field, but also apply independently at the priority level shown above. Clearing the launch form field does not remove the **Global Nextflow config** values. ::: For example, if: 1. The pipeline repository `nextflow.config` file contains this manifest: ```ini title="Pipeline repository nextflow.config" manifest { name = 'A' description = 'Pipeline description A' } ``` 2. Your compute environment **Global Nextflow config** field contains this manifest: ```ini title="Compute environment Global Nextflow config field" manifest { name = 'B' description = 'Pipeline description B' } ``` 3. You specify this manifest in the **Nextflow config file** field on the pipeline launch form: ```ini title="Pipeline launch form Nextflow config file field" manifest { name = 'C' description = 'Pipeline description C' } ``` The resolved configuration will contain the **Nextflow config file** field's manifest: ```ini title="Resolved configuration" manifest { name = 'C' description = 'Pipeline description C' } ``` ### Platform-managed configuration Platform generates a configuration file from the compute environment definition. For any property defined in both this file and the pipeline repository `nextflow.config`, the Platform-generated value takes precedence. There is no warning repository config values are replaced. ### Pre-launch configuration preview The configuration preview shown on the launch form reflects the **Nextflow config file** field and the compute environment's **Global Nextflow config** field only. Platform-managed compute settings and the pipeline repository `nextflow.config` are not visible in the preview. Both are resolved at launch time. :::tip{title="Best practices"} To ensure compute-specific settings are applied consistently: - Define compute-specific settings in the compute environment's **Global Nextflow config** field or the launch form's **Nextflow config file** field to make settings visible in the pre-launch preview and ensure they apply regardless of what the repository config contains. - Use the launch form's **Nextflow config file** field for settings that must take precedence over everything else. ::: ## Seqera Cloud config file Configure per-pipeline Seqera reporting behavior. Settings specified here override the same settings in the `tower.yml` [configuration file](../enterprise/configuration/overview) for this execution. Use the `reports` key to specify report paths, titles, and MIME types: ```yml reports: reports/multiqc/index.html: display: "MultiQC Reports" mimeType: "text/html" ``` ## Pre and post-run scripts Run custom code either before or after the execution of the Nextflow script. These fields allow you to enter shell commands. Pre-run scripts are executed in the nf-launch script prior to invoking Nextflow processes. Pre-run scripts are useful for: - Executor setup, such as loading a private CA certificate. - Troubleshooting. For example, add `sleep 3600` to your pre-run script to instruct Nextflow to wait 3600 seconds (60 minutes) before process execution after the nf-launcher container is started, to create a window in which to test connectivity and other issues before your Nextflow processes execute. Post-run scripts are executed after all Nextflow processes have completed. The scripts have access to the following environment variables: | Environment variable | Description | |----------------------|----------------------------------------------| | `TOWER_WORKFLOW_ID` | The unique workflow run identifier | | `TOWER_WORKSPACE_ID` | The workspace identifier | | `NXF_UUID` | The Nextflow session ID | | `NXF_OUT_FILE` | Path to the Nextflow console output file | | `NXF_LOG_FILE` | Path to the Nextflow log file | | `NXF_TML_FILE` | Path to the timeline report HTML file | | `NXF_EXIT_STATUS` | The exit code of the workflow execution | | `TOWER_ACCESS_TOKEN` | Platform API access token for authentication | | `TOWER_REFRESH_TOKEN`| Platform API refresh token | | `NXF_WORK` | The work directory path used by the workflow | | `TOWER_CONFIG_FILE` | Path to the Tower configuration file | Post-run scripts are also useful for triggering a third party service via API request. :::note Post-run script failures do not affect the workflow exit status. Post-run scripts have a maximum size limit of 1 KB. ::: ## Pull latest Instruct Nextflow to pull the latest pipeline version from the pipeline repository. This is equivalent to using the `-latest` flag. ## Stub run Replace Nextflow process commands with command [stubs](https://docs.seqera.io/nextflow/process#stub), where defined, before execution. ## Nextflow version Select the Nextflow version for the run. The selector lists the versions available in your installation and maps your choice to the launch container image that runs the workflow. The default version is: - **Pipeline advanced options**: the system default version, or the compute environment type's minimum version when that minimum is higher. - **Launch advanced options**: the version saved on the pipeline, when it is compatible with the selected compute environment. If the pipeline's saved version is below the minimum required by the compute environment, no version is preselected and you must choose a compatible version before launching. Version availability depends on the compute environment: - **Cloud and Kubernetes** compute environments (AWS Batch, Azure Batch, Google Batch, Kubernetes) support version selection. You cannot select versions below the compute environment's minimum. Platform rejects any launch submitted with a lower or unknown version through any channel (UI, API, or CLI) before execution. - **Grid/HPC** compute environments (Slurm, LSF, Grid Engine, Altair PBS Pro, Moab) run a pre-installed Nextflow and have no launch container. The version selector does not appear for them, and a version carried over from a pipeline default has no effect when you launch on a grid environment. Changing only the Nextflow version registers a new pipeline version, because the version determines the runtime that runs the workflow. :::note Use the **Nextflow version** selector instead of setting `NXF_VER` in a pre-run script or the pipeline configuration. If `NXF_VER` is set in the pipeline configuration, it overrides the version selected here. ::: :::caution When your installation pins a custom launch container with [`TOWER_LAUNCH_CONTAINER`](../enterprise/advanced-topics/custom-launch-container), that image determines the Nextflow runtime for every run. The version selector is hidden on all compute environments and any selected version has no effect. ::: ## Enable Nextflow syntax parser v2 Use the v2 Nextflow language parser. Requires Nextflow 25.02.0-edge or later. Older runtimes ignore this setting. The v2 parser implements Nextflow's [strict syntax](https://nextflow.io/docs/latest/strict-syntax.html). Platform selects it by exporting `NXF_SYNTAX_PARSER` to the launch environment: - **Off (default)**: Workflows run with the v1 parser. Platform exports `NXF_SYNTAX_PARSER=v1`. - **On**: Workflows run with the v2 parser. Platform exports `NXF_SYNTAX_PARSER=v2`. The toggle only selects the parser. It does not change the Nextflow runtime version, the pipeline source, or any pipeline parameters. The v2 parser becomes the default in Nextflow 26.04: - **Before Nextflow 26.04**: v1 is the runtime default. Turn the toggle on to opt in to v2. - **From Nextflow 26.04**: v2 is the runtime default. Turn the toggle off to pin a pipeline to v1. A [pre-run script](#pre-and-post-run-scripts) that exports `NXF_SYNTAX_PARSER` overrides this toggle. :::note The launch form inherits this setting from the pipeline. You can override it per launch without changing the stored value. Changing the toggle on the pipeline edit form creates a new pipeline version. ::: ## Main script Nextflow will attempt to run the script named `main.nf` in the root of the project repository by default. You can configure a custom script path and/or filename in `manifest.mainScript`, or you can provide the script path and filename in this field. In a pipeline repository set up with subdirectories containing multiple main script files, enter the path name to your desired custom script in **Main script**. For example: `/custom-pipeline/custom-script.nf` If you point to a custom script using this field, Platform also looks for a `nextflow.config` in the same directory as the custom script, and if none exists, it defaults to the `nextflow.config` in the repository root. :::note If you specify a custom script filename, the root of the default branch in your pipeline repository must still contain a `main.nf` file, even if blank. See [Nextflow configuration](../troubleshooting_and_faqs/nextflow) for more information on this known Nextflow behavior. ::: ## Workflow entry name Nextflow DSL2 provides the ability to launch workflows with specific names. Enter the name of the workflow to be executed in this field. ## Schema name Specify the name of a pipeline schema file in the workflow repository root folder to override the default `nextflow_schema.json`. ## Head job CPUs and memory Specify the compute resources allocated to the Nextflow head job. These fields are only displayed for runs executing on [AWS Batch](../compute-envs/aws-batch) and [Azure Batch](../compute-envs/azure-batch) compute environments. --- ## Nextflow cache and resume Nextflow maintains a [cache](https://docs.seqera.io/nextflow/cache-and-resume) directory where it stores the intermediate results and metadata from workflow runs. Workflows executed in Seqera Platform use this caching mechanism to enable users to relaunch or resume failed or otherwise interrupted runs as needed. This eliminates the need to re-execute successfully completed tasks when a workflow is executed again due to task failures or other interruptions. ## Cache directory Nextflow stores all task executions to the task cache automatically, whether or not the resume or relaunch option is used. This makes it possible to resume or relaunch runs later if needed. Platform HPC and local compute environments use the default Nextflow cache directory (`.nextflow/cache`) to store the task cache. Cloud compute environments use the [cloud cache](https://docs.seqera.io/nextflow/cache-and-resume#cache-stores) mechanism to store the task cache in a sub-folder of the pipeline work directory. To override the default cloud cache location in cloud compute environments, specify an alternate directory with the [cache](https://docs.seqera.io/nextflow/process#process-cache) directive in your Nextflow configuration file (either in the **Advanced options > Nextflow config file** field on the launch form, or in the `nextflow.config` file in your pipeline repository). To customize the cache location used in your AWS Batch and Amazon EKS compute environments, specify an alternate cache directory in your Nextflow configuration: ```groovy cloudcache { enabled = true path = 's3://your-bucket/.cache' } ``` The new cache directory must be accessible with the credentials associated with your compute environment. An alternate cloud storage location can be specified if you include the necessary credentials for that location in your Nextflow configuration. **This is not recommended for production environments**. To customize the cache location used in your Azure Batch compute environments, specify an alternate cache directory in your Nextflow configuration: ```groovy cloudcache { enabled = true path = 'az://your-container/.cache' } ``` The new cache directory must be accessible with the credentials associated with your compute environment. An alternate cloud storage location can be specified if you include the necessary credentials for that location in your Nextflow configuration. **This is not recommended for production environments**. To customize the cache location used in your Google Cloud Batch and Google Kubernetes Engine compute environments, specify an alternate cache directory in your Nextflow configuration: ```groovy cloudcache { enabled = true path = 'gs://your-bucket/.cache' } ``` The new cache directory must be accessible with the credentials associated with your compute environment. An alternate cloud storage location can be specified if you include the necessary credentials for that location in your Nextflow configuration. **This is not recommended for production environments**. Kubernetes compute environments do not use cloud cache by default. To specify a cloud storage cache directory, include the cloud cache path and necessary credentials for that location in your Nextflow configuration. **This is not recommended for production environments**.
AWS S3 ```groovy // Specify cloud storage credentials aws { accessKey = '' secretKey = '' region = '' } // Set the cloud cache path cloudcache { enabled = true path = 's3://your-bucket/.cache' } ```
Azure Blob Storage ```groovy // Specify cloud storage credentials azure { storage { accountName = '' accountKey = '' } } // Set the cloud cache path cloudcache { enabled = true path = 'az://your-container/.cache' } ```
Google Cloud Storage 1. See [these instructions](../compute-envs/google-cloud-batch#iam) to set up IAM and create a JSON key file for the custom service account with permissions to your Google Cloud storage account. 2. If you run the [gcloud CLI authentication flow](https://docs.seqera.io/nextflow/google#credentials) with `gcloud auth application-default login`, your Application Default Credentials are written to `$HOME/.config/gcloud/application_default_credentials.json` and picked up by Nextflow automatically. Otherwise, declare the `GOOGLE_APPLICATION_CREDENTIALS` environment variable explicitly with the local path to your service account credentials file created in the previous step. 3. Add the following to the **Nextflow Config file** field when you [launch](../launch/launchpad#launch-form) your pipeline: ```groovy // Specify cloud storage credentials google { location = '' project = '' batch.serviceAccountEmail = '' } // Set the cloud cache path cloudcache { enabled = true path = 'gs://your-bucket/.cache' } ```
## Relaunch a workflow run An effective way to troubleshoot a workflow execution is to **Relaunch** it with different parameters. Select the **Runs** tab, open the options menu to the right of the run, and select **Relaunch**. You can edit parameters, such as **Pipeline to launch** and **Revision number** before launch. Select **Launch** to execute the run from scratch. :::note The **Relaunch** option is only available for runs launched from the Seqera Platform interface. ::: ## Resume a workflow run Seqera uses Nextflow's **resume** functionality to resume a workflow run with the same parameters, using the cached results of previously completed tasks and only executing failed and pending tasks. Select **Resume** from the options menu to the right of the run of your choice to launch a resumed run of the same workflow, with the option to edit some parameters before launch. Unlike a relaunch, you cannot edit the pipeline to launch or the work directory during a run resume. :::note The **Resume** option is only available for runs launched from the Seqera Platform interface. ::: :::tip For a detailed explanation of the Nextflow resume feature, see _Demystifying Nextflow resume_ ([Part 1](https://www.nextflow.io/blog/2019/demystifying-nextflow-resume.html) and [Part 2](https://www.nextflow.io/blog/2019/troubleshooting-nextflow-resume.html)) in the Nextflow blog. ::: #### Change compute environment during run resume Users with appropriate permissions can change the compute environment when resuming a run. The new compute environment must have access to the original run work directory. This means that the new compute environment must have a work directory that matches the root path of the original pipeline work directory. For example, if the original pipeline work directory is `s3://foo/work/12345`, the new compute environment must have access to `s3://foo/work`. --- ## Launch pipelines(Launch) View, configure, and launch pipelines from your workspace **Launchpad**. ## Launchpad The **Launchpad** enables workspace users to launch pre-configured pipelines, add new pipelines, or perform a quick launch of unsaved pipelines. Use the **Sort by:** drop-down to sort pipelines, either by name or most-recently updated. :::note A pipeline is a repository containing a Nextflow workflow, a compute environment, and pipeline parameters. ::: The list layout is the default **Launchpad** view. Use the toggle next to the **Search** field to switch between the list and tile views. Both views display the compute environment of each pipeline for easy reference. ## Launch form The launch form is used to launch pipelines and to add pipelines to the **Launchpad**. Select **Launch** next to a saved pipeline in the list, or select **launch a run without configuration** to perform a quick launch of an unsaved pipeline. The launch form consists of [General config](#general-config), [Run parameters](#run-parameters), and [Advanced options](#advanced-options) sections to specify your run parameters before execution, and an execution summary. Use section headings or select the **Previous** and **Next** buttons at the bottom of the page to navigate between sections. For saved pipelines, **General config** and **Run parameters** fields are prefilled and can be edited before launch. :::info The launch form accepts URL query parameters. See [Populate launch form with URL query parameters](#populate-launch-form-with-url-query-parameters) for more information. ::: ### General config - **Pipeline to launch**: A Git repository name or URL. For saved pipelines, this is prefilled and cannot be edited. Private repositories require [access credentials][credentials]. :::note Nextflow pipelines are Git repositories that can reside on any public or private Git-hosting platform. See [Git integration][git] in the Seqera docs and [Pipeline sharing][pipeline-sharing] in the Nextflow docs for more details. ::: - **Version name**: The pipeline version name that will be selected as default for this pipeline run. See [Pipeline versioning][pipeline-versioning] for details. - **Version ID**: The pipeline version id that will be selected as default for this pipeline run. See [Pipeline versioning][pipeline-versioning] for details. - **Revision**: A valid repository commit ID, tag, or branch name. Determines the version of the pipeline to launch. - **Commit ID**: Pin pipeline revision to the most recent HEAD commit ID. If no commit ID is pinned, the latest revision of the repository branch or tag is used. - **Pull latest**: Fetch the most recent HEAD commit ID of the pipeline revision at launch time. Unpins the **Commit ID**, if set. :::info See [Git revision management][pipeline-revision] for more information on **Revision**, **Commit ID**, and **Pull latest** behavior. ::: - **Work directory**: The cloud storage or file system path where pipeline scratch data is stored. Seqera will create a scratch sub-folder if only a cloud bucket location is specified. Use file system paths for local or HPC compute environments. :::note The credentials associated with the compute environment must have access to the work directory. ::: - **Main script**: The script file to execute (default: `main.nf`). Config profiles suggestions may update when this field changes. - **Config profiles**: One or more [configuration profile][nextflow-config-profile] names to use for the execution. Config profiles must be defined in the `nextflow.config` file in the pipeline repository. See below for additional details. - **Workflow run name**: A unique identifier for the run, pre-filled with a random name. This can be customized. - **Labels**: Assign new or existing [labels][labels] to the run. - **Compute environment**: The [compute environment][compute-envs] where the run will be launched. - **Schema**: Select the [pipeline schema][pipeline-schema] to validate pipeline parameters and prevent runtime failures. - **Enable lineage**: Track the [provenance][data-lineage] of files produced by pipeline runs. Defaults to the [workspace setting][workspace-settings-lineage]. #### Config profiles The drop-down of available config profiles is populated by inspecting the Nextflow configuration in the pipeline repository. A limited form of static analysis is used to detect profiles in the main configuration and included configurations that match any of the following patterns: - Includes with a static string: ```groovy includeConfig 'conf/profiles.config' includeConfig 'http://...' ``` - Includes with dynamic string that depends on parameters defined in the config: ```groovy includeConfig params.custom_config includeConfig "${params.custom_config_base}/nfcore_custom.config" ``` - Includes with a ternary expression: ```groovy includeConfig params.custom_config_base ? "${params.custom_config_base}/nfcore_custom.config" : "/dev/null" ``` :::note Only the "true" branch is inspected. ::: - Includes within a try-catch statement: ```groovy try { includeConfig "${params.custom_config_base}/nfcore_custom.config" } catch (Exception e) { // ... } ``` #### Output directory Set an optional **Output directory** to override the default location for your pipeline's [workflow outputs][nextflow-workflow-outputs]. This is distinct from your pipeline's own output parameter (such as `outdir`) under [Run parameters](#run-parameters). - Enter an absolute cloud storage path, such as `s3://my-bucket/results`, or select **Browse** to choose a location with [Data Explorer][data-explorer]. Select a **Compute environment** before you browse. - Platform passes this value to Nextflow as `-output-dir`. - **Output directory** is optional and is not carried over on relaunch. Set it for each launch. :::note The **Output directory** field requires Nextflow 24.10.0 or later and a pipeline that uses the [workflow outputs syntax][nextflow-workflow-outputs]. For older pipelines, use your pipeline output parameter (for example, `params.outdir`) instead. ::: ### Run parameters There are four ways to enter **Run parameters** prior to launch: - The **Input form view** displays form fields to enter text, select attributes from drop-downs, and browse input and output locations with [Data Explorer][data-explorer]. - The **Params file view** displays a raw schema that you can edit directly. Select JSON or YAML format from the **View as** drop-down. - **Upload params file** allows you to upload a JSON or YAML file with run parameters. - Specify run parameters with query parameters in the launch URL. See [Populate launch form with URL query parameters](#populate-launch-form-with-url-query-parameters) for more information. Seqera uses a `nextflow_schema.json` file in the root of the pipeline repository to dynamically create a form with the necessary pipeline parameters. Most pipelines contain at least input and output parameters: - **input** Specify compatible input [datasets][datasets] manually or from the drop-down. Select **Browse** to view the available datasets or browse for files in [Data Explorer][data-explorer]. The Data Explorer tab allows you to select input datasets that match your [pipeline schema][pipeline-schema] `mimetype` criteria (`text/csv` for CSV files, or `text/tsv` for TSV files). - **outdir** Your pipeline's own output directory parameter, if defined in the pipeline schema. Specify the output directory where run results will be saved manually, or select **Browse** to choose a cloud storage directory using [Data Explorer][data-explorer]. This is separate from the [**Output directory**](#output-directory) field in **General config**, which sets the Nextflow `-output-dir` value for workflow outputs. The remaining fields will vary for each pipeline, dependent on the parameters specified in the pipeline schema. ### Advanced settings Enter [resource labels][resource-labels], [pipeline secrets][pipeline-secrets], and [advanced options][advanced-options] before launch. #### Resource labels Use resource labels to tag the computing resources created during the workflow execution. While resource labels for the run are inherited from the compute environment and pipeline, admins can override them from the launch form. Applied resource label names must be unique. #### Pipeline secrets Secrets are used to store keys and tokens used by workflow tasks to interact with external systems. Enter the names of any stored user or workspace secrets required for the workflow execution. :::note In AWS Batch compute environments, Seqera passes stored secrets to jobs as part of the Seqera-created job definition. Seqera secrets cannot be used in Nextflow processes that use a [custom job definition][custom-job-definition]. ::: #### Advanced options See [Advanced options](../launch/advanced). After you have filled the necessary launch details, select **Launch**. The **Runs** tab shows your new run in a **submitted** status at the top of the list. Select the run name to navigate to the [**View Workflow Run**][monitoring-overview] page and view the configuration, parameters, status of individual tasks, and run report. :::note For more information on relaunch and resume, see [Nextflow cache and resume][cache-resume]. ::: ## Add new pipeline From the **Launchpad**, select **Add pipeline** to add a new pipeline with pre-saved parameters to your workspace. The fields on the new pipeline form are similar to the pipeline launch form. See [Add pipelines][add-pipelines] for instructions to add pipelines to your workspace via [Seqera Pipelines][seqera-pipelines] or the Launchpad. :::note Pipeline names must be unique per workspace. ::: :::tip To create your own customized Nextflow schema for your pipeline, see [Pipeline schema][pipeline-schema] and the `nf-core` workflows that have adopted this; [nf-core/eager](https://github.com/nf-core/eager/blob/master/nextflow_schema.json) and [nf-core/rnaseq](https://github.com/nf-core/rnaseq/blob/master/nextflow_schema.json) are good examples. ::: ## Email notifications You can receive email notifications upon completion or failure of a workflow execution. Select **Your profile** from the user menu, then toggle **Send notification email on workflow completion** at the bottom of the page. ## Edit pipeline Workspace maintainers can edit existing pipeline details. Select the options menu next to the pipeline in the **Launchpad** list, then select **Edit** to load the pipeline parameters form with pre-filled existing pipeline details to be edited. See [Add from the Launchpad][add-from-launchpad] for more information on the pipeline parameters form fields. Select **Update** when you are ready to save the updated pipeline. :::note Pipeline names must be unique per workspace. ::: ## Populate launch form with URL query parameters The launch form can populate fields with values passed as URL query parameters. For example, append `?revision=master` to your launch URL to prefill the **Revision** field with `master`. This feature is useful for Platform administrators to provide custom pipeline launch URLs to users in order to hard-code required run and pipeline parameters for every run. Platform validates run parameters passed via the launch URL in the following way: - Parameter names are **not** validated. You must provide valid and supported parameters for launch form fields to be populated without error. See supported parameter names in the following section. - Parameter values are validated and warnings are shown for any invalid supplied values. - Disabled launch form fields, such as the `pipeline` field when launching a presaved pipeline, cannot be populated by URL. Parameters that accept arrays (multiple values) as input must be specified with the parameter name for each individual value. For example: ``` ?labelIds=&labelIds= ``` Pipeline-specific run parameters can be passed with the `paramsText` query parameter. Pass both the name and value for any parameter defined in your [pipeline schema][pipeline-schema] in JSON format: ``` ?paramsText={"key1": "value1", "key2": "value2"} ``` :::note When submitted, JSON-formatted paramsText input will be formatted with percent-encoding for spaces, brackets and other non-standard URL characters. For example: ``` ?paramsText={"key1": "value1", "key2": "value2"} ``` will be formatted and added to relevant launch form fields with this syntax: ``` %7B"key1":%20"value1",%20"key2":%20"value2"%7D ``` Platform will ignore added percent-encoding characters in form fields, so you do not need to remove them manually before submitting your pipeline launch. ::: ### Supported URL query parameters and corresponding launch form fields | **Launch form field** | **Query parameter name** | |------------------------------------------------|-----------------------------| | **General config** | | | Pipeline to launch | `pipeline` | | Revision number | `revision` | | Config profiles | `configProfiles` | | Workflow run name | `runName` | | Labels | `labelIds` | | Compute environment | `computeEnvId` | | Work directory | `workDir` | | **Run parameters** | | | Pipeline-specific run parameters | `paramsText` | | **Advanced settings** | | | Resource labels | `resourceLabelIds` | | Nextflow config file | `configText` | | Seqera Cloud config file | `towerConfig` | | Pull latest | `pullLatest` | | Stub run | `stubRun` | | Main script | `mainScript` | | Workflow entry name | `entryName` | | Schema name | `schemaName` | | Head job CPUs | `headJobCpus` | | Head job memory | `headJobMemoryMb` | | Workspace's pipeline secrets | `workspaceSecrets` | | User's pipeline secrets | `userSecrets` | | Pre-run script | `preRunScript` | | Post-run script | `postRunScript` | {/* links */} [credentials]: ../credentials/overview [pipeline-sharing]: https://docs.seqera.io/nextflow/sharing [git]: ../git/overview [pipeline-versioning]: ../pipelines/versioning [pipeline-revision]: ../pipelines/revision [nextflow-config-profile]: https://docs.seqera.io/nextflow/config#config-profiles [nextflow-workflow-outputs]: https://docs.seqera.io/nextflow/workflow#outputs [labels]: ../labels/overview [compute-envs]: ../compute-envs/overview [pipeline-schema]: ../pipeline-schema/overview [data-lineage]: ../data/data-lineage [workspace-settings-lineage]: ../orgs-and-teams/workspace-management#lineage [data-explorer]: ../data/data-explorer [datasets]: ../data/datasets [resource-labels]: ../resource-labels/overview [pipeline-secrets]: ../secrets/overview [advanced-options]: ../launch/advanced [custom-job-definition]: https://docs.seqera.io/nextflow/aws#custom-job-definition [monitoring-overview]: ../monitoring/overview [cache-resume]: ./cache-resume.mdx [add-pipelines]: ../getting-started/quickstart-demo/add-pipelines [seqera-pipelines]: https://seqera.io/pipelines [add-from-launchpad]: ../getting-started/quickstart-demo/add-pipelines#add-from-the-launchpad --- ## Usage limits Seqera Platform features have default limits per organization and workspace. ## Organizations | Description | Basic | Cloud Pro + Enterprise | | ----------------------- | ----- | ---------------------- | | Members | 3 | 50, or per license | | Workspaces | 50 | 50, or per license | | Teams | 20 | 20, or per license | | Run history | 250 | 250, or per license | | Active runs | 3 | 100, or per license | | Running Studio sessions | 1 | 1000, or per license | :::info Seqera applies custom usage limits to academic institutions and commercial organizations evaluating Seqera Platform. [Contact us](https://seqera.io/contact-us/) for more information. ::: ## Workspaces | Description | Basic | Cloud Pro + Enterprise | | ------------ | ----- | ---------------------- | | Participants | 3 | 50, or per license | | Pipelines | 100 | 100, or per license | | Datasets | 100 | 1000, or per license | | Labels | 1000 | 1000, or per license | :::note Some Enterprise instances on older licenses are limited to 100 labels per workspace. [Contact support](mailto:support@seqera.io) to upgrade your license. ::: ## Datasets | Description | Default limit | | -------------------- | ------------- | | File size | 10 MB | | Versions per dataset | 100 | If you need higher limits, [contact us](https://seqera.io/contact-us/) to discuss your requirements. --- ## Audit logs Root users can view application event audit logs from the [Admin panel](../administration/overview) **Audit logs** tab. :::info Application event audit logs are retained for 365 days by default. In Platform Enterprise, this retention period can be [customized](../enterprise/configuration/overview#logging). You can also disable automatic audit log deletion with `TOWER_CRON_AUDIT_LOG_CLEAN_UP_ENABLED`. ::: ## Audit log versions in 26.1 Seqera Platform Enterprise 26.1 introduces the audit log v2 schema as a **breaking change** for direct database consumers and custom ETL jobs. - The legacy audit log schema remains in the `tw_audit_log` table. - The new audit log v2 schema is written to a separate table. - The v2 schema is not backward-compatible with the legacy schema. Field names, structure, and pagination behavior differ. - The v2 Admin panel view and CSV export are available when `TOWER_AUDIT_LOG_V2_WRITE_MODE` is set to `dual` or `v2`. Use `TOWER_AUDIT_LOG_V2_WRITE_MODE` to control how new audit events are written: - `dual`: Write new events to both `v1` schema and `v2` schema. This is the recommended 26.1 migration mode if you need to validate the v2 schema while keeping existing v1 integrations unchanged. - `v2`: Write new events to `v2` schema only. ## Upgrade path for existing integrations If you have existing scripts, exports, or ETL processes that read from the legacy audit log schema, plan the 26.1 upgrade in two stages: 1. Upgrade to 26.1. 2. Validate your integrations against the v2 schema while your existing v1 readers continue to work from the legacy table. In the 26.1 migration plan, dual-write is transitional. Plan for 26.2 to make v2 the only write-side schema, while the legacy v1 data remains available for reads as long as your retention policy still covers the required historical period. ## Audit log event format When audit log v2 is enabled, the Admin panel shows the following event details: - **Timestamp**: Event timestamp in ISO 8601 format. - **Event**: The audit event name, such as `user_sign_in` or `credentials_created`. - **Actor**: Whether the event was triggered by a user or by the system, including point-in-time user details for user-initiated events. - **Client**: Client IP address, user agent, and access token ID when available. Client details are empty for system-initiated events. - **Target**: The resource type, ID, and resource name associated with the event. - **Organization**: The organization ID and name for organization-scoped or workspace-scoped resources. - **Workspace**: The workspace ID and name for workspace-scoped resources. - **Correlation ID**: An identifier that links all audit events emitted as part of the same cascade action. For organization-scoped, personal workspace-scoped, or system-wide targets, the organization and workspace columns display `N/A` labels to indicate when a field does not apply to that resource scope. CSV exports use the same v2 schema and date filters as the Admin panel view. You can control the maximum export size with `TOWER_AUDIT_LOG_V2_CSV_EXPORT_MAX_LOGS`. ### Audit log v2 events Audit log v2 emits the following event names. ::table{file=configtables/audit_events_v2.yml} ### Deprecated audit events The following legacy event names are deprecated. Use the replacement event when one is available. ::table{file=configtables/audit_events_deprecated.yml} ### Pre and post state change capture When enabled, audit log v2 captures full resource state snapshots or images immediately before and after each change event in JSON format. This provides a complete record of what changed and satisfies regulatory requirements (such as GxP/21 CFR Part 11). Fields that are large or that may contain sensitive values are hashed. :::info State snapshots increase database storage requirements. For a deployment with 2 million audit log records, the snapshots can consume between 3 GB and 40 GB depending on the events and the size and complexity of the tracked resources. Plan your database capacity and retention policy accordingly before enabling this feature. ::: This feature is enabled once the GxP add-on is attached to your Seqera license. [Contact us](https://seqera.io/contact-us/) to obtain the GxP add-on. --- ## Monitoring cloud costs Monitor cloud costs to manage resources effectively and prevent unexpected expenses when running pipelines in Seqera Platform. ## Resource labels Use [Resource labels](../resource-labels/overview) in your compute environments to annotate and track the actual cloud resources consumed by a pipeline run. Resource labels are applied to the resources spawned during a run and sent to your cloud provider in `key=value` format. For full cost accounting — including storage and networking — combine resource labels with your cloud provider's native cost tools rather than custom wrapper scripts that dedicate whole instances to single jobs. See [Include Seqera resource labels in AWS billing reports](../resource-labels/overview#include-seqera-resource-labels-in-aws-billing-reports). ## Seqera cost estimate The [run details](../monitoring/run-details) page includes an **Estimated cost** display on the **Metrics** tab. This is the total estimated compute cost of all tasks in the pipeline run. Per-task cost — along with the machine type, price model, and requested CPU and memory used to derive it — is shown in each task's **Metrics** details. The Seqera cost estimator should only be used for at-a-glance heuristic purposes. For accounting and legal cost reporting, use resource labels and leverage your compute platform's native cost reporting tools. :::tip Per-task metrics, including estimated cost, are also available programmatically through the Platform API for building custom cost dashboards across runs. See the [describe workflow task](https://docs.seqera.io/platform-api/describe-workflow-task) and [list workflow tasks](https://docs.seqera.io/platform-api/list-workflow-tasks) API endpoints. ::: The compute cost of a task is computed as follows: $$ \text{Task cost} = \text{VM hourly rate} \times \text{VM fraction} \times \text{Task runtime} $$ $$ \quad \text{VM fraction} = \text{max} ( \frac{\text{Task CPUs}}{\text{VM CPUs}}, \frac{\text{Task memory}}{\text{VM memory}} ) $$ $$ \quad \text{Task runtime} = ( \text{Task complete} - \text{Task start} ) $$ See also: **cost**, **start**, **complete**, **cpus**, and **memory** in the task table. Seqera uses a database of prices for AWS, Azure, and Google Cloud, across all instance types, regions, and zones, to fetch the VM price for each task. This database is updated periodically to reflect the most recent prices. :::note Prior to version 22.4.x, the cost estimate used `realtime` instead of `complete` and `start` to measure the task runtime. The `realtime` metric tends to underestimate the billable runtime because it doesn't include the time required to stage input and output files. ::: The estimated cost is subject to several limitations: - It doesn't account for the cost of storage, network, the head job, or how tasks are mapped to VMs. As a result, it tends to underestimate the true cost of a pipeline run. - On a resumed pipeline run, the cost of cached tasks is included in the estimated cost. This estimate is an aggregation of all compute costs associated with the run. As a result, the total cost of multiple attempts of a pipeline run tends to overestimate the actual cost, because the cost of cached tasks may be counted multiple times. For accurate cost accounting, you should use the cost reporting tools for your cloud provider. ## Cloud provider cost monitoring and alerts AWS, Google Cloud, and Microsoft Azure provide cost alerting and budgeting tools to enable effective cloud resource management and prevent unexpected costs. ### AWS - **Budgets**: [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) lets you set custom cost and usage budgets with alerts when costs or usage exceed pre-defined thresholds. Set up notifications via email or SNS (Simple Notification Service) to receive alerts when budget thresholds are reached. - **Cost Explorer**: [AWS Cost Explorer](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-what-is.html) provides cost management tools to visualize, understand, and manage your AWS costs and usage over time. - **Cost Anomaly Detection**: [AWS Cost Anomaly Detection](https://docs.aws.amazon.com/cost-management/latest/userguide/getting-started-ad.html) uses machine learning models to detect and alert on anomalous spend patterns in your deployed AWS services. ### Google Cloud - **Budgets and budget alerts**: [Budgets](https://cloud.google.com/billing/docs/how-to/budgets) allow you to set budget thresholds for your GCP projects. When costs exceed these thresholds, you can receive alerts via email, SMS, or notifications in the Google Cloud Console. - **Cost management tools**: [Cloud Billing](https://cloud.google.com/billing/docs/onboarding-checklist) provides cost management tools such as billing reports and spend visualization to help you analyze and understand your GCP costs. ### Microsoft Azure - **Cost Management**: [Microsoft Cost Management](https://learn.microsoft.com/en-us/azure/cost-management-billing/costs/overview-cost-management) is a suite of FinOps tools that help organizations analyze, monitor, and optimize their Microsoft Cloud costs. - **Cost alerts**: Create [alerts](https://learn.microsoft.com/en-us/azure/cost-management-billing/costs/overview-cost-management#monitor-costs-with-alerts) for usage anomalies and costs that exceed pre-defined thresholds. --- ## Dashboard The Seqera Platform **Dashboard** is accessed from the user menu and provides an overview of: - Pipeline runs in your personal and organization workspaces. - Studio sessions in your organization workspaces only. - Fusion usage in your organization workspaces. - Resource usage for your organization workspaces. ## Pipelines You can explore the status of pipelines in your personal and in organizational workspaces. On the **Dashboard** page, select **Pipelines**. ### Filters and summary The **Dashboard** view defaults to all organizations and workspaces you can access. Select the **View** drop-down to filter by specific organizations and workspaces, or to view statistics for your personal workspace only. You can filter by time, including a custom date range of up to 12 months. To filter the set of pipelines, select **Filter**. When a filter is applied, the button icon and color changes. ### Export data Select **Export data** in the filter panel near the top of the page to export dashboard data, based on the filters you have applied, in a CSV file. ### Pipelines per organization The pipeline totals for your selected filters are displayed for each organization that you have access to. Depending on the filter selected, each card details a separate workspace or organization. Total pipelines for each organization are arranged by workspace and status. For a detailed view, you can do one of the following: - Select a pipeline integer value in the table to navigate to a list filtered by the status and time range selected. - Select a workspace name in the table to navigate to a list filtered by the workspace selected. ## Studios You can explore the status of Studio sessions in your organizational workspaces. On the **Dashboard** page, select **Studios**. The following statuses are listed with the number of Studio sessions in each status: - `Building` - `Build-failed` - `Starting` - `Running` - `Stopping` - `Stopped` - `Errored` ### Filters and summary The **Dashboard** view defaults to all organizations and workspaces you can access. Select the **View** drop-down to filter by organizations and workspaces. Select a status in the table to navigate to a list filtered by the status selected. ### Export data Select **Export data** in the view panel near the top of the page to export a CSV of the dashboard data for the selected organizations and workspaces. ## Fusion Select a workspace from the drop-down to view Fusion usage for the current and previous month. The usage is displayed in GB and shows a percentage change from the previous month. ## Resource usage You can explore compute resource consumption across your organization workspaces. On the **Dashboard** page, select **Resource usage**. Monthly CPU hours aggregated across your organization workspaces are displayed. :::note The **Resource usage** view is visible to all members of an organization. ::: ### Filters and summary Select the **View** drop-down to select an organization. Select the **Date** drop-down to filter by year. ### Export data Select **Export data** in the view panel near the top of the page to export a CSV of the dashboard data for the selected organization. [ds]: ../studios/overview --- ## Overview Workflow executions submitted in Seqera Platform can be monitored wherever you have an internet connection. The **Runs** tab contains all previous runs in the workspace. Each new or resumed run is given a random name such as _grave_williams_. Each row corresponds to a specific run. As a run executes, it can transition through the following states: - `submitted`: Pending execution - `running`: Running - `succeeded`: Completed successfully - `failed`: Successfully executed, where at least one task failed with a `terminate` [error strategy](https://docs.seqera.io/nextflow/process#errorstrategy) - `cancelled`: Stopped manually during execution - `unknown`: Indeterminate status Select the name of a run from the list to display that run's [execution details](./run-details). ## Save run as pipeline From the **Runs** list, any run can be saved as a new pipeline for future use, regardless of run status. Select the item menu next to any run in the list, then select **Save as pipeline**. In the dialog box shown, you can edit the pipeline name, add labels, and **Save**. You can **Review and edit** any run details prior to saving the pipeline. After you've saved the pipeline, it is listed on the **Launchpad** and can be run from the same workspace where it was created. ## All runs view The **All runs** page, accessed from the user menu, provides a comprehensive overview of the runs accessible to a user across the entire Seqera instance. This facilitates overall status monitoring and early detection of execution issues from a single view, split across organizations and workspaces. The **All runs** view defaults to all organizations and workspaces you can access. Select the drop-down next to **View** to filter by specific organizations and workspaces, or to view runs from your personal workspace only. ### Search The **Search workflow** bar filters by one or more `:` entries: - `status` - `label` - `workflowId` - `runName` - `username` - `projectName` - `after`: YYYY-MM-DD - `before`: YYYY-MM-DD - `sessionId` - `is:starred` The field suggests valid keywords as you type. Suggested results for `label:` include available labels from all workspaces. Labels present in multiple workspaces are only suggested once. Search covers all workflow runs in a workspace. Enter a query in the Search workflow field. Platform identifies each valid `keyword:value` substring, combines the remaining text into a single freeform string, and filters runs using all of these criteria. For example: `rnaseq username:john_doe status:succeeded after:2024-01-01` will retrieve all runs from the workspace that meet the following criteria: - Ended successfully (`status:succeeded`) - Launched by user john_doe (`username:john_doe`) - Include `rnaseq` in the data fields covered by the free text search - Submitted after January 1, 2024 The freetext search uses a _partial_ match to find runs, so it will search for `*freetext*`. The `keyword:value` item uses an _exact_ match to filter runs, so `username:john` will not retrieve runs launched by `john_doe`. :::caution Filtering elements are combined with **AND** logic. This means that queries like `status:succeeded, status:submitted` are formally valid but return an empty list because a workflow can only have one status. The freeform text result of all the `keyword:value` pairs is merged into a unique string that includes spaces. This may result in an empty list of results if the search query contains typos. ::: :::note Keywords corresponding to dates (`after` or `before`) are automatically converted to valid ISO-8601, taking your timezone into account. Partial dates are also supported: `before:2022-5` is automatically converted to `before:2022-05-01T00:00:00.000Z`. ::: Seqera will suggest matching keywords while you type. Valid values are also suggested for some keywords, when supported. ### Search keywords - **Freeform text** The search box allows you to search for partial matches with `project name`, `run name`, `session id`, or `manifest name`. Use wildcards (`*`) before or after keywords to filter results. - **Exact match keywords** - `workflowId:3b7ToXeH9GvESr`: Search workflows with a specific workflow ID. - `runName:happy_einstein`: Search workflows with a specific run name. - `sessionId:85d35eae-21ea-4294-bc92-xxxxxxxxxxxx`: Search workflows with a specific session ID. - `projectName:nextflow-io/hello`: Search workflows with a specific project name. - `userName:john_doe`: Search workflows by a specific user. - `status:succeeded`: Search workflows with a specific status (`submitted`, `running`, `succeeded`, `failed`, `cancelled`, `unknown`). - `before:2024-01-01`: Search workflows submitted on or before the given date in YYYY-MM-DD format. - `after:2024-01-01`: Search workflows submitted on or after the given date in YYYY-MM-DD format. - `label:label1 label:label2`: Search workflows with specific labels. - `is:starred`: Search workflows that have been starred by the user. --- ## Run details Select a workflow run from the **Runs** list to open a run details page. The top of the page contains basic run details and a progress overview for an at-a-glance view of the run's status: - View and copy the run ID, pipeline name and repository, pipeline work directory, compute environment, and launch date. - Select the star icon to favorite the run and find it more easily via a filter view in the runs list later. - Use the options menu to apply labels, relaunch, resume, or delete the run, save the run as a new pipeline, or publish a new pipeline [version](../pipelines/versioning) (if the run was launched from an unnamed draft). Select the tabs below the workflow run progress bar to view further run details: - **Tasks**: View the status and progress of pipeline tasks and [processes](#processes), including extensive [task details](#tasks). - **Logs**: View and download the pipeline run's execution logs. - **Metrics**: View resource [metrics](#wall-time) for the run. - **Configuration**: View Nextflow configuration files and the resolved [configuration](#configuration) used for the run. - **Inputs**: View pipeline parameters used by the run, including their lineage records. - **Outputs**: View files produced by the run, including reports and lineage records for every published file. - **Containers**: View the details of containers used in the run, if any. - **Run Info**: View details about the [run](#run-details), [infrastructure](#infrastructure-details), and [executor](#executors-details). :::tip Data lineage is made available on request. Please contact your Seqera account manager. Lineage-aware fields and tabs only display data when the run was executed with data lineage enabled. There are three ways to enable lineage: - [**Settings > Lineage**][workspace-lineage-settings]. A workspace maintainer configures the cloud credentials, region, and (optionally) bucket name where lineage records are stored. Select **Enable lineage by default** to make the launch form lineage toggle default to on for every run launched in the workspace. - **Launch form toggle**. When launching a pipeline, toggle lineage on or off for the individual run. See [Getting started with data lineage][nextflow-lineage-tutorial] for the underlying lineage data model. ::: ![Task status overview](./_images/task-status-tiles.png) The cards at the top of the **Tasks** tab provide a real-time status of all tasks in the pipeline run: - **Pending**: The task has been created, but not yet submitted to an executor. - **Submitted**: The task has been submitted to an executor, but is not yet running. - **Running**: The task has been launched by an executor (the precise definition of "running" may vary for each executor). - **Cached**: A previous (and valid) execution of the task was found and used instead of executing the task again. See [Cache and resume](../launch/cache-resume). - **Succeeded**: The task completed successfully. - **Failed**: The task failed. - **Aborted**: The task was submitted, but the run was cancelled or failed before the task could begin. ### Processes The **Processes** panel displays the status of each process in a pipeline run. In Nextflow, a process is an individual step in a pipeline, while a task is a particular invocation of a process for given input data. In the panel, each process is shown with a progress bar indicating how many tasks have been completed for that process. The progress bar is color-coded based on task status (**created**, **submitted**, **completed**, **failed**). Select a process to navigate to the [Tasks](#tasks) panel and filter the table contents by the selected process. ### Tasks The **Tasks** panel shows all the tasks that were executed in the run, including the following task details: | Label | Description | |-------|-------------| | **task_id** | Unique identifier for the task. | | **process** | Process name. | | **tag** | User-defined label or tag associated with the task. | | **hash** | Nextflow task hash value. | | **status** | Task execution status (e.g., `COMPLETED`, `FAILED`, `RUNNING`). | | **attempt** | Number of execution attempts for this task (for retry logic). | | **exit** | Task exit code. | | **container** | Container image used to execute the task. | | **native_id** | Native job ID assigned by the executor (e.g., cluster job ID). | | **submit** | Timestamp when the task was submitted for execution. | | **duration** | Total execution time for the task. | | **realtime** | CPU wall time the task actually ran. | | **% cpu** | Percentage of CPU utilization during task execution. | | **% mem** | Percentage of memory utilization during task execution. | | **peak_rss** | Peak resident set size (physical memory usage). | | **peak_vmem** | Peak virtual memory usage. | | **rchar** | Number of characters read from storage. | | **wchar** | Number of characters written to storage. | | **vol_ctxt** | Number of voluntary context switches. | | **inv_ctxt** | Number of involuntary context switches. | | **lineage_id** | Lineage ID (LID) of the task's `TaskRun` record. Populated only when lineage tracking is active for the run. Select the LID to navigate to the lineage record. | Use the search bar to filter tasks with substrings in the table columns such as **process**, **tag**, **hash**, and **status**. For example, if you enter `succeeded` in the **Search task** field, the table displays only tasks that succeeded. #### Task details ![Task details](./_images/task-details.png) Select a task in the task table to open the **Task details** dialog. The dialog has the following tabs: - **About** - **Metrics** - **Execution log** - **Data Explorer** - **Container** :::note If lineage is enabled for the run, the **About** tab content includes **Inputs** and **Outputs** tabs. The **Inputs** and **Outputs** tabs show every input or output consumed by the task, including the name, its lineage type (`Collection` or `Path`), the source path, the lineage labels assigned to it, and the lineage ID of the corresponding lineage record. Select a name to open the file in [Data Explorer](../data/data-explorer). Select a lineage ID or label to navigate to that lineage record. ::: #### About - **Name**: Process name and tag. - **Status**: Exit code, task status, attempts. - **Native ID**: Unique identifier assigned by the underlying execution executor to a specific job. - **Command**: Task script, defined in the pipeline process. - **Environment**: Environment variables supplied to the task. - **Work directory**: Directory where the task was executed. - **Inputs**: File inputs to the task and associated lineage data. - **Outputs**: File outputs from the task and associated lineage data. - **Upstream**: Links to related upstream tasks. - **Downstream**: Links to related downstream tasks. #### Metrics - **Execution time**: Metrics for task submission, start, and completion time: | Label | Description | |-------|-------------| | **submitted** | Task submission timestamp. | | **started** | Task execution timestamp. | | **completed** | Task completion timestamp. | | **total duration** | Time elapsed from task submission to completion, including scheduling time. | | **script execution time** | Task script execution time. | - **Requested resources**: Metrics for the resources requested by the task: | Label | Description | |-------|-------------| | **container image** | Container image name used to execute the task. | | **queue** | The queue that the executor used to run the process. | | **cpus** | Number of CPUs requested for task execution. | | **memory** | Memory requested for task execution. | | **disk space** | Disk space requested for task execution. | | **time limit** | Time requested for task execution. | | **executor** | The Nextflow executor used for this task. | | **cloudZone** | The cloud zone (region) where the task was executed. | | **machineType** | The virtual machine type used for this task. | | **priceModel** | The price model used to calculate the task computation cost. | | **estimated cost** | The estimated cost to compute this task. | - **Used resources**: Metrics for the actual resources used by the task: | Label | Description | |-------|-------------| | **pcpu** | Percentage of CPU used by the task. | | **rss** | Real memory (resident set) size of the task. | | **peakRss** | Peak of real memory used. | | **vmem** | Virtual memory size of the task. | | **peakVmem** | Peak of virtual memory used. | | **rchar** | Number of bytes the task read, using any read-like system call from files, pipes, tty, etc. | | **wchar** | Number of bytes the task wrote, using any write-like system call. | | **readBytes** | Number of bytes the task read directly from disk. | | **writeBytes** | Number of bytes the task originally dirtied in the page-cache (assuming they will go to disk later). | | **syscr** | Number of read-like system call invocations that the task performed. | | **syscw** | Number of write-like system call invocations that the task performed. | | **volCtxt** | Number of voluntary context switches. | | **invCtxt** | Number of involuntary context switches. | #### Execution log The **Execution log** tab provides a real-time log of the selected task's execution. Task execution and other logs (such as `stdout` and `stderr`) are available for download if they are still available in your compute environment. :::note Real-time log streaming is available only for compute environments that stream logs from a cloud logging service: AWS Batch, Azure Batch, Google Cloud Batch, Kubernetes, and the AWS Cloud and Azure Cloud environments. HPC compute environments (such as Slurm, Grid Engine, LSF, and PBS Pro) retrieve the log from the task work directory rather than streaming it. The **Execution log** tab does not refresh automatically while a task runs. Change tabs or refresh the page to load the latest log content. See [Execution logs don't update in real time for HPC compute environments](../troubleshooting_and_faqs/troubleshooting#execution-logs-dont-update-in-real-time-for-hpc-compute-environments). ::: #### Data Explorer If the pipeline work directory is in cloud storage, this tab shows a [Data Explorer](../data/data-explorer) view of the task's work directory location with the files associated with the task. #### Container This tab contains the image and build details of the container used to execute the task: | Label | Description | |-------|-------------| | **Target image** | The container image used to execute the workflow task. | | **Source image** | The container image specified in the workflow configuration, if available. | | **Request ID** | The unique request ID associated with the container. | | **Request time** | The timestamp when the container request was made. | | **Build ID** | The unique build ID assigned when the container was provisioned. | | **Mirror ID** | The unique mirror ID assigned when the container was copied between repositories. | | **Scan ID** | The unique scan ID from the vulnerability security scan of the container. | | **Cached** | Indicates whether the container was previously built in an earlier request. | | **Freeze** | Indicates whether the container was provisioned for persistent storage using Wave freeze mode. | The **Logs** tab contains a window with the Nextflow execution log console output. Select **Download log files** to download: - Nextflow console output, in TXT format. - Nextflow log file, in LOG format. - Execution timeline graph, in HTML format. ![Metrics overview](./_images/metrics-tiles.png) The cards at the top of the **Metrics** tab display a real-time summary of the resources used by the run. #### Wall time Wall time is the duration of the entire workflow run, from submission to completion. While the run is in progress, wall time is a measure of the time elapsed since run start. #### CPU time CPU time is the total CPU time used by all tasks, measured in CPU hours. It is based on the CPUs _requested_, not the actual CPU usage. The CPU time of an individual task is computed as follows: $$ \text{CPU time (CPU-hours)} = \text{Task CPUs} \times \text{Task runtime} $$ The runtime of an individual task is computed as follows: $$ \text{Task runtime} = \text{Task complete} - \text{Task start} $$ See also: **cpus**, **start**, and **complete** in the task table. #### Memory Memory is the total memory used by all tasks. It is based on the memory _requested_, not the actual memory usage. See also: **peakRss** in the task table. #### Data read and write Data read and Data write are the total amount of data (in GB) read from and written to storage. See also: **readBytes** and **writeBytes** in the task table. #### Estimated cost An estimated cost for the run. See [Seqera cost estimate](../monitoring/cloud-costs#seqera-cost-estimate) for details. #### Load ![Load](./_images/load.png) The **Load** panel displays the current number of running tasks and CPU cores vs the maximum number of tasks and CPU cores for the entire pipeline run. These metrics measure the level of parallelism achieved by the pipeline. Use these metrics to determine whether your pipeline runs are fully utilizing the capacity of your compute environment. #### Utilization ![Utilization](./_images/utilization.png) The **Utilization** panel displays the average resource utilization of all tasks that have completed successfully in a pipeline run. The CPU and memory efficiency of a task are computed as follows: $$ \text{CPU efficiency (\%)} = \text{CPU usage (\%)} \times \text{Task CPUs} $$ $$ \text{Memory efficiency (\%)} = \frac{ \text{Peak memory usage} }{ \text{Task memory} } \times \text{100 \%} $$ See also: **pcpu**, **cpus**, **peakRss**, and **memory** in the task table. These metrics measure how efficiently the pipeline is using its compute resources. Low utilization indicates that the pipeline may be over-requesting resources for some tasks. #### Interactive resource plots ![Interactive CPU plot](./_images/interactive-plot.png) The **CPU**, **Memory**, **Job duration**, and **I/O** interactive plots visualize detailed resource usage, grouped by process. These metrics include succeeded and failed tasks. Use these plots to quickly inspect a pipeline run to determine the resources requested and consumed by each process. :::tip Hover the cursor over each box plot to show more details. ::: The **Configuration** tab contains information about the Nextflow configuration files and the Nextflow command used for the run. #### Configuration ![Configuration](./_images/configuration.png) The **Configuration** window displays the locations of the Nextflow configuration files used for the run, and the resolved configuration resulting from those configuration files. #### Command ![Nextflow command](./_images/command.png) The **Command** window displays the Nextflow command used for the run. The **Inputs** tab consolidates the pipeline parameters and the input files used by the run. #### Parameters ![Parameters](./_images/parameters.png) The **Parameters** window displays the pipeline parameters configured for the run, with options to view, copy, or download the parameters in Groovy, JSON, or YAML format. #### Input files The **Input files** table displays every dataset, file, and collection that was used as input for the run: | Column | Description | |--------|-------------| | **Input Name** | Display name of the input. Select the name to open the file in [Data Explorer](../data/data-explorer) or in the corresponding [Dataset](../data/datasets). | | **Type** | Lineage type, such as `Collection` or `Path`. | | **File Path** | Full path to the input. The path is truncated; hover for the complete path. Select the path to open it in [Data Explorer](../data/data-explorer). | | **Lineage ID** | Lineage ID (LID) of the input's lineage record. Only populated when [lineage tracking is enabled][nextflow-lineage-tutorial]. | | **Lineage Labels** | Lineage labels assigned to the input. Each label is a clickable link that navigates to the lineage record for that label. | If the run was not launched with any input files or datasets, the table is empty. The **Outputs** tab links to every file the run published to its output directory: - **Reports** — The named report files configured for the run, such as the MultiQC report or any reports declared in `tower.yml`. #### Reports ![Reports](./_images/reports.png) The **Reports** sub-tab contains a table with the names, details, and paths to all [reports](../reports/overview) generated by the run, if any were configured. Select a report to open a Data Explorer file preview of the report, with options to open the report in a new tab or download it. :::info The containers feature is only available from Nextflow 25.03.1-edge. ::: ![Containers](./_images/containers.png) The **Containers** tab displays the details of containers used in the run, if any. Container details shown include: - **Target image**: Container image used to execute the task. - **Source image**: Container image specified in the workflow configuration, if available. - **Request ID**: Unique request ID associated with the container. - **Request time**: Timestamp when the container request was made. - **Build ID**: Unique build ID assigned when the container was provisioned, linked to the Wave container build report. - **Mirror ID**: Unique mirror ID assigned when the container was copied between repositories, linked to the Wave mirror report. - **Scan ID**: Unique scan ID for the vulnerability security scan of the container, linked to the Wave scan report. - **Cached**: Indicates if the container was built during a previous request. - **Freeze**: Indicates if the container was provisioned for persistent storage using Wave freeze mode. The **Run Info** tab contains at-a-glance details about the run, infrastructure, and executor. When lineage tracking is enabled, it also displays lineage information. Hover over the information icon next to a card's name to view a value description. Select the icons next to any run detail values to copy them. #### Run details ![Run details](./_images/run-details.png) The **Run details** view displays basic run details: - **Pipeline** name. Select **View pipeline details** to navigate to the pipeline details page. - **Pipeline version** information. Select **View version** to navigate to the pipeline details page. - **Workflow repository**. Select **View repository** to navigate to the pipeline Git repository. - Run **ID**. - **Run start time**. - **Total run duration**. - **Launch user**. Select **View user runs** to view a list of the launch user's runs in the same workspace. - **Executor(s)** used for the run (AWS Batch, Azure Batch, etc.). - **Revision and Git commit ID**. The pipeline version and Git commit ID associated with the version used for the run. #### Infrastructure details ![Infrastructure details](./_images/infra-details.png) The **Infrastructure details** view displays compute environment and work directory information: - **Compute environment** name. Select **Preview** to view a window with basic compute environment details, or **View** to navigate to the compute environment page. - **(Provider) operation ID**. The unique identifier for the task submitted to the cloud provider or compute platform, such as an AWS Batch operation ID. - **Work directory**. Select **View** to browse the work directory in Data Explorer. - **Compute environment ID**. #### Executor(s) details ![Infrastructure details](./_images/executor-details.png) View run executor details: - The **Nextflow version** and **Nextflow session ID** for the run. - The version of [**Fusion**](https://docs.seqera.io/fusion) used in the run, if enabled. - Whether the run used [**Wave**](https://docs.seqera.io/wave) (**Enabled** or **Disabled**). [nextflow-lineage-tutorial]: https://docs.seqera.io/nextflow/tutorials/data-lineage [nextflow-label-directive]: https://docs.seqera.io/nextflow/reference/process#label [workspace-lineage-settings]: ../orgs-and-teams/workspace-management#lineage --- ## Custom roles Seqera Platform supports custom roles to define permissions-based access control at a more granular level than the six default [workspace participant roles](./roles.md#workspace-participant-roles). ### Create custom roles Organization owners can add custom roles and assign read, write, execute, admin, and delete permissions for every Seqera resource type: 1. Select your organization name from the organization and workspace switcher in the top navigation. 1. Select **Access control** to view the list of default and custom roles available in your organization. 1. Select **Add role**. 1. Enter a role **Name** and optional **Description**. 1. From the **Permissions** list, select the **Read**, **Write**, **Execute**, **Admin**, and **Delete** permissions your custom role requires for each resource type. 1. Select **Add** to create the custom role and return to the **Access control** roles list. Select **Edit** or **Delete** to manage existing custom roles in the list. ### Permissions Individual permissions grant read, write, execute, admin, or delete access for each Seqera entity. Individual read and write permissions may grant access for multiple operations via the Platform UI, API, and other programmatic tools such as Platform CLI. For example, the `action:read` permission allows a user to view the list of actions in a workspace, view the details of a specific action, and view available action types. #### Compute | Permission | Description | API endpoint | |------------|-------------|--------------| | **compute_environment:read** | List all compute environments | `GET /compute-envs` | | | View compute environment details | `GET /compute-envs/{computeEnvId}` | | **compute_environment:write** | Create a new compute environment | `POST /compute-envs` | | | Edit an existing compute environment | `PUT /compute-envs/{computeEnvId}` | | | Set a compute environment as primary | `POST /compute-envs/{computeEnvId}/primary` | | | Validate compute environment name availability | `GET /compute-envs/validate` | | **compute_environment:delete** | Delete a compute environment | `DELETE /compute-envs/{computeEnvId}` | | **credentials:read** | List all credentials in workspace | `GET /credentials` | | | View credential details | `GET /credentials/{credentialsId}` | | **credentials:write** | Add new credentials | `POST /credentials` | | | Edit existing credentials | `PUT /credentials/{credentialsId}` | | | Validate credentials | _(Used by Platform)_ | | | Validate credential name availability | `GET /credentials/validate` | | **credentials:delete** | Delete credentials | `DELETE /credentials/{credentialsId}` | | **credentials_encrypted:read** | Get encrypted credentials | _(Used by Platform)_ | | **pipeline_secrets:read** | List all pipeline secrets | `GET /pipeline-secrets` | | | View pipeline secret details | `GET /pipeline-secrets/{secretId}` | | **pipeline_secrets:write** | Create a new pipeline secret | `POST /pipeline-secrets` | | | Validate secret name availability | `GET /pipeline-secrets/validate` | | | Edit an existing pipeline secret | `PUT /pipeline-secrets/{secretId}` | | **pipeline_secrets:delete** | Delete a pipeline secret | `DELETE /pipeline-secrets/{secretId}` | | **platform:read** | List available platforms | `GET /platforms` | | | List platform regions | `GET /platforms/{platformId}/regions` | | | View platform details | `GET /platforms/{platformId}` | #### Data | Permission | Description | API endpoint | |------------|-------------|--------------| | **data_link:read** | List all data-links (cloud buckets) | `GET /data-links` | | | Browse data-link contents | `GET /data-links/{dataLinkId}/browse` | | | View data-link details | `GET /data-links/{dataLinkId}` | | **data_link:write** | Refresh data-link cache | `GET /data-links/cache/refresh` | | | Browse data-link directory tree | `GET /data-links/{dataLinkId}/browse-tree` | | | Download files from data-link | `GET /data-links/{dataLinkId}/download` | | | Generate download URL for data-link files | `GET /data-links/{dataLinkId}/generate-download-url` | | | Generate download script | `GET /data-links/{dataLinkId}/script/download` | | | Upload files to data-link | `POST /data-links/{dataLinkId}/upload` | | | Complete file upload to data-link | `POST /data-links/{dataLinkId}/upload/finish` | | | Create a custom data-link | `POST /data-links` | | | Edit data-link metadata | `PUT /data-links/{dataLinkId}` | | **data_link:delete** | Delete files from data-link | `DELETE /data-links/{dataLinkId}/content` | | | Remove a data-link from workspace | `DELETE /data-links/{dataLinkId}` | | **data_link:admin** | Hide data-links | _(Used by Platform)_ | | | Show data-links | _(Used by Platform)_ | | **dataset:read** | List datasets (legacy endpoint) | `GET /workspaces/{workspaceId}/datasets` | | | List workspace dataset versions (legacy endpoint) | `GET /workspaces/{workspaceId}/datasets/versions` | | | List dataset versions (legacy endpoint) | `GET /workspaces/{workspaceId}/datasets/{datasetId}/versions` | | | View dataset metadata (legacy endpoint) | `GET /workspaces/{workspaceId}/datasets/{datasetId}/metadata` | | | Download dataset | `GET /workspaces/{workspaceId}/datasets/{datasetId}/v/{version}/n/{fileName}` | | | List all datasets | `GET /datasets` | | | List latest dataset versions | `GET /datasets/versions` | | | List versions for a specific dataset | `GET /datasets/{datasetId}/versions` | | | List datasets used in a pipeline launch | `GET /launch/{launchId}/datasets` | | | View dataset metadata | `GET /datasets/{datasetId}/metadata` | | | Download dataset files | `GET /datasets/{datasetId}/v/{version}/n/{fileName}` | | **dataset:write** | Create dataset (legacy endpoint) | `POST /workspaces/{workspaceId}/datasets` | | | Edit dataset (legacy endpoint) | `PUT /workspaces/{workspaceId}/datasets/{datasetId}` | | | Upload dataset (legacy endpoint) | `POST /workspaces/{workspaceId}/datasets/{datasetId}/upload` | | | Create a new dataset | `POST /datasets` | | | Edit dataset metadata | `PUT /datasets/{datasetId}` | | | Upload files to dataset | `POST /datasets/{datasetId}/upload` | | **dataset:delete** | Delete dataset (legacy endpoint) | `DELETE /workspaces/{workspaceId}/datasets/{datasetId}` | | | Delete a single dataset | `DELETE /datasets/{datasetId}` | | | Delete multiple datasets | `DELETE /datasets` | | **dataset:admin** | Hide any workspace user's datasets | `POST /datasets/hide` | | | Show any workspace user's datasets | `POST /datasets/show` | | | Disable any workspace user's dataset version | `POST /datasets/{datasetId}/versions/{version}/disable` | | **dataset_label:write** | Add labels to datasets | `POST /datasets/labels/add` | | | Remove labels from datasets | `POST /datasets/labels/remove` | | | Apply label sets to datasets | `POST /datasets/labels/apply` | #### Pipelines | Permission | Description | API endpoint | |------------|-------------|--------------| | **action:read** | View action details | `GET /actions/{actionId}` | | | View available action types | `GET /actions/types` | | | List all actions in workspace | `GET /actions` | | **action:execute** | Trigger an action to run | `POST /actions/{actionId}/launch` | | **action:write** | Create a new action | `POST /actions` | | | Edit an existing action | `PUT /actions/{actionId}` | | | Test action configuration | _(Used by Platform)_ | | | Pause a running action | `POST /actions/{actionId}/pause` | | | Validate action name availability | `GET /actions/validate` | | **action:delete** | Delete an action | `DELETE /actions/{actionId}` | | **action_label:write** | Apply resource labels when adding an action | Sub-operation on `POST /actions` | | | Apply resource labels when editing an action | Sub-operation on `PUT /actions/{actionId}` | | | Add labels to actions | `POST /actions/labels/add` | | | Remove labels from actions | `POST /actions/labels/remove` | | | Apply label sets to actions | `POST /actions/labels/apply` | | **container:read** | View container details | _(Used by Platform)_ | | | List containers | _(Used by Platform)_ | | | List workflow containers | _(Used by Platform)_ | | **launch:read** | View launch details | `GET /launch/{launchId}` | | **pipeline:read** | View pipeline repository information | `GET /pipelines/info` | | | View pipeline schema and parameters | `GET /pipelines/{pipelineId}/schema` | | | View pipeline schema from repository URL | _(Used by Platform)_ | | | View pipeline launch configuration | `GET /pipelines/{pipelineId}/launch` | | | List available pipeline repositories | `GET /pipelines/repositories` | | | List all pipelines in workspace | `GET /pipelines` | | | View pipeline details | `GET /pipelines/{pipelineId}` | | | List pipeline versions | `GET /pipelines/{pipelineId}/versions` | | | Fetch pipeline optimization | _(Used by Platform)_ | | **pipeline:write** | Modify pipeline details when launching a pipeline run | Sub-operation on `POST /workflow/launch` | | | Add a new pipeline to workspace | `POST /pipelines` | | | Edit pipeline (default version) configuration | `PUT /pipelines/{pipelineId}` | | | Configure pipeline | _(Used by Platform)_ | | | Validate pipeline name availability | `GET /pipelines/validate` | | | Create a pipeline schema | `POST /pipeline-schemas` | | | Validate pipeline version name availability | `GET /pipelines/{pipelineId}/versions/validate` | | | Manage pipeline version | `PUT /pipelines/{pipelineId}/versions/{versionId}/manage` | | | Edit pipeline version configuration | `POST /pipelines/{pipelineId}/versions/{versionId}` | | **pipeline:delete** | Delete a pipeline | `DELETE /pipelines/{pipelineId}` | | **pipeline_label:write** | Apply resource labels when launching a pipeline run | Sub-operation on `POST /workflow/launch` | | | Add labels to pipelines | `POST /pipelines/labels/add` | | | Apply resource labels when adding a pipeline | Sub-operation on `POST /pipelines` | | | Apply resource labels when editing a pipeline (default version) | Sub-operation on `PUT /pipelines/{pipelineId}` | | | Apply resource labels when editing a pipeline version | Sub-operation on `POST /pipelines/{pipelineId}/versions/{versionId}` | | | Remove labels from pipelines | `POST /pipelines/labels/remove` | | | Apply label sets to pipelines | `POST /pipelines/labels/apply` | | **workflow:read** | View run details | `GET /workflow/{workflowId}` | | | View run progress | `GET /workflow/{workflowId}/progress` | | | List tasks in a run | `GET /workflow/{workflowId}/tasks` | | | View individual task details | `GET /workflow/{workflowId}/task/{taskId}` | | | View run metrics | `GET /workflow/{workflowId}/metrics` | | | List all runs in workspace | `GET /workflow` | | | View run launch configuration | `GET /workflow/{workflowId}/launch` | | | View run execution logs | `GET /workflow/{workflowId}/log` | | | View task-specific logs | `GET /workflow/{workflowId}/log/{taskId}` | | | Download run logs | `GET /workflow/{workflowId}/download` | | | Download run content in a workspace | _(Used by Platform)_ | | | Download task logs | `GET /workflow/{workflowId}/download/{taskId}` | | | View run reports | _(Used by Platform)_ | | | Download run report | _(Used by Platform)_ | | | Fetch workflow optimization | _(Used by Platform)_ | | | Check optimized workflow list | _(Used by Platform)_ | | **workflow:execute** | Launch a pipeline run | `POST /workflow/launch` | | | Cancel a running pipeline | `POST /workflow/{workflowId}/cancel` | | | Launch a pipeline run | _(Used by Platform)_ | | **workflow:write** | Create execution trace | `POST /trace/create` | | | Update trace heartbeat | `PUT /trace/{workflowId}/heartbeat` | | | Mark trace begin | `PUT /trace/{workflowId}/begin` | | | Mark trace complete | `PUT /trace/{workflowId}/complete` | | | Update trace progress | `PUT /trace/{workflowId}/progress` | | **workflow:delete** | Delete a single run | `DELETE /workflow/{workflowId}` | | | Delete multiple runs | `POST /workflow/delete` | | **workflow_label:write** | Add labels to runs | `POST /workflow/labels/add` | | | Remove labels from runs | `POST /workflow/labels/remove` | | | Apply label sets to runs | `POST /workflow/labels/apply` | | **workflow_quick:execute** | Launch quick pipeline | Sub-operation on `POST /workflow/launch` | | | Launch quick pipeline | _(Used by Platform)_ | | | GA4GH: create a run | `POST /ga4gh/wes/v1/runs` | | **workflow_star:read** | Check if run is starred (favorited) | `GET /workflow/{workflowId}/star` | | **workflow_star:write** | Star (favorite) a run | `POST /workflow/{workflowId}/star` | | **workflow_star:delete** | Unstar (unfavorite) a run | `DELETE /workflow/{workflowId}/star` | #### Settings | Permission | Description | API endpoint | |------------|-------------|--------------| | **label:read** | List all workspace labels | `GET /labels` | | **label:write** | Create a new label | `POST /labels` | | | Edit an existing label | `PUT /labels/{labelId}` | | **label:delete** | Delete a label | `DELETE /labels/{labelId}` | | **workspace:read** | View workspace details | `GET /orgs/{orgId}/workspaces/{workspaceId}` | | | List workspace participants | `GET /orgs/{orgId}/workspaces/{workspaceId}/participants` | | **workspace:write** | Edit workspace settings | `PUT /orgs/{orgId}/workspaces/{workspaceId}` | | | Add a workspace participant | `PUT /orgs/{orgId}/workspaces/{workspaceId}/participants/add` | | | Find workspace participant candidates | _(Used by Platform)_ | | | Change participant role | `PUT /orgs/{orgId}/workspaces/{workspaceId}/participants/{participantId}/role` | | | Remove a workspace participant (user or team) | `DELETE /orgs/{orgId}/workspaces/{workspaceId}/participants/{participantId}` | | | Remove a workspace user (member or collaborator) | `DELETE /orgs/{orgId}/workspaces/{workspaceId}/users/{userId}` | | **workspace:delete** | Delete the workspace | `DELETE /orgs/{orgId}/workspaces/{workspaceId}` | | **workspace:admin** | Change participant role to/from Owner | Sub-operation on `PUT /orgs/{orgId}/workspaces/{workspaceId}/participants/{participantId}/role` | | | Remove a workspace Owner by participantId | Sub-operation on `DELETE /orgs/{orgId}/workspaces/{workspaceId}/participants/{participantId}` | | | Remove a workspace Owner by userId | Sub-operation on `DELETE /orgs/{orgId}/workspaces/{workspaceId}/users/{userId}` | | **workspace_self:delete** | Leave workspace (remove self as participant) | `DELETE /orgs/{orgId}/workspaces/{workspaceId}/participants` | | **workspace_studio:read** | View studio settings for workspace | `GET /orgs/{orgId}/workspaces/{workspaceId}/settings/studios` | | **workspace_studio:write** | Edit studio settings for workspace | `PUT /orgs/{orgId}/workspaces/{workspaceId}/settings/studios` | #### Studios | Permission | Description | API endpoint | |------------|-------------|--------------| | **studio:read** | View studio session details | `GET /studios/{sessionId}` | | | View studio repository details | _(Used by Platform)_ | | | List all studios in workspace | `GET /studios` | | | List available studio templates | `GET /studios/templates` | | | List checkpoints for a studio | `GET /studios/{sessionId}/checkpoints` | | | View checkpoint details | `GET /studios/{sessionId}/checkpoints/{checkpointId}` | | **studio:execute** | List mounted data-links for studios | `GET /studios/data-links` | | | Start a studio session | `PUT /studios/{sessionId}/start` | | | Stop a studio session | `PUT /studios/{sessionId}/stop` | | **studio:write** | Create a new studio | `POST /studios` | | | Edit checkpoint name | `PUT /studios/{sessionId}/checkpoints/{checkpointId}` | | | Validate studio name availability | `GET /studios/validate` | | **studio:delete** | Delete a studio | `DELETE /studios/{sessionId}` | | **studio:admin** | Delete another user's private studio | Sub-operation on `DELETE /studios/{sessionId}` | | | Start another user's private studio | Sub-operation on `PUT /studios/{sessionId}/start` | | | Stop another user's private studio | Sub-operation on `PUT /studios/{sessionId}/stop` | | | Extend another user's private studio session lifespan (iframe) | _(Used by Platform)_ | | | Extend another user's private studio session lifespan | Sub-operation on `POST /studios/{sessionId}/lifespan` | | | Administer another user's private studio | _(Used by Platform)_ | | **studio_label:write** | Apply resource labels when starting a studio | Sub-operation on `PUT /studios/{sessionId}/start` | | **studio_session:read** | Open a studio | _(Used by Platform)_ | | **studio_session:execute** | Extend studio session lifespan (iframe) | _(Used by Platform)_ | | | Extend studio session lifespan | `POST /studios/{sessionId}/lifespan` | --- ## Organizations Organizations are the top-level structure and contain workspaces, members, and teams. You can create multiple organizations, each of which can contain multiple workspaces with shared users and resources. This means you can customize and organize the use of resources while maintaining an access control layer for users associated with a workspace. Organization owners can add or remove members from an organization or workspace, and can allocate specific access roles within workspaces. Teams provide a way to group users and participants together, such as `workflow-developers` or `analysts`, and apply access control for all users within that team. You can also add external collaborators to an organization. ### Create an organization 1. From the user menu, select [Your organizations](https://cloud.seqera.io/orgs), then **Add Organization**. 2. Enter a **Name** and **Full name** for your organization. 3. Enter any other optional fields as needed: **Description**, **Location**, **Website URL**, and **Logo**. 4. Select **Add**. ### Edit an organization :::note From version 23.2, **organization owners** can edit their organization name, either from the organizations page or the [Admin panel](../administration/overview). ::: As an **organization owner**, access the organization page from the organizations and workspaces drop-down, or open the user menu and select **Your organizations** to view and edit your organizations. As a root user, you can also edit organizations from the [Admin panel](../administration/overview). Open the **Settings** tab on the organization page, and select **Edit** in the **Edit Organization** row. Update the settings and select **Update** to save. ### Organization resource usage tracking Select **Usage overview** next to the organization and workspace selector drop-down to view a window with the following usage details: - **Run history**: The total number of pipeline runs. - **Concurrent runs**: Total simultaneous pipeline runs. - **Running Studio sessions**: Number of concurrent running Studio sessions. - **Users**: Total users per organization. Organization resource usage information is also displayed on the organization's **Settings** tab, under **Usage**. Select **Contact us to upgrade** if you need to increase your Platform usage limits for your organization. :::info Usage limits differ per organization and [subscription type](https://seqera.io/pricing/). [Contact us](https://seqera.io/contact-us/) to discuss your needs. ::: ## Members You can view the list of all organization **Members** from the organization's page. Once an organization is created, the user who created the organization is the default owner of that organization. You can invite or add additional members to the workspace from the workspace page or the [Admin panel](../administration/overview). Seqera provides access control for members of an organization by classifying them either as an **Owner** or a **Member**. Each organization can have multiple owners and members. ### Add a member To add a new member to an organization: 1. Go to the **Members** tab of the organization menu. 2. Select **Add member**. 3. Enter the name or email address of the user you'd like to add to the organization. An email invitation will be sent to the user. Once they accept the invitation, they can switch to the organization (or organization workspace) from the workspace drop-down. :::note For information about what happens when a user deletes their account, see [user deletion](../data-privacy/overview#user-deletion). ::: ## Teams **Teams** allow organization **owners** to group members and collaborators together into a single unit and to manage them as a whole. ### Create a new team To create a new team within an organization: 1. Go to the **Teams** tab of the organization menu. 2. Select **Add Team**. 3. Enter the **Name** of team. 4. Optionally, add the **Description** and the team's **Avatar**. 5. Select **Add**. To start adding members to your team, select **Edit > Members of team > Add member** and enter the name or email address of the organization members or collaborators. ## Collaborators **Collaborators** are users who are invited to an organization's workspace, but are not members of that organization. As a result, their access is limited to that organization workspace. You can view the list of all organization **Collaborators** from the organization's page. New collaborators to an organization's workspace can be added as **Participants** from the workspace page. See [User roles](./roles) to learn more about participant access levels. :::note **Collaborators** can only be added from a workspace. For more information, see [workspace management](./workspace-management#create-a-new-workspace). ::: --- ## Personal profile and default settings These settings control how you're identified in Seqera Platform, which workspace you land in after sign-in, and your notification preferences. ## Profile fields | Field | Required | Editable | Description | | --- | --- | --- | --- | | **Email** | Yes | No | Email address used to sign in. Locked after account creation. | | **User name** | Yes | Yes | Auto-generated from email. Lowercase alphanumeric and dash characters only. | | **First name** | No | Yes | First name. | | **Last name** | No | Yes | Surname or family name. | | **Avatar** | No | Yes | Profile picture. Auto-generated if not provided. | | **Organization** | No | Yes | Name of your company or organization. | | **Description** | No | Yes | Free-text information about yourself, shown to other Seqera Platform users. | ## Default settings | Setting | Default | Description | | --- | --- | --- | | **Send notification email on workflow completion** | Off | Receive an email when a pipeline run completes. | ## Delete your account :::warning This action cannot be undone. ::: Delete your account from Seqera Platform. --- ## User roles Organization owners can assign role-based access levels to individual **participants** and **teams** in an organization workspace. :::tip You can group **members** and **collaborators** into **teams** and apply a role to that team. Members and collaborators inherit the access role of the team. ::: ### Organization user roles - **Owner**: After an organization is created, the user who created the organization is the default owner of that organization. Additional users can be assigned as organization owners. Owners have full read/write access to modify members, teams, collaborators, and settings within an organization. Organization owners always have full owner access to organization workspaces, regardless of their participant roles at the workspace level. - **Member**: A member is a user who is internal to the organization. Members have an organization role and can operate in one or more organization workspaces. In each workspace, members have a participant role that defines the permissions granted to them within that workspace. ### Role inheritance If a user is concurrently assigned to a workspace as both a named **participant** and member of a **team**, Seqera assigns the higher of the two privilege sets. Example: - If the participant role is Launch and the team role is Admin, the user will have Admin rights. - If the participant role is Admin and the team role is Launch, the user will have Admin rights. - If the participant role is Launch and the team role is Launch, the user will have Launch rights. As a best practice, use teams as the primary vehicle for assigning rights within a workspace and only add named participants when one-off privilege escalations are necessary. ## Workspace participant roles The default workspace participant roles are: - **Owner**: The user who created the workspace is its first owner. Owners have full administrative privileges over a workspace and its resources, including permission to delete the workspace. Regular participants can also be promoted to workspace owners. - **Admin**: Workspace admins share most of the administrative privileges of workspace owners, but admins cannot delete a workspace. - **Maintain**: Workspace maintainers can use and manage all workspace resources, but cannot create workspace credentials, compute environments, or Studios - **Launch**: Launch users can use existing workspace resources and launch pipelines, but they cannot modify workspace resources. - **Connect**: Connect users can connect to running workspace Studios. - **View**: View users can view workspace resources, but cannot modify or execute them. See [Custom roles](./custom-roles.md) for instructions to create roles with custom permissions. :::note Workspace participants with any role can leave the workspace, i.e., remove themselves as a workspace participant. However, only workspace owners and admins can add or remove workspace participants other than themselves. ::: ### Role permissions The following table shows which operations are available to the default workspace participant roles: | Permission | Owner | Admin | Maintain | Launch | Connect | Viewer | |--------------------------------|-------|-------|----------|--------|---------|--------| | **action:read** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **action:execute** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **action:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **action:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **action_label:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **compute_environment:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **compute_environment:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **compute_environment:delete** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **container:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **credentials:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **credentials:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **credentials:delete** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **credentials_encrypted:read** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **data_link:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **data_link:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **data_link:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **data_link:admin** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **dataset:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **dataset:write** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **dataset:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **dataset:admin** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **dataset_label:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **label:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **label:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **label:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **launch:read** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **lineage:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **pipeline:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **pipeline:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **pipeline:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **pipeline_label:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **pipeline_secrets:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **pipeline_secrets:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **pipeline_secrets:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **platform:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **studio:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **studio:execute** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **studio:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **studio:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **studio:admin** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **studio_label:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **studio_session:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | | **studio_session:execute** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | | **workflow:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workflow:execute** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **workflow:write** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **workflow:delete** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **workflow_label:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **workflow_quick:execute** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **workflow_star:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workflow_star:write** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workflow_star:delete** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workspace:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workspace:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **workspace:delete** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | **workspace:admin** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | **workspace_lineage:read** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **workspace_lineage:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **workspace_self:delete** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workspace_studio:read** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **workspace_studio:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | --- ## Teams **Teams** allow organization owners to group members and collaborators together into a single unit and to manage them as a whole. Apply a workspace role to a team and every member inherits that access. See [User roles](./roles) for the available roles. :::note If your organization has [single sign-on (SSO)](../enterprise/configuration/authentication/overview) and IdP group claims mapping enabled, the team can be delegated to **IdP Groups**. See [Delegate a team to an IdP group](#delegate-a-team-to-an-idp-group). ::: ## Create a team To create a new team: 1. Go to the **Teams** tab in the sidebar of the organization landing page. 2. Select **Add Team**. 3. Enter the **Name** of the team. 4. Optionally, add the **Description** and the team's **Avatar**. 5. Select **Add**. To add members to the team, select **Edit**, then **Members of team**, then **Add member**. Enter the name or email address of an organization member or collaborator. ## Edit a team 1. Open the **Teams** tab and select the team you want to edit. 2. Select **Edit**. 3. Update the **Name**, **Description**, **Avatar**, or membership. 4. Select **Update** to save. The same surface is used to delete a team. The **Delete** action is disabled for delegated teams. Clear the **IdP Group** field first. ## Delegate a team to an IdP group Organizations with an active OIDC SSO connection can delegate team membership to an identity provider (IdP) group. Once a team is delegated, the IdP becomes the sole authority for who belongs. Platform evaluates each user's IdP claims at every login and adjusts membership automatically. For the runtime model behind delegation, see [IdP delegation overview](../enterprise/configuration/authentication/idp-delegation/overview). :::info[**Prerequisites**]{#prerequisites} You will need the following to get started: - An active OIDC SSO connection on your organization. See [Authentication](../enterprise/configuration/authentication/overview). - A populated IdP group catalog. See [Manage your IdP group catalog](../enterprise/configuration/authentication/idp-delegation/group-catalog/overview). - An IdP that emits the `groups` claim in OIDC tokens. See [IdP claim mapping](../enterprise/configuration/authentication/idp-delegation/claim-mapping). - Organization owner access to your Seqera organization. ::: ### Delegate the team 1. In Platform, open **Organization settings > Group mapping**. 2. In the **IdP groups** field, select a group from the drop-down, which is populated from your organization's IdP group catalog. 3. Select **Update** to save. The same IdP group can be assigned to more than one team. Each team can reference exactly one IdP group. ### What changes when a team is delegated After you delegate a team: - Membership becomes immutable in the Platform UI. The **Add member** and **Remove member** controls are hidden. - The team cannot be deleted. To delete a delegated team, clear the **IdP Group** field first. - The team's name, description, avatar, and **IdP Group** value remain editable. - Existing manual workspace and role assignments on the team are preserved. - The team is marked **IdP Delegated** in the teams list. ### What happens at login On every SSO login, Seqera evaluates each delegated team against the user's `groups` claim and updates membership accordingly: - **Match found**: The user is added to the team if they aren't already a member. - **No match**: And the user was previously a member - they're removed from the team. - **No match**: And the user was never a delegation-driven member - no change. Users added manually to a team with no **IdP Group** value keep their membership regardless of their IdP claims. If the user's token has no `groups` claim or the claim is malformed, no changes take place.. ### Stop delegating a team To convert a delegated team back to manual management: 1. In Platform, open **Organization settings > Group mapping**. 2. Clear the **IdP Group** field. 3. Select **Update** to save. Existing members are kept. The **Add member** and **Remove member** controls become available again, and the team can be deleted as normal. ## Workspace and role assignment Delegation controls who belongs to the team. It doesn't assign the team to workspaces or grant roles. After delegation: - Assign the team to a workspace using the workspace **Participants** page. - Set the team's workspace role separately. See [User roles](./roles). This separation is intentional: the IdP owns membership, but the organization owns access policy. --- ## Workspaces Each user has a unique **user workspace** to manage resources such as pipelines, compute environments, and credentials. You can also create multiple workspaces within an organization context and associate each of these workspaces with dedicated teams of users, while providing fine-grained access control for each of the teams. **Organization workspaces** extend the functionality of user workspaces by adding the ability to fine-tune access levels for specific members, collaborators, or teams. This is achieved by managing **participants** in the organization workspaces. Organizations consist of members, while workspaces consist of participants. :::note A workspace participant may be a member of the workspace organization or a collaborator within that workspace only. Collaborators count toward the total number of workspace participants. See [Usage limits](../limits/overview). ::: ## Create a new workspace Organization owners and admins can create a new workspace within an organization: 1. Go to the **Workspaces** tab of the organization page. 2. Select **Add Workspace**. 3. Enter the **Name** and **Full name** for the workspace. 4. Optionally, add a **Description** for the workspace. 5. Under **Visibility**, select either **Private** or **Shared**. Private visibility means that workspace pipelines are only accessible to workspace participants. 6. Select **Add**. :::tip As a workspace owner, you can modify optional workspace fields after workspace creation. You can either select **Edit** on an organization's workspaces list or the **Settings** tab within the workspace page. ::: Apart from the **Participants** tab, the _organization_ workspace is similar to the _user_ workspace. As such, the relation to [runs](../launch/launchpad), [actions](../pipeline-actions/overview), [compute environments](../compute-envs/overview), and [credentials](../credentials/overview) is the same. ## Workspace settings ### Studios - **Collaboration mode**: Limit which members can connect to a running Studio in the workspace. Toggle between **Collaborative** (any member with the right permissions can connect) and **Private** (only the creator can connect). Default is **Collaborative** mode. - **Session lifespan**: Set a predefined lifespan (between 1 and 120 hours), after which all Studio sessions in the workspace are automatically stopped. To keep all workspace Studios running indefinitely, select **Always keep the session running**. Default is a session lifespan of **8 hours**. - **Container repository**: Define the target container repository where custom Studio images built with Wave will be pushed. The workspace must have a credential with read and write permissions to the target container registry. There is no default and custom builds will fail for self-hosted deployments. - **Container naming strategy**: Define your container registry naming strategy. Default for Seqera Cloud is **tagPrefix**. - **tagPrefix**: Differentiate application versions within the same repository (e.g., `registry/image:prefix-version`). This strategy is recommended for organizing specific image types (`dev`, `staging`, `prod`) and typically results in fewer repositories with more tags. - **imageSuffix**: Group different build types across repositories (e.g., `registry/image-suffix:version`). This strategy is recommended for managing permissions or different build environments (`front-end` vs. `back-end`, or `API` vs. `GUI`) and typically results in higher repository counts (i.e., one repository per environment/variant). :::note Studios sessions created in shared workspaces are not shared across all the workspaces in an organization. ::: ### Labels Select **Manage** to open the workspace [labels and resource labels](../labels/overview). ### Lineage :::note Data lineage is in public preview and not enabled by default. See [Configuration options](../enterprise/configuration/overview#data-features). ::: Configure where Nextflow lineage data are stored and whether lineage tracking is on by default for every run launched in the workspace. Select **Manage** and then choose to enable lineage by default for all pipeline runs in the workspace. Configure the lineage settings manually or automatically. | Field | Required | Description | |-------|----------|-------------| | **Credentials** | Yes | The workspace credentials Platform uses to create and access the lineage storage bucket. The credentials must include permission to create buckets in the chosen region (or to access an existing bucket if **Bucket name** is specified), activate object notifications on the bucket, and manage the SQS queue. | | **Region** | Yes | Cloud region where the lineage storage bucket is created (for example, `us-east-1`, `eu-west-1`). | | **Bucket name** | No | Bucket where lineage records are stored. If left empty, Platform generates a default bucket name in the form `seqera-lineage-`. | If configuring **manually**, two additional settings can be defined: | Field | Required | Description | |-------|----------|-------------| | **SQS Queue name** | No | The Amazon Simple Queue Service (SQS) name. If left empty, Platform generates a default queue name in the form `-notifications`. | | **SQS Queue ARN** | No | The ARN of the SQS queue. This is useful if your Platform deployment requires cross-account access. | ### Edit or delete a workspace :::note From version 23.2, **workspace owners** can edit their workspace name, either from the workspace settings tab or the [Admin panel](../administration/overview). ::: Select **Edit workspace** to update the workspace name, full name, description, and sharing. Select **Update** to save changes. Select **Delete workspace** to delete the workspace and its associated resources. This action cannot be reversed. ## Add a new participant A new workspace participant can be an existing organization member, team, or collaborator. To add a new participant to a workspace: 1. Go to the **Participants** tab in the workspace menu. 2. Select **Add participant**. 3. Enter the **Name** of the new participant. 4. Optionally, update the participant **role**. ## Workspace run monitoring To allow users executing pipelines from the command line to share their runs with a given workspace, see [deployment options](../getting-started/deployment-options#nextflow--with-tower). Seqera Platform introduces the concept of shared workspaces as a solution for synchronization and resource sharing within an organization. A shared workspace enables the creation of pipelines in a centralized location, making them accessible to all members of an organization. The benefits of using a shared workspace within an organization include: - **Define once and share everywhere**: Set up shared resources once and automatically share them across the organization. - **Centralize the management of key resources**: Organization administrators can ensure the correct pipeline configuration is used in all areas of an organization without the need to replicate pipelines across multiple workspaces. - **Immediate update adoption**: Updated parameters for a shared pipeline become immediately available across the entire organization, reducing the risk of pipeline discrepancies. - **Computational resource provision**: Pipelines in shared workflows can be shared along with the required computational resources. This eliminates the need to duplicate resource setup in individual workspaces across the organization. Shared workspaces centralize and simplify resource sharing within an organization. ### Create a shared workspace Creating a shared workspace is similar to the creation of a private workspace, with the exception of the **Visibility** option, which must be set to **Shared**. ### Create a shared pipeline When you create a pipeline in a shared workspace, associating it with a [compute environment](../compute-envs/overview) is optional. If a compute environment from the shared workspace is associated with the pipeline, it will be available to users in other organization workspaces to launch the shared pipeline with the associated compute environment by default. ### Use shared pipelines from a private workspace Once a pipeline is set up in a shared workspace and associated with a compute environment in that workspace, any user can launch the pipeline from an organization workspace using the shared workspace's compute environment. This eliminates the need for users to replicate shared compute environments in their private workspaces. :::note The shared compute environment will not be available to launch other pipelines limited to that specific private workspace. ::: If a pipeline from a shared workspace is shared **without** an associated compute environment, users can run it from other organization workspaces. By default, the **primary** compute environment of the launching workspace will be selected. ### Make shared pipelines visible in a private workspace :::note Pipelines from _all_ shared workspaces are visible when the visibility is set to **Shared workspaces**. ::: To view pipelines from shared workspaces, go to the [Launchpad](../launch/launchpad) and set the **Filter > Pipelines from** option to **This and shared workspaces**. --- ## Pipeline actions Actions enable event-based pipeline execution, such as triggering a pipeline launch with a GitHub webhook whenever the pipeline repository is updated. Seqera Platform currently offers support for native **GitHub webhooks** and a general **Tower webhook** that can be invoked programmatically. ### GitHub webhooks A **GitHub webhook** listens for any changes made in the pipeline repository. When a change occurs it triggers the launch of the pipeline automatically. :::note You must sign in to Seqera using GitHub authentication to create a GitHub webhook action. If you're signed in via Google the **Add** button in step 6 below will be inactive. ::: To create a new action, select the **Actions** tab and select **Add Action**. 1. Enter a **Name** for your action. 1. Select **GitHub webhook** as the **Event source**. 1. Select the **Compute environment** where the pipeline will be executed. 1. Select the **Pipeline to launch** and (optionally) the **Revision number**. 1. Enter the **Work directory**, the **Config profiles**, and the **Pipeline parameters**. 1. Select **Add**. The pipeline action is now set up. When a new commit occurs for the selected repository and revision, an event is triggered and the pipeline is launched. Workspace maintainers can edit pipeline actions. Select **Edit** from the options menu to the right of the action on the **Actions** list to load the action details. Select **Update** to save the updated pipeline action. :::note Workspace maintainers can edit the names of existing pipeline actions from the **Edit Action** page. ::: ### Tower launch hooks A **Tower launch hook** creates a custom endpoint URL which can be used to trigger the execution of your pipeline programmatically from a script or web service. To create a new action, select the **Actions** tab and select **Add Action**. 1. Enter a **Name** for your action. 1. Select **Tower launch hook** as the event source. 1. Select the **Compute environment** to execute your pipeline. 1. Enter the **Pipeline to launch** and (optionally) the **Revision number**. 1. Enter the **Work directory**, the **Config profiles**, and the **Pipeline parameters**. 1. Select **Add**. The pipeline action is now set up and the new endpoint can be used to launch the corresponding pipeline programmatically. When you create a **Tower launch hook**, you also create an **access token** for launching pipelines. Access tokens can be managed on the [tokens page](https://cloud.seqera.io/tokens), which is also accessible from the user menu. --- ## Pipeline optimization(Pipeline-optimization) Pipeline optimization takes the resource usage information from previous workflow runs to optimize subsequent runs. When a run completes successfully, an _optimized profile_ is created. This profile consists of Nextflow configuration settings for each process and each resource directive (where applicable): `cpus`, `memory`, and `time`. The optimized setting for a given process and resource directive is based on the maximum use of that resource across all tasks in that process. :::caution Due to the variability of production pipeline data inputs, optimization results may vary per run. The optimization profile can be updated or removed from your pipeline if you experience unexpected results. Contact [support](https://support.seqera.io) for further assistance. ::: ## Optimize a pipeline On the **Launchpad**, each pipeline that can be optimized shows a lightbulb icon. Any pipeline with at least one successful run can be optimized. 1. Select the lightbulb icon to open the **Customize optimization profile** menu. 2. Under the **Optimization profile** tab, select a previous run from the drop-down. The list contains all successful runs. 3. Select which **Targets** to optimize. 4. Enable **Retry with dynamic resources** for failed tasks to be retried with increased resources. This option is useful if an optimized setting is too low and causes a task to fail. 5. Select the **Optimized configuration** tab to preview your configuration. 6. Select **Save** to save the optimized configuration and enable it for the pipeline. All subsequent launches of the pipeline will use the optimized configuration. You can also toggle the optimized profile from the pipeline detail page. ### Verify the optimized configuration You can verify the optimized configuration of a given run by inspecting the resource usage plots for that run and these fields in the run's task table: - CPU usage: `pcpu` - Memory usage: `peakRss` - Runtime: `start` and `complete` ### Override the optimized configuration While the optimized configuration is applied after the base configuration of the pipeline, it can be overridden by the **Nextflow config file** text box. Ensure there are no conflicting settings in this text box, unless you explicitly want to override some optimization settings. ### Handle large variations in resource usage Each optimized profile is calibrated to a specific run, so it can only be used safely for "similar" runs. Whether a new run is "similar" is subjective, but in general, an optimized profile should only be used for runs that use the same [**compute environment**](../compute-envs/overview) and have similar task-level resource requirements. However, it's common for a pipeline to process input files that vary widely in size. In this case, the task-level resource requirements may vary widely for a given process, and the optimized profile may not be accurate or efficient. The best way to handle this variation is to create multiple optimized profiles for specific ranges of input sizes. Here is an example strategy: 1. Separate your input files into "bins" based on their size, e.g., _small_, _medium_, and _large_. Duplicate your pipeline in the **Launchpad** for each bin. 2. For each bin, run the pipeline with a few representative samples from that bin. When the run completes, Seqera automatically creates an optimized profile for it. 3. Configure and enable the optimized profile for each pipeline. You now have multiple optimized profiles to handle a variety of input sizes. Although this example uses three bins, you can use as many or as few bins as you need to handle the variation of your input data. --- ## Pipeline schema Pipeline schema files describe the structure and validation constraints of your workflow parameters. They are used to validate parameters before launch to prevent software or pipelines from failing in unexpected ways at runtime. You can populate the parameters in the pipeline by uploading a YAML or JSON file, or in the Seqera Platform interface. The platform uses your pipeline schema to build a bespoke launchpad parameters form. See [nf-core/rnaseq](https://github.com/nf-core/rnaseq/blob/e049f51f0214b2aef7624b9dd496a404a7c34d14/nextflow_schema.json) as an example of the pipeline parameters that can be represented by a JSON schema file. ### Building pipeline schema files The pipeline schema is based on [json-schema.org](https://json-schema.org/) syntax, with some additional conventions. While you can create your pipeline schema manually, we highly recommend using [nf-core tools](https://nf-co.re/tools#json-schema-graphical-interface), a toolset for developing Nextflow pipelines built by the nf-core community. When you run the `nf-core schema build` command in your pipeline root directory, the tool collects your pipeline parameters and gives you interactive prompts about missing or unexpected parameters. If no existing schema file is found, the tool creates one for you. The `schema build` commands include the option to validate and lint your schema file according to best practice guidelines from the nf-core community. :::note The nf-core community creates the schema builder but it can be used with any Nextflow pipeline. ::: ### Customize pipeline schema When the skeleton pipeline schema file has been built with `nf-core schema build`, the command line tool will prompt you to open a [graphical schema editor](https://nf-co.re/pipeline_schema_builder) on the nf-core website. ![nf-core schema builder interface](./_images/pipeline_schema_overview.png) Leave the command line tool running in the background as it checks the status of your schema on the website. When you select **Finished** on the schema editor page, your changes are saved to the schema file locally. :::note Your pipeline schema contains a `mimetype` field that specifies the accepted file type for input [datasets](../data/datasets). When you launch a pipeline from the [Launchpad](../launch/launchpad), the input field drop-down will only show datasets that match the required file type (either `text/csv` or `text/tsv`). ::: --- ## Overview(Pipelines) Seqera Platform provides version-controlled, access-controlled, reproducible execution of Nextflow pipelines. When you add a pipeline to Seqera, you define: - The pipeline Git repository and [revision](./revision.md) (branch, tag, or commit) - [Compute environment](../compute-envs/overview.md) for execution - Pipeline parameters and [configuration profiles](https://docs.seqera.io/nextflow/config#config-profiles) - (Optional) [Labels](../labels/overview.md), [resource labels](../resource-labels/overview.md), and [secrets](../secrets/overview.md) - (Optional) [Pre-run and post-run](../launch/advanced.md#pre-and-post-run-scripts) bash scripts that execute in your compute environment ### Manage pipelines - [Add pipelines](../getting-started/quickstart-demo/add-pipelines.md) - [Edit pipelines](../launch/launchpad.md#edit-pipeline) - [Launch pipelines](../launch/launchpad.md) ### Key features #### Pipeline revision management Workflow repositories change over time as code is updated. Seqera provides [revision management](./revision.md) features, such as **commit ID pinning** to ensure reproducible execution by locking pipelines to specific Git commits, and **Pull latest** controls to instruct Nextflow to fetch the most recent commit at execution time. #### Pipeline versioning Seqera's [pipeline versioning system](./versioning.md) automatically tracks pipeline configuration changes as draft versions, creating an immutable audit trail of your pipeline evolution. Publish drafts to make important configurations easy to identify, share, and promote across your team. Version checksums provide cryptographic verification that workflow runs match their associated pipeline configurations. --- ## Git revision management Workflow repositories are mutable - branches can be updated, tags can be moved (though rarely), and the "latest" code changes over time. This creates a reproducibility challenge: launching the same pipeline configuration at different times could execute different workflow code. **Commit ID pinning** solves this by tracking the specific Git commit ID alongside the branch or tag revision. When you pin a commit ID, Seqera ensures that exact version of the workflow code is executed for every launch, regardless of future changes to the repository branch or tag. :::info Commit ID pinning requires a valid pipeline and **Revision** (tag or branch name) to be specified. The **Commit ID** field and pin icon is disabled if the **Revision** field is left empty. ::: The **Pull latest** toggle controls whether Nextflow fetches the most recent HEAD commit of the pipeline revision at execution time. This is equivalent to the `nextflow run -latest` flag. If **Pull latest** is **disabled** in HPC compute environments, the Nextflow cache is used (if available). Cloud compute environments always pull the latest HEAD commit of the revision at execution time, unless a specific commit ID revision is set or pinned. Enabling **Pull latest** unpins any pinned commit ID. ### Pin commit ID versus Pull latest behavior The **Commit ID** and **Pull latest** fields appear on pipeline add, edit, and launch forms. Their interaction and behavior depend on compute environment type: **Cloud compute environments** | Revision | Commit ID | Pull latest | Launch behavior | |----------|-----------|-------------|-----------------| | Branch/tag | Empty (unpinned) - default | OFF - default | Fetches current HEAD commit at execution time (non-deterministic). | | Branch/tag | Pinned | OFF - automatically set when pinned | Uses the pinned commit ID for deterministic execution. | | Branch/tag | Empty (unpinned) | ON | Fetches current HEAD commit at execution time (non-deterministic). Equivalent to `nextflow run -latest`. | | Commit ID | Automatically populated and pinned | OFF - default | Uses the specified commit ID (deterministic by definition). | **HPC compute environments** | Revision | Commit ID | Pull latest | Launch behavior | |----------|-----------|-------------|-------------------| | Branch/tag | Empty (unpinned) - default | OFF - default | Runs locally cached pipeline version. No update or network fetch is performed. | | Branch/tag | Pinned | OFF - automatically set when pinned | Uses the pinned commit ID for deterministic execution. | | Branch/tag | Empty (unpinned) | ON | Fetches and caches current HEAD commit before execution (non-deterministic). Equivalent to `nextflow run -latest`. | | Commit ID | Automatically populated and pinned | OFF - default | Uses the specified commit ID (deterministic by definition). | This relationship ensures commit ID pinning provides deterministic execution across both Cloud and HPC environments. Once pinned, the same commit ID is used for each launch, regardless of compute environment type. :::note If you enter a commit ID in the **Revision** field, the **Commit ID** field, pin icon, and **Pull latest** toggle are disabled. ::: --- ## Pipeline versioning Seqera's pipeline versioning system captures configuration changes as new draft versions of the pipeline, ensuring configuration traceability and execution reproducibility. Users with [Maintain or higher](../orgs-and-teams/roles.md) permissions can edit and publish draft versions, creating published versions that teams can reference and launch consistently. :::tip For deterministic and reproducible pipeline execution, use [commit ID pinning](revision.md) for published pipeline versions. This ensures the same workflow code is used across all launches of that version. ::: When you add a new pipeline to Seqera, the first default version of that pipeline is automatically published. New draft versions are automatically generated during pipeline edit or launch when you modify the following: - All pipeline schema parameters, unless the `track_changes` schema configuration for a given property is set to `false`. :::info Changes to all pipeline schema parameters during pipeline edit or launch trigger a new version by default i.e. the default for parameters is assumed as `"track_changes": true`. The intent with pipeline versioning is to allow the common variable inputs (e.g. fastq files) and outputs (e.g. outputDir) to be omitted for consideration during versioning. To enable this behavior for specific parameters, add `"track_changes": false` to the parameter property definition in the schema: ```json "track_changes": false } ``` For nested parameters, `track_changes` is supported at the leaf node level: ```json "nestedParam": { "type": "object", "properties": { "leafParam": { "type": "string", "track_changes": false } } } ``` ::: - Fields in the pipeline **Edit** form, excluding: - **Name** - **Image** - **Description** - **Labels** - **Resource labels** - Pipeline schema selection (see [Building pipeline schema files](../pipeline-schema/overview.md#building-pipeline-schema-files)) Published versions provide a stable reference for team-wide pipeline launches. Users with Maintain or higher permissions can publish a draft version, giving it a name and optionally setting it as the default version. This makes important configurations easy to identify, share, and promote across your team. :::info A pipeline's default version is shown in the Launchpad and automatically selected during launch. ::: Seqera maintains a history of all draft and published versions, providing an audit trail of pipeline evolution. #### Seqera Platform schema Users with [Maintain or higher](../orgs-and-teams/roles.md) permissions can upload a `nextflow_schema.json` file to Seqera Platform to control which pipeline parameters appear in the launch form. Changes to the Seqera Platform schema trigger a new draft version of the pipeline. For more information, see [Building pipeline schema files](../pipeline-schema/overview.md#building-pipeline-schema-files). ### Manage pipeline versions ![](./_images/pipeline-version-detail.jpg) Select a pipeline from the workspace Launchpad to open the pipeline's details page. From here, users with Maintain or higher permissions can: - **View version history**: See a chronological list of all draft and published versions with creator, date, and hash. - Use the drop-down next to **Show:** to show all versions, or filter by draft or published versions. - **Search** for specific version names (freetext search), or use keywords to search by `versionId:`, `versionName:`, or `versionHash:` ([version hash](#version-hash)). - **Manage draft versions**: - Select **Publish** from the options menu of a draft version to name this version and optionally make it the default version to launch from the Launchpad. :::note Draft versions created from workflow runs can only be published from the pipeline's original workspace. For shared pipelines, the **Publish** action is only available in the workspace where the pipeline was created. ::: - Select **Edit** to open the pipeline edit form and either save a new draft or publish the current draft version. - **Manage published versions**: - Select **Make default** from the options menu of a published version to use this version for every pipeline launch. - Select **Edit** to open the pipeline edit form and either save a new draft or update the current published version. - Select **Unpublish** to turn this version back into a draft. Draft versions are still visible to launch users. Individual versions cannot be deleted. This ensures that the pipeline configuration audit trail is immutable. However, published versions can be unpublished or have their names reassigned to different versions. :::note Changes made at launch time in a target workspace cannot be saved. Changes to versions can only be saved and published from the pipeline's original workspace. ::: #### Pipeline optimization [Pipeline optimization](../pipeline-optimization/overview) is available directly from the pipeline details page for the default version. Users with [Maintain or higher](../orgs-and-teams/roles.md) permissions can: - **Optimize pipeline**: Configure pipeline optimization settings for the default version from the **Default** section or the **Edit pipeline** form. - **Toggle optimization**: Enable or disable optimization for a pipeline that has already been optimized. - **Customize profile**: Modify the optimization profile settings when optimization is enabled. To optimize specific non-default versions, use the **Edit** page for that version. Pipeline optimization settings apply per version and remain configured when you set a different version as the default. #### Version hash Seqera calculates a hash for each draft version based on its version-triggering parameters. This provides: - **Provenance tracking** for audit and compliance requirements. - **Cryptographic verification** that a workflow run's configuration matches its associated pipeline version. --- ## Seqera Platform Enterprise Seqera Platform Enterprise is a centralized environment that makes scientific analysis accessible at any scale. Run pipelines, work interactively in managed analysis environments, manage data, and collaborate across teams using your own compute resources and infrastructure. Seqera helps organizations: - **Run pipelines**: Launch, manage, and monitor [Nextflow](https://www.nextflow.io) pipelines on cloud or HPC compute, with a [Launchpad](/platform-enterprise/launch/launchpad) interface for non-technical users. - **Analyze interactively**: Spin up [Studios](/platform-enterprise/studios/overview) with JupyterLab, R-IDE, VS Code, or Xpra remote desktops on a connected compute environment. - **Manage data**: Browse data across AWS, Azure, and Google Cloud buckets with [Data Explorer](/platform-enterprise/data/data-explorer), and trace pipeline provenance with [Data Lineage](/platform-enterprise/data/data-lineage) (public preview). - **Optimize cost and performance**: Get automated resource recommendations from [pipeline optimization](/platform-enterprise/pipeline-optimization/overview). - **Work with AI**: Use [Co-Scientist](/platform-enterprise/co-scientist/) and MCP-compatible agents to write, debug, and run pipelines. - **Collaborate securely**: Share pipelines, data, and compute across [organizations and teams](/platform-enterprise/orgs-and-teams/workspace-management). - **Access curated pipelines**: Run production-tested [community pipelines](https://seqera.io/pipelines/) from [nf-core](https://nf-co.re/) and others. - **Automate workflows**: [Automate](/platform-enterprise/getting-started/quickstart-demo/automation) launches as part of larger enterprise processes. :::tip Request a [**demo**](https://seqera.io/demo "Seqera Enterprise Demo") to explore using Seqera Enterprise in your own on-premises or cloud environment. ::: --- ## Reports Most Nextflow pipelines will generate reports or output files which are useful to inspect at the end of the pipeline execution. Reports may be in various formats (e.g. HTML, PDF, TXT) and would typically contain quality control (QC) metrics that would be important to assess the integrity of the results. **Reports** allow you to directly visualize supported file types or to download them via the user interface (see [Limitations](#limitations)). This saves users the time and effort of having to retrieve and visualize output files from their local storage. ### Visualize reports Available reports are listed in a **Reports** tab on the **Runs** page. You can select a report from the table to view or download it (see [Limitations](#limitations) for supported file types and sizes). To open a report preview, the file must be smaller than 10 MB. You can download a report directly or from the provided file path. Reports larger than 25MB cannot be downloaded directly — the option to download from file path is given instead. ### Configure reports Create a config file that defines the paths to a selection of output files published by the pipeline for Seqera to render reports. There are 2 ways to provide the config file, both of which have to be in YAML format: 1. **Pipeline repository**: If a file called `tower.yml` exists in the root of the pipeline repository then this will be fetched automatically before the pipeline execution. 2. **Seqera Platform interface**: Provide the YAML definition within the **Advanced options > Seqera Cloud config file** box when: - Creating a pipeline in the Launchpad. - Amending the launch settings during pipeline launch. This is available to users with the **Maintain** role only. :::caution Any configuration provided in the interface will override configuration supplied in the pipeline repository. ::: ### Configure reports for Nextflow CLI runs The reports and log files for pipeline runs launched with Nextflow CLI (`nextflow run -with-tower`) can be accessed directly in the Seqera UI. The files generated by the run must be accessible to your Seqera workspace primary compute environment. Specify your workspace prior to launch by setting the `TOWER_WORKSPACE_ID` environment variable. Reports are listed under the **Reports** tab on the run details page. Execution logs are available in the **Logs** tab by default, provided the output files are accessible to your workspace primary compute environment. To specify additional report files to be made available, your pipeline repository root folder must include a `tower.yml` file that specifies the files to be included (see below). ### Reports implementation Pipeline reports need to be specified using YAML syntax: ```yaml reports: : display: text to display (required) mimeType: file mime type (optional) ``` ### Path pattern Only the published files (using the Nextflow `publishDir` directive) are candidate files for Seqera reports. The path pattern is used to match published files to a report entry. It can be a partial path, a glob expression, or just a file name. Examples of valid path patterns are: - `multiqc.html`: This will match all the published files with this name. - `**/multiqc.html`: This is a glob expression that matches any subfolder. It's equivalent to the previous expression. - `results/output.txt`: This will match all the `output.txt` files inside any `results` folder. - `*_output.tsv`: This will match any file that ends with `\_output.tsv`. :::caution To use `*` in your path pattern, you must wrap the pattern in double quotes for valid YAML syntax. ::: ### Display Display defines the title that will be shown on the website. If there are multiple files that match the same pattern, a suffix will be added automatically. The suffix is the minimum difference between all the matching paths. For example, given this report definition: ```yaml reports: "**/out/sheet.tsv": display: "Data sheet" ``` For paths `/workdir/sample1/out/sheet.tsv` and `/workdir/sample2/out/sheet.tsv`, both match the path pattern. The final display name will for these paths will be _Data sheet (sample1)_ and _Data sheet (sample2)_. ### MIME type By default, the MIME type is deduced from the file extension, so you don't need to explicitly define it. Optionally, you can define it to force a viewer, for example showing a `txt` file as a `tsv`. It is important that it is a valid MIME-type text, otherwise it will be ignored and the extension will be used instead. ### Built-in reports Nextflow can generate a number of built-in reports: - [Execution report](https://docs.seqera.io/nextflow/reports#execution-report) - [Execution timeline](https://docs.seqera.io/nextflow/reports#timeline-report) - [Trace file](https://docs.seqera.io/nextflow/reports#trace-report) - [Workflow diagram](https://docs.seqera.io/nextflow/reports#dag-visualisation) (i.e. DAG) In Nextflow version 24.03.0-edge and later, these reports can be included as pipeline reports in Seqera Platform. Specify them in `tower.yml` like any other file: ```yaml reports: "report.html": display: "Nextflow execution report" "timeline.html": display: "Nextflow execution timeline" "trace.txt": display: "Nextflow trace file" "dag.html": display: "Nextflow workflow diagram" ``` :::note The filenames must match any custom filenames defined in the Nextflow config: - Execution report: `report.file` - Execution timeline: `timeline.file` - Trace file: `trace.file` - Workflow diagram: `dag.file` ::: ### Limitations The current reports implementation limits rendering to the following formats: `HTML`, `csv`, `tsv`, `pdf`, and `txt`. In-page rendering/report preview is restricted to files smaller than 10 MB. Larger files need to be downloaded first. The download is restricted to files smaller than 25 MB. Files larger than 25 MB need to be downloaded from the path. YAML formatting validation checks both the `tower.yml` file inside the repository and the UI configuration box. The validation phase will produce an error message if you try to launch a pipeline with non-compliant YAML definitions. --- ## Resource labels Platform supports resource labels in compute environments, pipelines, actions, runs, and Studios. This provides a flexible tagging system for annotating and tracking the cloud resources consumed by a run or Studio. Resource labels are sent to the cloud service provider in `key=value` format. Resource labels enable: - Cloud resource attribution across projects and teams - Granular cloud cost tracking - Resource organization and management - Compliance and governance enforcement ## How resource labels work Resource labels can be applied to compute environments, pipelines, actions, runs, and Studios. Resource labels are propagated to cloud resources during: - Compute environment creation - Workflow submission - Workflow execution - The start of a Studio's first session :::info Seqera applies resource labels to cloud resources in one direction only. Any tags changed or deleted directly in your cloud environment will not be reflected in Seqera. ::: :::note Resource labels are normally created and managed in Seqera at the workspace, compute environment, pipeline, action, run, and Studio levels. Advanced users can also define resource labels directly in Nextflow configuration using the [`resourceLabels`](https://docs.seqera.io/nextflow/reference/process#resourcelabels) process directive, set per process or globally with `process.resourceLabels`. Labels defined this way are applied by Nextflow at task submission and execution time. ::: ### Resource labels applied to compute environments Resource labels can be applied to all cloud compute environments. Cloud resources are tagged when a pipeline run is launched or a Studio is started with those resource labels applied. :::info If a compute environment is created with Batch Forge, it propagates resource labels to all cloud resources during the compute environment creation process. See [AWS](#aws) for the list of resources tagged during Batch Forge creation time. ::: ### Resource labels applied to a pipeline run A run inherits resource labels applied at the compute environment, pipeline, and action level. Resource labels can also be added or overridden during pipeline launch. When a run is executed with resource labels attached: - Seqera propagates the labels to the set of resources [listed for each provider](#resource-label-propagation-to-cloud-environments). - Nextflow distributes the labels for the resources spawned at runtime. ### Resource labels applied to a Studio A Studio inherits resource labels applied at the compute environment level. Resource labels can also be added or overridden when you add a Studio. When a Studio starts with resource labels attached: - Seqera propagates the labels to the set of resources [listed for each provider](#resource-label-propagation-to-cloud-environments). ## Prerequisites and limitations - Resource labels are only available for cloud environments that use a resource tagging system. AWS, Azure, Google, and Kubernetes are supported. HPC compute environments do not support resource labels. - Cloud provider credentials must have the appropriate roles or permissions to tag resources in your environment. - You can't assign multiple resource labels, using the same key, to the same resource, regardless of whether this option is supported by the destination cloud provider. ## Create resource labels **Workspace-level resource labels**: Create resource labels at the workspace level for consistent use across compute environments, pipelines, actions, runs, and Studios: 1. In your workspace, select **Settings** > **Edit labels**. 1. Select **Add label**. 1. Under **Type**, select **Resource label**. 1. Enter a **Name** such as `owner`, `team`, or `platform-run`. 1. Enter a **Value**: - **Standard resource labels**: ``, `TEAM_NAME` - **[Dynamic resource labels](#dynamic-resource-labels)**: Use variable syntax — `${sessionId}`, `${userName}`, or `${workflowId}` 1. Optionally, enable **Use as default in compute environment form** to automatically apply this resource label to all new compute environments in this workspace. 1. Select **Save**. **Create resource labels during compute environment, pipeline, action, run, and Studio creation**: Resource labels can also be created and added to new Platform entities on the fly. The deletion of a resource label from a workspace has no influence on the cloud environment. :::info All users can add resource labels, but only maintainers (or higher) can edit or delete them, provided they're not already associated with **any** resource. ::: ## Apply resource labels Once created at the workspace level, resource labels can be applied to: - **Compute environments**: In the **Resource labels** field when creating a new compute environment. Once the compute environment has been created, its resource labels cannot be edited. - **Pipelines**: In the **Resource labels** field when adding or editing a pipeline. - **Actions**: In the **Resource labels** field when creating or editing an action. - **Pipeline runs**: In the **Resource labels** field when launching a pipeline. - **Studios**: In the **Resource labels** field when adding a Studio. Resource labels from the compute environment or pipeline are prefilled in the pipeline launch form, and compute environment resource labels are prefilled in the Studio add form. You can apply or override these labels when you launch a pipeline or add a Studio. Workspace maintainers can override default resource labels inherited from the compute environment when they create or edit pipelines, actions, runs, and Studios. Custom resource labels associated with each element propagate to resources in your cloud provider account. They don't alter the default resource labels on the compute environment. When you add or edit resource labels associated with a pipeline, action, run, or Studio, the **submission and execution time** resource labels are altered. This does not affect the resource labels for resources spawned at compute environment **creation time**. For example, the resource label `name=ce1` is set during AWS Batch compute environment creation. If you create the resource label `pipeline=pipeline1` while launching a pipeline with the same AWS Batch compute environment, the EC2 instances associated with that compute environment will still contain only the `name=ce1` label. Job Definitions associated with the pipeline run will inherit the `pipeline=pipeline1` resource label. If a maintainer changes the compute environment associated with a pipeline, the **Resource labels** field is updated with the resource labels from the new compute environment. ## Dynamic resource labels Dynamic resource labels extend the standard resource labels functionality by allowing variable values that are populated with unique workflow identifiers at runtime. This enables precise cost tracking and resource attribution for individual pipeline runs across cloud compute environments. Standard resource labels use static key-value pairs, such as `project=research` or `environment=production`. Dynamic resource labels use variable placeholders. Seqera and Nextflow resolve these placeholders when a workflow runs: | Value | Description | |-----------------|---------------------| | `${workflowId}` | Platform run ID | | `${sessionId}` | Nextflow session ID | | `${userName}` | Platform username (run launch user) | For example, a dynamic resource label `platformRun=${workflowId}` becomes `platformRun=12345abcde` when applied to the cloud resources consumed by run `12345abcde`. Additional dynamic values, such as the user or team that launched a run, will be supported in a future release. :::info **Dynamic resource labels** tag resources with unique values for each pipeline run. Nextflow applies these labels at workflow submission and execution time, not during compute environment creation. See the **Submission time** and **Execution time** resources listed for each cloud provider in the [Resource label propagation](#resource-label-propagation-to-cloud-environments) section. ::: ### Benefits of dynamic resource labels Dynamic resource labels provide several key advantages: - **Granular cost tracking**: Associate cloud costs with specific workflow runs rather than entire compute environments or projects. - **Automated attribution**: Apply resource labels automatically at execution time - no manual tagging of individual runs. - **Enhanced reporting**: Filter and group costs by individual workflow runs in your cloud provider's cost management tools. - **Audit trails**: Track resource usage patterns for specific workflows over time. ## Search and filter with resource labels Search and filter pipelines on the Launchpad, and runs on the **Runs** tab, using one or more resource labels. The resource label search uses a `label:key=value` format. ## Resource label propagation to cloud environments ### AWS The following resources are tagged using the resource labels associated with the compute environment (either [Batch](../compute-envs/aws-batch.md) or [Cloud](../compute-envs/aws-cloud.md)): **Batch**: - **Batch Forge creation time** - FSX Filesystems (does not cascade to files) - EFS Filesystems (does not cascade to files) - Batch Compute Environment - Batch Queue(s) - ComputeResource (EC2 instances, including EBS volumes) - Service role - Spot Fleet role - Execution role - Instance Profile role - Launch template - **Submission time** - Jobs and Job Definitions - Tasks (via the `propagateTags` parameter on Job Definitions) - **Execution time** - Work Tasks (via the `propagateTags` parameter on Job Definitions) **Cloud**: - **Submission and execution time** - ComputeResource (EC2 instances, including EBS volumes) At execution time, when jobs are submitted to Batch, the requests are set up to propagate tags to all the instances and volumes created by the head job. :::caution Only compute environments and their associated queues **created by Batch Forge** are tagged with your resource labels automatically. AWS Batch compute environments, job queues, or other resources you create **manually outside of Seqera** don't inherit these tags, so their costs aren't attributable in AWS Cost Explorer or your data exports until you tag them yourself. If you run a mix of Forge-created and manually created queues, add the relevant cost-allocation tag (for example, `project=`) to the manually created resources in the AWS console. ::: The [IAM permissions](../compute-envs/aws-batch.md#required-platform-iam-permissions) contain the roles needed for Batch Forge-created AWS Batch compute environments to tag AWS resources. Specifically, the required roles are `iam:TagRole`, `iam:TagInstanceProfile`, and `batch:TagResource`. #### Verify resource label propagation to AWS Resource labels applied in Seqera surface as AWS tags with the same `key=value` on the resources listed above. For example, a resource label `project=rnaseq` on a Batch Forge compute environment is applied as the AWS tag `project=rnaseq` on the Batch compute environment, job queues, and EC2 instances at creation time, and on the jobs and job definitions submitted for each run. A dynamic resource label such as `platformRun=${workflowId}` is applied as a tag like `platformRun=12345abcde` on the jobs and job definitions spawned by that run. To view, manage, and verify the resource labels applied to AWS resources by Seqera and Nextflow, go to the [AWS Tag Editor](https://docs.aws.amazon.com/tag-editor/latest/userguide/find-resources-to-tag.html) (as an administrative user) and follow these steps: 1. Under **Find resources to tag**, search for the resource label key and value in the relevant search fields under **Tags**. Your search can be further refined by AWS region and resource type. 1. Select **Search resources**. **Resource search results** display all the resources tagged with your given resource label key and/or value. ### Include Seqera resource labels in AWS billing reports To include the cost information associated with your resource labels in your AWS billing reports, you need to activate cost allocation tags. The method for viewing costs differs between static and dynamic resource labels: :::tip Resource labels combined with your cloud provider's native cost tools are the recommended way to achieve full cost accounting — including compute, storage, and networking — for your pipeline runs. Avoid custom wrapper scripts that dedicate an entire EC2 instance to a single job to attribute cost: this pattern is incompatible with AWS Batch's shared-instance scheduling model and typically increases cost. Tag your resources with resource labels and report on them in AWS Cost Explorer or your data exports instead. ::: **For static resource labels**: Because static resource labels have fixed values at compute environment creation time or workflow submission time, they are applied to static resources including Batch compute environments and EC2 instances. Static resource label costs can be viewed in AWS Cost Explorer, [Data Exports](https://docs.aws.amazon.com/cur/latest/userguide/what-is-data-exports.html), and QuickSight dashboards. **For dynamic resource labels**: Dynamic resource labels are only propagated at workflow submission and execution time. This means only jobs and job definitions (for AWS Batch compute environments), and EC2 instances (for AWS Cloud compute environments) spawned at runtime are tagged with the unique workflow identifiers. You must [enable split cost allocation data](https://docs.aws.amazon.com/cur/latest/userguide/enabling-split-cost-allocation-data.html) and view costs in [AWS Data Exports](https://docs.aws.amazon.com/cur/latest/userguide/what-is-data-exports.html) and Cost and Usage Reports (CUR). Dynamic resource label costs are not visible in AWS Cost Explorer, which does not support split cost allocation data. **Steps to activate cost allocation tags**: 1. **Wait for tag creation**: After creating resources with resource labels, wait up to 24 hours for the tag keys to appear in your cost allocation tags page 2. **Activate cost allocation tags**: [Activate](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html) the associated tags in the **AWS Billing and Cost Management console**. Newly-applied tags may take up to 24 hours to appear on your cost allocation tags page. - In the navigation pane, choose **Cost allocation tags** - Select the tag keys you want to activate - Choose **Activate** - Allow up to 24 hours for tags to activate 3. **For static resource labels - View in Cost Explorer or Data Exports**: - Navigate to AWS Cost Explorer and use **Group by** filters to organize costs by your activated tag keys - Create [cost allocation reports](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/configurecostallocreport.html#allocation-viewing) including your resource label tags - Alternatively, view in Data Exports and QuickSight dashboards for more detailed analysis 4. **For dynamic resource labels - Enable split cost allocation and view in Data Exports**: - [Enable split cost allocation data](https://docs.aws.amazon.com/cur/latest/userguide/enabling-split-cost-allocation-data.html) in your Cost and Usage Reports preferences - View costs in your [Data Exports](https://docs.aws.amazon.com/cur/latest/userguide/what-is-data-exports.html) and Cost and Usage Reports (CUR) - Query reports using Amazon Athena or visualize in Amazon QuickSight dashboards (requires a QuickSight subscription) - For a complete walkthrough, see our [guide to AWS cost tracking with resource labels](https://seqera.io/blog/aws-labels-cost-tracking/) #### Verify cost data in your AWS billing reports After you activate cost-allocation tags, cost data for your labeled resources typically appears in Cost Explorer and your data exports (CUR/Parquet) only after a **24–48 hour delay**. To confirm that your labels and their costs landed, inspect the data export directly — for example, query the Parquet files with Amazon Athena, or download and open them — and check that your resource-label tag keys are present and associated with non-zero costs. :::caution AWS Cost and Usage Reports normalize tag characters. In CUR (version 2), colons (`:`) are rewritten as underscores (`_`), and mixed- or upper-case characters are lowercased and separated with underscores. For example, a tag key `costCenter` can appear as `cost_center`, and `team:genomics` as `team_genomics`, in the export. Design your resource-label keys and values so they remain unambiguous after this normalization, and account for it in downstream Athena or QuickSight queries. ::: #### AWS limitations - Resource label keys and values must contain a minimum of 2 and a maximum of 39 alphanumeric characters (each), separated by dashes or underscores. - The key and value cannot begin or end with dashes `-` or underscores `_`. - The key and value cannot contain a consecutive combination of `-` or `_` characters (`--`, `__`, `-_`, etc.) - A maximum of 25 resource labels can be applied to each resource. - A maximum of 1000 resource labels can be used in each workspace. - Keys and values cannot start with `aws` or `user`, as these are reserved prefixes appended to tags by AWS. - Keys and values are case-sensitive in AWS. See [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions) for more information on AWS resource tagging. ### Google Cloud The following resources are tagged using the labels associated with the compute environment (either [Batch](../compute-envs/google-cloud-batch.md) or [Cloud](../compute-envs/google-cloud.md)): **Submission time** - Job (Batch) **Execution time** - AllocationPolicy (Batch) - VirtualMachine (Cloud) #### View costs by resource labels in Google Cloud Google Cloud includes resource labels in billing data for cost analysis and reporting: 1. **Access Billing Console**: Go to [Google Cloud Billing](https://console.cloud.google.com/billing) and navigate to **Reports** in the Cost management section. 2. **Configure Reports**: Use the **Labels** filter to select specific label keys and set **Group by** to organize costs by your label values. 3. **Export for Analysis**: - [Enable Cloud Billing export to BigQuery](https://cloud.google.com/billing/docs/how-to/export-data-bigquery) for detailed analysis and custom reporting. - Use tools like [Looker Studio](https://cloud.google.com/looker-studio) to visualize your labeled cost data. #### Google Cloud limitations - Resource label keys and values must contain a minimum of 2 and a maximum of 39 alphanumeric characters (each), separated by dashes or underscores. - The key and value cannot begin or end with dashes `-` or underscores `_`. - The key and value cannot contain a consecutive combination of `-` or `_` characters (`--`, `__`, `-_`, etc.) - A maximum of 25 resource labels can be applied to each resource. - A maximum of 1000 resource labels can be used in each workspace. - Keys and values in Google Cloud Resource Manager may contain **only lowercase letters**. Resource labels created with uppercase characters are **automatically converted to lowercase** in Platform before being propagated to Google Cloud. See [here](https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements) for more information on Google Cloud Resource Manager labeling. ### Azure The system used for labeling resources in Azure differs depending on your compute environment type: - In an **Azure Batch** compute environment created with Batch Forge, resource labels are added to the Pool parameters — this adds set of `key=value` **metadata** pairs to the Azure Batch Pool. - In an **Azure Cloud** (single instance) compute environment, resource labels are propagated to VMs and related resources as **tags**. :::warning In Azure Batch compute environments, the [Azure Batch node pool](https://learn.microsoft.com/en-us/azure/batch/nodes-and-pools) is managed by the compute environment and **resource labels are fixed at the time of creation**. ::: #### View costs by resource labels in Azure Azure supports cost analysis by tags. However, you must configure tag inheritance and cost allocation. :::note Dynamic resource labels create tags in the form of metadata pairs on Azure Batch resources. However, Azure's cost reporting integration has some limitations. Azure tags may not always appear immediately in **Cost Management**. ::: **Prerequisites**: Billing profile contributor/owner permissions for billing profile tags, and Contributor role or Tag Contributor role for resource tagging. **Steps to enable cost tracking**: 1. **Enable Tag Inheritance** (recommended): Navigate to Cost Management in the Azure portal, select a billing account or subscription scope, and under **Settings** > **Configuration** > **Tag inheritance**, enable **Automatically apply subscription and resource group tags to new data**. See [Azure tag inheritance documentation](https://docs.microsoft.com/en-us/azure/cost-management-billing/costs/enable-tag-inheritance) for detailed steps. 2. **View Tagged Costs**: Navigate to **Cost Management + Billing** > **Cost Management** > **Cost analysis** and select **Group by** for your tag key. 3. **Create Budgets with Tag Filters**: [Create budgets with filters](https://docs.microsoft.com/en-us/azure/cost-management-billing/costs/tutorial-acm-create-budgets) on the inherited tags, available 24 hours after enabling tag inheritance. #### Azure limitations - Resource label keys and values must contain a minimum of 2 and a maximum of 39 alphanumeric characters (each), separated by dashes or underscores. - The key and value cannot begin or end with dashes `-` or underscores `_`. - The key and value cannot contain a consecutive combination of `-` or `_` characters (`--`, `__`, `-_`, etc.) - A maximum of 25 resource labels can be applied to each resource. - A maximum of 1000 resource labels can be used in each workspace. - Keys are case-insensitive, but values are case-sensitive. - Microsoft advises against using a non-English language in your resource labels, as this can lead to decoding progress failure while loading your VM's metadata. Tags are not available for tenant resources not associated with subscriptions, classic resources, or some resource types that don't support tags in usage data. See [here](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/tag-resources?tabs=json) for more information on Azure Resource Manager tagging. ### Kubernetes Both the Head pod and Work pod specs will contain the set of resource labels associated with the compute environment in addition to the standard resource labels applied by Seqera Platform and Nextflow. :::caution Currently, tagging with resource labels is not available for the files created during a workflow execution. The cloud instances are the elements being tagged. ::: The following resources will be tagged using the resource labels associated with the compute environment: **Compute environment creation time** - Deployment - PodTemplate **Submission time** - Head Pod Metadata **Execution time** - Run Pod Metadata #### Kubernetes limits - Resource label keys and values must contain a minimum of 2 and a maximum of 39 alphanumeric characters (each), separated by dashes or underscores. - The key and value cannot begin or end with dashes `-` or underscores `_`. - The key and value cannot contain a consecutive combination of `-` or `_` characters (`--`, `__`, `-_`, etc.) - A maximum of 25 resource labels can be applied to each resource. - A maximum of 1000 resource labels can be used in each workspace. See [Syntax and character set](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) for more information on Kubernetes object labeling. ## Best Practices - **Use descriptive keys**: Choose tag keys that clearly indicate their purpose (e.g., `workflow-id`, `pipeline-run`, `session-id`). - **Plan for cost analysis**: Consider how you'll group and filter costs in your cloud provider's tools when designing your tag schema. - **Combine static and dynamic resource labels**: Use dynamic resource labels alongside static resource labels for comprehensive cost attribution (e.g., static `project=genomics` with dynamic `platformRun=${workflowId}`). - **Monitor tag limits**: Stay within cloud provider tag limits (25 tags per resource for AWS/GCP/Azure). - **Document your schema**: Maintain documentation of your tagging strategy for team members who will analyze costs. ## Troubleshooting See [Resource labels](../troubleshooting_and_faqs/resource-labels.md) for troubleshooting common resource label propagation errors. --- ## Secrets **Secrets** store the keys and tokens used by workflow tasks to interact with external systems, such as a password to connect to an external database or an API token. Seqera Platform relies on third-party secret manager services to maintain security between the workflow execution context and the secret container. This means that no secure data is transmitted from your Seqera instance to the compute environment. :::note AWS, Google Cloud, and HPC compute environments are currently supported. See [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/index.html) and [Google Secret Manager](https://cloud.google.com/secret-manager/docs/overview) for more information. ::: ## Pipeline secrets To create a pipeline secret, go to a workspace (private or shared) and select the **Secrets** tab in the navigation bar. Available secrets are listed here and users with appropriate [permissions](../orgs-and-teams/roles) (maintainer, admin, or owner) can create or update secret values. :::note Multi-line secrets must be base64-encoded. ::: Select **Add Pipeline Secret** and enter a name and value for the secret. Then select **Add**. ## User secrets Listing, creating, and updating secrets for users is the same as secrets in a workspace. You can access user secrets from **Your secrets** in the user menu. :::caution Secrets defined by a user have higher priority and will override any secrets with the same name defined in a workspace. ::: ## Use secrets in workflows When you launch a new workflow, all secrets are sent to the corresponding secrets manager for the compute environment. Nextflow downloads these secrets internally when they're referenced in the pipeline code. See [Nextflow secrets](https://docs.seqera.io/nextflow/secrets) for more information. Secrets are automatically deleted from the secret manager when the pipeline completes, successfully or unsuccessfully. :::note In AWS Batch compute environments, Seqera passes stored secrets to jobs as part of the Seqera-created job definition. Seqera secrets cannot be used in Nextflow processes that use a [custom job definition](https://docs.seqera.io/nextflow/aws#custom-job-definition). ::: ## AWS Secrets Manager integration Seqera and associated AWS Batch IAM Roles require additional permissions to interact with AWS Secrets Manager, as detailed in the [Pipeline secrets section](../compute-envs/aws-batch#pipeline-secrets-optional) of the AWS Batch documentation. ### ECS Agent permissions The ECS Agent uses the [Batch Execution role](https://docs.aws.amazon.com/batch/latest/userguide/execution-IAM-role.html#create-execution-role) to communicate with AWS Secrets Manager. - If your AWS Batch compute environment does not have an assigned execution role, create one. - If your AWS Batch compute environment already has an assigned execution role, augment it. **IAM permissions** 1. Add the [`AmazonECSTaskExecutionRolePolicy` managed policy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonECSTaskExecutionRolePolicy.html). 1. Add this inline policy (specifying ``): ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowECSAgentToRetrieveSecrets", "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager::*:secret:tower-*" } ] } ``` :::note Including `tower-*` in the Resource ARN above limits access to Platform secrets only (as opposed to all secrets in the given region). ::: **IAM trust relationship** ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowECSTaskAssumption", "Effect": "Allow", "Principal": { "Service": "ecs-tasks.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ### Compute permissions The Nextflow head job must communicate with AWS Secrets Manager. Its permissions are inherited either from a custom role assigned during the [AWS Batch CE creation process](../compute-envs/aws-batch#advanced-options), or from its host [EC2 instance](https://docs.aws.amazon.com/batch/latest/userguide/instance_IAM_role.html). Augment your Nextflow head job permissions source with one of the following policies: **EC2 Instance role** Add this policy to your EC2 Instance role: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowNextflowHeadJobToAccessSecrets", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" } ] } ``` **Custom IAM role** Add this policy to your custom IAM role (specifying `YOUR_ACCOUNT` and `YOUR_BATCH_CLUSTER`): ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowNextflowHeadJobToAccessSecrets", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" }, { "Sid": "AllowNextflowHeadJobToPassRoles", "Effect": "Allow", "Action": [ "iam:GetRole", "iam:PassRole" ], "Resource": "arn:aws:iam::YOUR_ACCOUNT:role/YOUR_BATCH_CLUSTER-ExecutionRole" } ] } ``` Add this trust policy to your custom IAM role: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowECSTaskAssumption", "Effect": "Allow", "Principal": { "Service": "ecs-tasks.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ## Google Secret Manager integration You must [enable Google Secret Manager](https://cloud.google.com/secret-manager/docs/configuring-secret-manager) in the same project that your Google compute environment credentials have access to. Your compute environment credentials require additional IAM permissions to interact with Google Secret Manager. ### IAM permissions See the [Google documentation](https://cloud.google.com/secret-manager/docs/access-control) for permission configuration instructions to integrate with Google Secret Manager. Seqera Platform requires `roles/secretmanager.admin` permissions in the project where it will manage your secrets. Ensure that your compute environment contains credentials with this access role for the same `project_id` listed in the service account JSON file. --- ## Commands Use the `--help` or `-h` option to list available commands and options: ```shell-session seqerakit --help ``` ### Input Seqerakit supports input through paths to YAML configuration files or directly from standard input (`stdin`). - Using file path: ```shell-session seqerakit file.yaml ``` - Using `stdin`: ```shell-session cat file.yaml | seqerakit - ``` See [Define your YAML file using CLI options](./yaml-configuration#yaml-configuration-options) for guidance on formatting your input YAML files. ### Dryrun Confirm that your configuration and command are correct before creating resources in your Seqera account, particularly when automating the end-to-end creation of multiple entities at once. To print the commands that would be executed with Platform CLI when using a YAML file, run your `seqerakit` command with the `--dryrun` option: ```shell-session seqerakit file.yaml --dryrun ``` ### Specify targets When using a YAML file as an input that defines multiple resources, use the `--targets` option to specify which resources to create. This option accepts a comma-separated list of resource names. Supported resource names include: - `actions` - `compute-envs` - `credentials` - `datasets` - `labels` - `launch` - `members` - `organizations` - `participants` - `pipelines` - `secrets` - `teams` - `workspaces` For example, given a `test.yaml` file that defines the following resources: ```yaml workspaces: - name: 'workspace-1' organization: 'seqerakit' ... compute-envs: - name: 'compute-env' type: 'aws-batch forge' workspace: 'seqerakit/workspace-1' ... pipelines: - name: 'hello-world' url: 'https://github.com/nextflow-io/hello' workspace: 'seqerakit/workspace-1' compute-env: 'compute-env' ... ``` You can target the creation of `pipelines` only by running: ```shell-session seqerakit test.yaml --targets pipelines ``` This command will create only the pipelines defined in the YAML file and ignore `workspaces` and `compute-envs`. To create both workspaces and pipelines, run: ```shell-session seqerakit test.yaml --targets workspaces,pipelines ``` ### Delete resources Instead of adding or creating resources, specify the `--delete` option to recursively delete resources in your YAML file: ```shell-session seqerakit file.yaml --delete ``` For example, if you have a `file.yaml` that defines an organization, workspace, team, credentials, and compute environment that have already been created, run `seqerakit file.yaml --delete` to recursively delete the same resources. ### Use `tw`-specific CLI options Specify `tw`-specific CLI options with the `--cli=` option: ```shell-session seqerakit file.yaml --cli="--arg1 --arg2" ``` See [CLI commands](https://docs.seqera.io/platform-cli/commands-reference) or run `tw -h` for the full list of options. :::note The `--verbose` option for `tw` CLI is currently not supported in `seqerakit` commands. ::: #### Example: HTTP-only connections The Platform CLI expects to connect to a Seqera instance that is secured by a TLS certificate. If your Seqera Enterprise instance does not present a certificate, you must run your `tw` commands with the `--insecure` option. To use `tw`-specific CLI options such as `--insecure`, use the `--cli=` option, followed by the options to use enclosed in double quotes: ```shell-session seqerakit file.yaml --cli="--insecure" ``` --- ## Installation(Seqerakit) Seqerakit is a Python wrapper that sets [Platform CLI](https://docs.seqera.io/platform-cli) command options using YAML configuration files. Individual commands and configuration parameters can be chained together to automate the end-to-end creation of all Seqera Platform entities. As an extension of the Platform CLI, Seqerakit enables: - **Infrastructure as code**: Users manage and provision their infrastructure from the command line. - **Simple configuration**: All Platform CLI command-line options can be defined in simple YAML format. - **Automation**: End-to-end creation of Seqera entities, from adding an organization to launching pipelines. ### Installation Seqerakit has three dependencies: 1. [Seqera Platform CLI (`>=0.10.1`)](https://github.com/seqeralabs/tower-cli/releases) 2. [Python (`>=3.8`)](https://www.python.org/downloads/) 3. [PyYAML](https://pypi.org/project/PyYAML/) #### Pip If you already have [Platform CLI](https://docs.seqera.io/platform-cli/installation) and Python installed on your system, install Seqerakit directly from [PyPI](https://pypi.org/project/seqerakit/): ```bash pip install seqerakit ``` Overwrite an existing installation to use the latest version: ```bash pip install --upgrade --force-reinstall seqerakit ``` #### Conda To install `seqerakit` and its dependencies via Conda, first configure the correct channels: ```bash conda config --add channels bioconda conda config --add channels conda-forge conda config --set channel_priority strict ``` Then create a conda environment with `seqerakit` installed: ```bash conda env create -n seqerakit seqerakit conda activate seqerakit ``` #### Local development installation Install the development branch of `seqerakit` on your local machine to test the latest features and updates: 1. You must have [Python](https://www.python.org/downloads/) and [Git](https://git-scm.com/downloads) installed on your system. 1. To install directly from pip: ```bash pip install git+https://github.com/seqeralabs/seqera-kit.git@dev ``` 1. Alternatively, clone the repository locally and install manually: ```bash git clone https://github.com/seqeralabs/seqera-kit.git cd seqera-kit git checkout dev pip install . ``` 1. Verify your installation: ```bash pip show seqerakit ``` ### Configuration Create a [Seqera](https://cloud.seqera.io/tokens) access token via **Your Tokens** in the user menu. Seqerakit reads your access token from the `TOWER_ACCESS_TOKEN` environment variable: ```bash export TOWER_ACCESS_TOKEN= ``` For Enterprise installations, specify the custom API endpoint used to connect to Seqera. Export the API endpoint environment variable: ```bash export TOWER_API_ENDPOINT= ``` By default, this is set to `https://api.cloud.seqera.io` to connect to Seqera Cloud. ### Usage To confirm the installation of `seqerakit`, configuration of the Platform CLI, and connection to Seqera is working as expected, run this command: ```bash seqerakit --info ``` This runs the `tw info` command under the hood. Use `--version` or `-v` to retrieve the current version of your `seqerakit` installation: ```bash seqerakit --version ``` Use the `--help` or `-h` option to list the available commands and their associated options: ```bash seqerakit --help ``` See [Commands](./commands) for detailed instructions to use Seqerakit. --- ## Templates Customize YAML configuration templates to use in `seqerakit` commands to create, update, or delete Seqera resources. Create or delete multiple resources with a single command by combining them into a single configuration file. To use the templates on this page: 1. Copy the template text or download the YAML files you need. 1. Edit the values to specify your resource details, and save as a `.yaml` file. 1. Specify the YAML template file in your `seqerakit` commands: - To create the resources specified in the file: ```shell-session seqerakit file.yaml ``` - To delete the existing resources specified in the file: ```shell-session seqerakit file.yaml --delete ``` :::info See [Specify targets](./commands#specify-targets) to create or delete only selected resources from configuration templates that contain multiple resource entries. ::: See [End-to-end example](#end-to-end-example) for a template that contains examples of all Seqera resources that can be created with Seqerakit. ### Administration Manage organizations, organization members, workspaces, teams, and participants. #### Organizations Add or delete organizations. {Organizations} [Download organizations.yaml](./templates/organizations.yaml) #### Members Add or delete organization members. {Members} [Download members.yaml](./templates/members.yaml) #### Workspaces Add or delete workspaces. {Workspaces} [Download workspaces.yaml](./templates/workspaces.yaml) #### Teams Add or delete teams. {Teams} [Download teams.yaml](./templates/teams.yaml) #### Participants Add or delete participants in workspaces and teams. {Participants} [Download participants.yaml](./templates/participants.yaml) ### Credentials Add or delete compute environment, Git, and container registry credentials in workspaces. {Credentials} [Download credentials.yaml](./templates/credentials.yaml) ### Compute environments Add or delete compute environments. {ComputeEnvironments} [Download compute-envs.yaml](./templates/compute-envs.yaml) ### Pipelines Add or delete pipelines in workspace Launchpads. {Pipelines} [Download pipelines.yaml](./templates/pipelines.yaml) ### Launch Launch a Nextflow pipeline. {Launch} [Download launch.yaml](./templates/launch.yaml) ### Datasets Add or delete workspace datasets for pipeline input data. {Datasets} [Download datasets.yaml](./templates/datasets.yaml) ### Labels Add or delete labels and resource labels to apply to workspace compute environments, pipelines, and runs. {Labels} [Download labels.yaml](./templates/labels.yaml) ### Secrets Add or delete user and workspace secrets. {Secrets} [Download secrets.yaml](./templates/secrets.yaml) ### Actions Add or delete pipeline actions. {Actions} [Download actions.yaml](./templates/actions.yaml) ### End-to-end example A template to create the following resources: - An organization - A workspace - A team - Participants - Credentials - Secrets - Compute environments - Datasets - Pipelines The template also contains `launch` entries to launch saved pipelines. {EndToEnd} [Download seqerakit-e2e.yaml](./templates/seqerakit-e2e.yaml) --- ## YAML configuration Seqerakit supports the creation and deletion of the following Seqera Platform resources, listed here with their respective Platform CLI resource names: - Pipeline actions: `actions` - Compute environments: `compute-envs` - Credentials: `credentials` - Datasets: `datasets` - Labels (including resource labels): `labels` - Pipeline launch: `launch` - Organization members: `members` - Organizations: `organizations` - Workspace and team participants: `participants` - Pipelines: `pipelines` - Pipeline secrets: `secrets` - Teams: `teams` - Workspaces: `workspaces` To determine the options to provide as definitions in your YAML file, run the Platform CLI help command for the resource you want to create. 1. Retrieve CLI options: Obtain a list of available CLI options for defining your YAML file with the Platform CLI `help` command. For example, to add a pipeline to your workspace, view the options for adding a pipeline: ```shell-session tw pipelines add -h ``` ```shell-session Usage: tw pipelines add [OPTIONS] PIPELINE_URL Add a workspace pipeline. Parameters: * PIPELINE_URL Nextflow pipeline URL. Options: * -n, --name= Pipeline name. -w, --workspace= Workspace numeric identifier (TOWER_WORKSPACE_ID as default) or workspace reference as OrganizationName/WorkspaceName -d, --description= Pipeline description. --labels=[,...] List of labels seperated by coma. -c, --compute-env= Compute environment name. --work-dir= Path where the pipeline scratch data is stored. -p, --profile=[,...] Comma-separated list of one or more configuration profile names you want to use for this pipeline execution. --params-file= Pipeline parameters in either JSON or YML format. --revision= A valid repository commit Id, tag or branch name. ... ``` 1. Define key-value pairs in YAML: Translate each CLI option into a key-value pair in the YAML file. The structure of your YAML file should reflect the hierarchy and format of the CLI options. For example: ```yaml pipelines: - name: 'my_first_pipeline' url: 'https://github.com/username/my_pipeline' workspace: 'my_organization/my_workspace' description: 'My test pipeline' labels: 'yeast,test_data' compute-env: 'my_compute_environment' work-dir: 's3://my_bucket' profile: 'test' params-file: '/path/to/params.yaml' revision: '1.0' ``` In this example: - The keys (`name`, `url`, `workspace`, and so forth) are the keys derived from the CLI options. - The corresponding values are user-defined. #### Best practices - The indentation and structure of the YAML file must be correct — YAML is sensitive to formatting. - Use quotes around strings that contain special characters or spaces. - To list multiple values (such as multiple `labels`, `instance-types`, or `allow-buckets`), separate values with commas. This is shown with `labels` in the preceding example. - For complex configurations, see [Templates](./templates). ### Templates See [Templates](./templates) for YAML file templates for each of the entities that can be created in Seqera. ### YAML Configuration Options Some options handled specially by `seqerakit` or not exposed as `tw` CLI options can be provided in your YAML configuration file. #### Pipeline parameters using `params` and `params-file` To specify pipeline parameters, use `params:` to specify a list of parameters or `params-file:` to point to a parameters file. For example, to specify pipeline parameters within your YAML: ```yaml params: outdir: 's3://path/to/outdir' fasta: 's3://path/to/reference.fasta' ``` To specify a file containing pipeline parameters: ```yaml params-file: '/path/to/my/parameters.yaml' ``` Or provide both: ```yaml params-file: '/path/to/my/parameters.yaml' params: outdir: 's3://path/to/outdir' fasta: 's3://path/to/reference.fasta' ``` :::note If duplicate parameters are provided, the parameters provided as key-value pairs inside the `params` nested dictionary of the YAML file will take precedence **over** values in the `params-file`. ::: #### Overwrite For every entity defined in your YAML file, specify `overwrite: True` to overwrite any existing Seqera entities of the same name. Seqerakit will first check to see if the name of the entity exists. If so, it will invoke a `tw delete` command before attempting to create it based on the options defined in the YAML file. ```shell-session DEBUG:root: Overwrite is set to 'True' for organizations DEBUG:root: Running command: tw -o json organizations list DEBUG:root: The attempted organizations resource already exists. Overwriting. DEBUG:root: Running command: tw organizations delete --name $SEQERA_ORGANIZATION_NAME DEBUG:root: Running command: tw organizations add --name $SEQERA_ORGANIZATION_NAME --full-name $SEQERA_ORGANIZATION_NAME --description 'Example of an organization' ``` #### Specify JSON configuration files with `file-path` The Platform CLI allows the export and import of entities through JSON configuration files for pipelines and compute environments. To use these files to add a pipeline or compute environment to a workspace, use the `file-path` key to specify a path to a JSON configuration file. An example of the `file-path` option is provided in the [compute-envs.yaml](./templates/compute-envs.yaml) template: ```yaml compute-envs: - name: 'my_aws_compute_environment' # required workspace: 'my_organization/my_workspace' # required credentials: 'my_aws_credentials' # required wait: 'AVAILABLE' # optional file-path: './compute-envs/my_aws_compute_environment.json' # required overwrite: True ``` --- ## Custom container template :::info[**Prerequisites**] You will need the following to get started: - Valid credentials for accessing cloud storage resources - **Maintain** role permissions (minimum) - A compute environment with sufficient resources (scale based on data volume) - [Data Explorer](../data/data-explorer) enabled ::: For ready-to-use examples, see [Example custom Studios][example-studios]. Select **Custom container template** and provide your own template (see [Custom container template image][custom-image]). When you select this option, you cannot **Install Conda packages**. Configure the following fields: - **Container identifier**: The template for the container. - **Resource labels**: Any [resource label](../labels/overview) already defined for the compute environment is added by default. Additional custom resource labels can be added or removed as needed. - **Environment variable**: Environment variables for the session. All variables from the selected compute environment are automatically inherited and displayed. Additional session-specific variables can be added. Session-level variables take precedence. To override an inherited variable, define the same key with a different value. - **Studio name**: The name for the Studio. - **Description** (optional): A description for the Studio. - **Collaboration**: Session access permissions. By default, all workspace users with the launch role and above can connect to the session. Toggle **Private** on to restrict connections to the session creator only. :::note When private, workspace administrators can still start, stop, and delete sessions, but cannot connect to them. ::: - **SSH Connection (public preview)**: From Enterprise v25.3.3, you can enable direct connections to running Studio sessions using standard SSH clients, VS Code Remote SSH, or terminal access. Enable the toggle to allow SSH connections to this Studio session. See [Studios SSH configuration](../enterprise/studios-ssh) for configuration details. - **Session lifespan**: The duration the session remains active. Available options depend on your workspace settings: - **Stop the session automatically after a predefined period of time**: An automatic timeout for the session (minimum: 1 hour; maximum: 120 hours; default: 8 hours). If a workspace-level session lifespan is configured, this field cannot be edited. Changes apply only to the current session and revert to default values after the session stops. - **Keep the session running:** Continuous session operation until manually stopped or an error terminates it. The session continues consuming compute resources until stopped. ### Mount data Mount data repositories to make them accessible in your session: 1. Select **Mount data** to open the data selection modal. 1. Choose the data repositories to mount. 1. Select **Mount data** to confirm. Mounted repositories are accessible at `/workspace/data/` using the [Fusion file system](https://docs.seqera.io/fusion). Data doesn't need to match the compute environment region, though cross-region access may increase costs or cause errors. Sessions have read-only access to mounted data by default. Enable write permissions by adding AWS S3 buckets as **Allowed S3 Buckets** in your compute environment configuration. Files uploaded to a mounted bucket during an active session may not be immediately available within that session. ## Save and start 1. Review the configuration to ensure all settings are correct. 1. Save your configuration: - To save and immediately start your Studio, select **Add and start**. - To save but not immediately start your Studio, select **Add only**. Studios you create will be listed on the Studios landing page with a status of either **stopped** or **starting**. Select a Studio to inspect its configuration details. {/* links */} [contact]: https://support.seqera.io/ [aws-cloud]: ../compute-envs/aws-cloud [aws-gpu]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html [aws-batch]: ../compute-envs/aws-batch [custom-envs]: ./custom-envs [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./container-images [example-studios]: ./example-studios --- ## Import from Git repository :::info[**Prerequisites**] You will need the following to get started: - **Maintain** role permissions or above - A compute environment with sufficient resources (scale based on data volume) - [Data Explorer](../data/data-explorer) enabled - Git credentials configured in your workspace - A Git repository containing a `.seqera` folder ::: **Limitations** - Compute environments are Platform-specific and cannot be defined in external Git repositories. Select the compute environment when you add a Studio. - Data-links currently cannot be referenced in Git repositories. Mount data manually when adding a Studio. - Git repositories with multiple Studio configurations are not supported. However, it is possible to use a Git repository with multiple branches and a single configuration per branch. ### Create the required configuration files Create a `studio-config.yaml` file in the `.seqera` directory in your repository. Your `studio-config.yaml` should contain at least `schemaVersion `, `kind` and `session.template.kind`. All other fields are optional. :::note `ssh.enabled` is only available from v25.3.3 and will be ignored in earlier versions. ::: ```yaml schemaVersion: "0.0.1" kind: "studio-config" session: name: "studio-name" # Must be unique to a workspace. If undefined, an auto-generated name is used description: "desc" # Short description of what the Studio is for template: kind: "registry"|"dockerfile"|"none" # Required registry: "cr.seqera.io/image:latest" # Ignored for `dockerfile` and `none` dockerfile: "Dockerfile" # Ignored for `registry` and `none` clone: enabled: true # Clone the contents of the repository to the Studio. Defaults to `true` path: "/workspace" # Defaults to `/workspace`. If you want to clone to `/workspace/repository` then you need to specify this dependencies: condaEnvironmentFile: "environment.yaml" # Define additional libraries (and versions). Ignored for `dockerfile` computeRequirements: awsBatch: # Ignored for non-AWS batch compute environment cpu: 2 # Number of CPUs to use. Defaults to `2` gpu: 0 # Number of GPUs to use (if the CE supports GPUs). Defaults to `0` memory: 8192 # Memory allocated in MiB. Defaults to `8192` environmentVariables: # Ordered sequence of elements that are objects (or mappings) of key-value pairs - name: "var1" value: "value1" - name: "var2" value: "value2" management: # Session management settings lifespanHours: 1 # Ignored if workspace lifespan is set isPrivate: false # Defaults to `false` ssh: enabled: true # Defaults to `false` ``` The schema can define a custom `Dockerfile` or an `environment.yaml` file, which must be in the `.seqera` folder. The following limitations apply: - Define the target repository where your custom images will be pushed by setting the `TOWER_DATA_STUDIO_WAVE_CUSTOM_IMAGE_REGISTRY` and `TOWER_DATA_STUDIO_WAVE_CUSTOM_IMAGE_REPOSITORY` environment variables on the Platform backend containers. If no repository configuration is specified, the build will fail. - Each workspace needs to have valid credentials to push to the repository you've specified. - The only supported repository and compute environment combination for a fully private Dockerfile-based Studio is ECR and AWS. - The files pulled for Dockerbuild context have individual and total file size limits: - Individual files cannot be larger than 5 MB. - Total file size cannot be more than 10 MB. :::tip To help you get started, a [GitHub repository][github-examples] with multiple branches for various use cases is publicly available. Each branch offers different configuration options. ::: ### Add a Studio You can add a Studio by referencing a Git repository containing Studio configuration files. You can also configure the following fields: - **Git repository**: Enter the full URL to your Git repository (e.g., `https://github.com/your-org/your-repo`). - **Revision**: Select a branch, tag, or commit from the drop-down. The drop-down is dynamically populated based on the repository URL. If no revision is selected, the default branch is used. - **Install Conda packages**: A list of conda packages to include with the Studio. For more information on package syntax, see [conda package syntax][conda-syntax]. - **Resource labels**: Any [resource label](../labels/overview) already defined for the compute environment is added by default, but can be removed. Additional custom resource labels can be added or removed as needed. - **Environment variables**: Environment variables for the session. All variables from the selected compute environment are automatically inherited and displayed. Additional session-specific variables can be added. Session-level variables take precedence. To override an inherited variable, define the same key with a different value. - **Studio name**: The name for the Studio. - **Description** (optional): A description for the Studio. - **Collaboration**: Session access permissions. By default, all workspace users with the launch role and above can connect to the session. Toggle **Private** on to restrict connections to the session creator only. :::note When private, workspace administrators can still start, stop, and delete sessions, but cannot connect to them. ::: - **SSH Connection (public preview)**: From Enterprise v25.3.3, you can enable direct connections to running Studio sessions using standard SSH clients, VS Code Remote SSH, or terminal access. Enable the toggle to allow SSH connections to this Studio session. See [Studios SSH configuration](../enterprise/studios-ssh) for configuration details. - **Session lifespan**: The duration the session remains active. Available options depend on your workspace settings: - **Stop the session automatically after a predefined period of time**: An automatic timeout for the session (minimum: 1 hour; maximum: 120 hours; default: 8 hours). If a workspace-level session lifespan is configured, this field cannot be edited. Changes apply only to the current session and revert to default values after the session stops. - **Keep the session running**: Continuous session operation until manually stopped or an error terminates it. The session continues consuming compute resources until stopped. :::note When the **Git URL** or **Revision** fields are changed, form field values dynamically update. ::: ### Mount data Mount data to make them accessible in your session: 1. Select **Mount data** to open the data selection modal. 1. Choose the data to mount. 1. Select **Mount data** to confirm. Once the Studio session is running, mounted data are accessible at `/workspace/data/` using the [Fusion file system](https://docs.seqera.io/fusion). Data doesn't need to match the compute environment region, though cross-region data transfer (ingress and egress) may increase costs. Sessions have read-only access to mounted data by default. Enable write permissions by adding AWS S3 buckets as **Allowed S3 Buckets** in your compute environment configuration. Files uploaded to a mounted bucket during an active session may not be immediately available within that session. See [Running session does not show new data in object storage](../troubleshooting_and_faqs/studios_troubleshooting#running-session-does-not-show-new-data-in-object-storage) for more information. ### Repository cloning When a Studio session starts from a Git repository, the repository contents are cloned into the session, using the same commit that was selected, or resolved, when the Studio was first created. For example, repository `https://github.com/seqeralabs/studio-templates.git` clones to `/workspace/` with `README.md` at `/workspace/README.md`. You can disable cloning, which allows you to share a public/private template. You can define the clone path configuration in the schema without the need to build a different Docker image. #### Limitations - Platform credentials are not shared with the Studio. - The `.git` folder is not synced and you cannot push/pull from the configured repository after initial Studio creation. - There are no preprovisioned Git credentials available to use in the Studio. ## Save and start 1. Review the configuration to ensure all settings are correct. 1. Save your configuration: - To save and immediately start your Studio, select **Add and start**. - To save but not immediately start your Studio, select **Add only**. Studios you create will be listed on the Studios landing page with a status of either **stopped** or **starting**. Select a Studio to inspect its configuration details. {/* links */} [github-examples]: https://github.com/seqeralabs/studio-schema-examples [contact]: https://support.seqera.io/ [aws-cloud]: ../compute-envs/aws-cloud [aws-gpu]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html [aws-batch]: ../compute-envs/aws-batch [custom-envs]: ./custom-envs [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./container-images --- ## Seqera-provided container template :::info[**Prerequisites**] You will need the following to get started: - Valid credentials for accessing cloud storage resources - **Maintain** role permissions (minimum) - A compute environment with sufficient resources (scale based on data volume) - [Data Explorer](../data/data-explorer) enabled ::: Configure the following fields: - **Container template**: The template for the container. Select a provided container template. - **Install Conda packages**: A list of conda packages to include with the Studio. For more information on package syntax, see [conda package syntax][conda-syntax]. :::note You need to configure a target repository using the `TOWER_DATA_STUDIO_WAVE_CUSTOM_IMAGE_REGISTRY` and `TOWER_DATA_STUDIO_WAVE_CUSTOM_IMAGE_REPOSITORY` environment variables. If no repository configuration is specified, the build will fail. ::: - **Resource labels**: Any [resource label](../labels/overview) already defined for the compute environment is added by default. Additional custom resource labels can be added or removed as needed. - **Environment variable**: Environment variables for the session. All variables from the selected compute environment are automatically inherited and displayed. Additional session-specific variables can be added. Session-level variables take precedence — to override an inherited variable, define the same key with a different value. - **Studio name**: The name for the Studio. - **Description** (optional): A description for the Studio. - **Collaboration**: Session access permissions. By default, all workspace users with the launch role and above can connect to the session. Toggle **Private** on to restrict connections to the session creator only. :::note When private, workspace administrators can still start, stop, and delete sessions, but cannot connect to them. ::: - **SSH Connection (public preview)**: From Enterprise v25.3.3, you can enable direct connections to running Studio sessions using standard SSH clients, VS Code Remote SSH, or terminal access. Enable the toggle to allow SSH connections to this Studio session. See [Studios SSH configuration](../enterprise/studios-ssh) for configuration details. - **Session lifespan**: The duration the session remains active. Available options depend on your workspace settings: - **Stop the session automatically after a predefined period of time**: An automatic timeout for the session (minimum: 1 hour; maximum: 120 hours; default: 8 hours). If a workspace-level session lifespan is configured, this field cannot be edited. Changes apply only to the current session and revert to default values after the session stops. - **Keep the session running:** Continuous session operation until manually stopped or an error terminates it. The session continues consuming compute resources until stopped. ### Mount data Mount data to make them accessible in your session: 1. Select **Mount data** to open the data selection modal. 1. Choose the data to mount. 1. Select **Mount data** to confirm. Once the Studio session is running, mounted data are accessible at `/workspace/data/` using the [Fusion file system](https://docs.seqera.io/fusion). Data doesn't need to match the compute environment region, though cross-region access may increase costs or cause errors. Sessions have read-only access to mounted data by default. Enable write permissions by adding AWS S3 buckets as **Allowed S3 Buckets** in your compute environment configuration. Files uploaded to a mounted bucket during an active session may not be immediately available within that session. See [Running session does not show new data in object storage](../troubleshooting_and_faqs/studios_troubleshooting#running-session-does-not-show-new-data-in-object-storage) for more information. ## Save and start 1. Review the configuration to ensure all settings are correct. 1. Save your configuration: - To save and immediately start your Studio, select **Add and start**. - To save but not immediately start your Studio, select **Add only**. Studios you create will be listed on the Studios landing page with a status of either **stopped** or **starting**. Select a Studio to inspect its configuration details. {/* links */} [contact]: https://support.seqera.io/ [aws-cloud]: ../compute-envs/aws-cloud [aws-gpu]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html [aws-batch]: ../compute-envs/aws-batch [custom-envs]: ./custom-envs [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./container-images --- ## Add a Studio Select the **Studios** tab, and then select **Add Studio**. The options available are: - [Provided container template][containers] - [Custom container template][custom-container] - [Import from a Git repository][github] ### Compute environment requirements For AWS Batch compute environments: - **CPUs allocated**: The default allocation is 2 CPUs. - **GPUs allocated**: Available only if the selected compute environment has GPU support enabled. For more information about GPUs on AWS, see [Amazon ECS task definitions for GPU workloads][aws-gpu]. The default allocation is 0 GPUs. - **Maximum memory allocated**: The default allocation is 8192 MiB of memory. :::note In AWS Batch, Seqera creates two job queues and their respective compute environments: a head queue that runs the parent Nextflow process on a single On-Demand instance, and a worker queue that executes per-task processes dispatched by the head node, typically on Spot instances. Studios uses only the head queue and its compute environment. The worker queue is not used. ::: For more information on AWS Batch configuration, see [AWS Batch][aws-batch]. Single virtual machine compute environments are supported for [AWS][aws-cloud], [Azure][azure-cloud], and [Google Cloud][google-cloud]. ### EFS file systems If you configured your compute environment to include an EFS file system with **EFS file system > EFS mount path**, the mount path must be explicitly specified. The mount path cannot be the same as your compute environment work directory. If the EFS file system is mounted as your compute environment work directory, snapshots cannot be saved and sessions fail. To mount an EFS volume in a Studio session (for example, if your organization has a custom, managed, and standardized software stack in an EFS volume), add the EFS volume to the compute environment (system ID and mount path). The volume will be available at the specified mount path in the session. ### SSH connection (public preview) From Enterprise v25.3.3, direct SSH connections to running Studios are available using standard SSH clients, VS Code Remote SSH, or terminal access. To use this feature: 1. Enable SSH access for your workspace by setting the `TOWER_DATA_STUDIO_SSH_ALLOWED_WORKSPACES` [environment variable](../enterprise/configuration/overview#data-features) during deployment. See [Studios SSH configuration](../enterprise/studios-ssh) for configuration details. 2. Add your SSH public key to your Seqera Platform user profile. 3. Enable the **SSH Connection** toggle when adding a Studio. For connection instructions and VS Code setup, see [Connect to a Studio via SSH](./managing#connect-to-a-studio-via-ssh-public-preview). {/* links */} [contact]: https://support.seqera.io/ [aws-cloud]: ../compute-envs/aws-cloud [aws-gpu]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html [aws-batch]: ../compute-envs/aws-batch [azure-cloud]: ../compute-envs/azure-cloud.md [google-cloud]: ../compute-envs/google-cloud.md [github]: ./add-studio-git-repo [custom-container]: ./add-studio-custom-container [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./add-studio-custom-container --- ## Connect changelog :::note Always use the `recommended` tagged template image for new Studios. Only two earlier minor versions of Seqera Connect are supported by Seqera. ::: ## Connect server ### server/v0.11.0 `latest` - 2026-03-02 * Fix(proxy): bidirectional proxy fixes ### server/v0.10.0 - 2026-02-11 * Add: SSH Connectivity: * Server implementation (initialize SSH server when enabled) * Authenticate authorization requests to Platform with oidc secret * Add SSH connection activity tracking and notifications * Change the logger timestamp format to ISO8601 * Detect network load balancer health checks ### server/v0.9.0 - 2025-12-05 * Fix: security vulnerabilities for crypto SSH library and slack nebula * Upgrade go (from v1.24.3 to 1.25.3) and caddyserver (from 2.10.0 to 2.10.2) ### server/v0.8.4 - 2025-10-31 * N/A ### server/v0.8.3 - 2025-07-25 :::warning Connect version 0.8.3 introduced a change which required the creation of a `/data` folder which was mounted to `connect-proxy`. If this is not done, the deployment will fail. ::: * Extract Fusion version * Fix(proxy): include prefix in Location header ### server/v0.8.2 - 2025-07-21 * Add ability to set tool identifier after compile time * Add mount data to initial configuration logs * Add eStargz support to client images build * Add management API tunnels `GET` requests * Add `$` to `metrics_patch.txt` * Add `connector_id` to stored tunnel host in Redis * Add CPU/memory collector * Add `connector_id` to identify sessions in logs * Add support for multi-platform build of Connect clients (adding Linux/ARM64) * Improve race condition `reOpening`, `compareAndDelete`, and `Handle` * Simplify `sessionid` functionality interface * Use `CONNECT_MANAGEMENT_PORT`for proxy instead of deprecated `CONNECT_METRICS_PORT` * Disable resource collector * Spot instance termination watcher implementation * Create a client and server packages * Restructure proxy package * Use `synctest` in `executor_test.go` * Basic structure of management API * Enable path-based routing * Update go-jose library (v3 from 3.0.3 to 3.0.4; v4 from 4.0.4 to 4.0.5) * Update x/net dependency (from v0.36.0 to v0.40.0) * Upgrade go (from v1.23.0 to v1.24.3) and xcaddy (from v2.9.1 to v2.10.0) * Upgrade go in Dockerfiles (from v1.23 to v1.24) * Bump golang.org/x/net (from v0.35.0 to v0.36.0) * Bump dependencies that were using vulnerable golang.org/x/crypto (from v0.33.0 to v0.35.0) ### server/v0.8.1-rc - 2025-04-10 * Extend `GithubActions` to trigger clients publishing/promoting in downstream repo studio-templates * `sync.Map`: use `Swap` instead of `LoadAndDelete` ### server/v0.8.0-rc - 2025-03-19 * Feat: update caddy reverse proxy to dynamic A record * Feat: change proxy Docker command to be the same as before * Feat: client mux implementation * Feat: server connect-tunnel implementation * Feat: in case view scope is missing from access token, redirect with auth callback error query parameter * Feat: removal of `go-gost`, implement `connect-tunnel`, and upgrade go from v1.20 to v1.23 * Feat: micromamba based RStudio * Feat: add Git hash to stage releases * Feat: add 10 minutes' waiting period before failing notifying Platform * Cut 0.8.0 release * Upgrade xcaddy version (from v0.4.2 to v0.4.4) * Release Server version 0.7.5 ### server/v0.7.8 - 2025-03-06 * Feat: update caddy reverse proxy to dynamic a record * Feat: client mux implementation * Feat: micromamba based rstudio * Feat: server connect-tunnel implementation * Feat: in case view scope is missing form access token, redirect with auth callback error query parameter * Feat: removal of `go-gost`, implement `connect-tunnel`, and upgrade `go` (from v1.20 to v1.23) * Use Fusion v2.4.9 * Upgrade xcaddy version ### server/v0.7.7 - 2025-01-10 * Feat: change proxy Docker command to be the same as before ### server/v0.7.6 - 2025-01-08 * Latest release with adjusted workflow ### server/v0.7.5 - 2025-01-07 * Env var capital letters ## Connect client ### client/v0.12.1 `latest` - 2026-05-19 * Fix(client): skip auto-discovered mounts under /proc in overlay setup * Chore: bump go_modules group dependencies across components ### client/v0.12.0 - 2026-04-16 * Feat(client): support agent forwarding in SSH server * Chore(deps): update to go 1.26.2 and google.golang.org/grpc to 1.79.3 (vulnerability fix) * Chore(deps): pin dependencies * Update CI actions ### client/v0.11.1 - 2026-03-24 * Fix(client): git cloning failing with conflicts on mounted datalink and preexisting files ### client/v0.11.0 - 2026-03-02 * Fix: x/net vulnerability * Fix(client): add new version to matrix * Fix: slow/flaky tests * Fix: update dependencies to fix security vulnerabilities * Refactor(client): refactor executor package * Fix(client): apply suggested security fixes ### client/v0.10.0 - 2026-02-11 * Moved Docker service management to the Connect-client. * Add: SSH Connectivity: * Server implementation (initialize ssh server when enabled) * Fingerprint verification * Add SSH connection activity tracking and notifications ### client/v0.9.0 - 2025-12-05 - Add: disk size and auto resizing based on compute env - Add: version module and add support for client version - Fix: security vulnerabilities for crypto ssh library and slack nebula - Upgrade go (from v1.24.3 to 1.25.3) and caddyserver (from 2.10.0 to 2.10.2) - Bump server to 0.9.0 ### client/v0.8.7 - 2025-10-14 * * Fix(vscode): incorrect path in Dockerfile ### client/v0.8.6 - 2025-10-14 * Fix(vscode): incorrect path in Dockerfile ### client/v0.8.5 - 2025-07-29 * Feat: add eStargz support to client images * Feat: send squash notifications to platform * Feat: extract Fusion version ### client/v0.8.4 - 2025-07-18 * Feat: enable path-based routing (optional `CONNECT_TOOL_PATH_PREFIX` as base URL) * Feat: install pip for VS Code images * Feat: enable GHA runner cache to improve build time performance ### client/v0.8.3 - 2025-06-19 * Fix: return normal err when server closes connection ### client/v0.8.2 - 2025-06-17 * Add R-IDE option and remove unused scripts ### client/v0.8.1 - 2025-05-29 * Feat: delay running notification until the downstream is connectable * Feat: Spot instance termination watcher implementation * Feat: simplify `sessionid` functionality interface * Update x/net dependency (from v0.36.0 to v0.40.0) * Update go-jose library v3 (from 3.0.3 to 3.0.4) and v4 (from 4.0.4 to 4.0.5) * Bump golang.org/x/net (from v0.35.0 to v0.36.0) * Bump dependencies that were using vulnerable golang.org/x/crypto (from v0.33.0 to v0.35.0) * Upgrade go (from v1.23.0 to v1.24.3) and xcaddy (from v2.9.1 to v2.10.0) * Upgrade go in Dockerfiles (from v1.23 to v1.24) ### client/v0.8.0-rc - 2025-03-19 * fix: swap connector after closing previous ### client/v0.7.7 - 2025-03-07 * Feat: add 10 minutes waiting period before failing notifying Platform ### client/v0.7.6 - 2025-03-03 * Feat: micromamba based RStudio * Feat: client mux implementation * Feat: in case view scope is missing from access token, redirect with auth callback error query parameter * Feat: removal of `go-gost`, implement `connect-tunnel`, and upgrade go (from v1.20 to v1.23) * Feat: server connect-tunnel implementation * Upgrade xcaddy version * Use Fusion v2.4.9 ### client/v0.7.5 - 2024-11-18 * Updated Fusion version (from v2.4.2 to v2.4.6) and use released Nextflow language server (v1.0.0) VS Code extension ### client/v0.7.4 - 2024-10-28 * Feat: default to run, specify entrypoint ### client/v0.7.2-rc 2024-09-26 * Feat: add micromamba to VS Code Docker image ### client/v0.7.1 - 2024-09-17 * Feat: workflows for publishing versioned images for dev/staging/prod * Feat: template to test clients locally against dev * Bump clients version * Bump version to fixed one used for release * Bump Fusion to v2.3.5 --- ## Container image templates There are four container image templates provided: JupyterLab, R-IDE, Visual Studio Code, and Xpra. The image templates install a very limited number of packages when the Studio session container is built. You can install additional packages as needed during a Studio session. The image template tag includes the version of the analysis application, an optional incompatibility flag, and the Seqera Connect version. Connect is the proprietary Seqera web server client that manages communication with the container. The image template tag has the format: ```ignore title="Image template tag" -[u]- ``` - ``: Third-party analysis application that follows its own semantic versioning `..`, such as `4.2.5` for JupyterLab. - ``: Optional analysis application update version, such as `u1`, for instances where a backwards incompatible change is introduced. - ``: Seqera Connect client version, such as `0.12` or `0.12.0`. Additionally, the Seqera Connect client version string has the format: ```ignore title="Seqera version tag subset" .. ``` - ``: Signifies major version changes in the underlying Seqera Connect client. - ``: Signifies breaking changes in the underlying Seqera Connect client. - ``: Signifies patch (non-breaking) changes in the underlying Seqera Connect client. When pushed to the container registry, an image template is tagged with the following tags: - `-.`, such as `4.2.3-0.10`. When adding a new container template image this is the tag displayed in Seqera Platform. - `-..`, such as `4.2.3-0.10.0`. To view the latest versions of the images, see [public.cr.seqera.io](https://public.cr.seqera.io/). You can also augment the Seqera-provided image templates or use your own custom container image templates. This is the recommended approach for managing reproducible analysis environments. For more information, see [Custom environments][custom-envs]. ### JupyterLab 4.2.5 The default user is the `root` account. The following [conda-forge](https://conda-forge.org/) packages are available by default: - `python=3.13.0` - `pip=24.2` - `jedi-language-server=0.41.4` - `jupyterlab=4.2.5` - `jupyter-collaboration=1.2.0` - `jupyterlab-git=0.50.1` - `jupytext=1.16.4` - `jupyter-dash=0.4.2` - `ipywidgets=7.8.4` - `pandas[all]=2.2.3` - `scikit-learn=1.5.2` - `statsmodels=0.14.4` - `itables=2.2.2` - `seaborn[stats]=0.13.2` - `altair=5.4.1` - `plotly=5.24.1` - `r-ggplot2=3.5.1` - `nb_black=1.0.7` - `qgrid=1.3.1` To install additional Python packages during a running Studio session, execute `!pip install ` commands in your notebook environment. Additional system-level packages can be installed in a terminal window using `apt install `. To see all JupyterLab image templates, including security scan results, or to inspect the container specification, see [public.cr.seqera.io/repo/platform/data-studio-jupyter][ds-jupyter]. ### R-IDE 4.4.1 The default user is the `root` account. To install R packages during a running Studio session, execute `install.packages("")` commands in your notebook environment. Additional system-level packages can be installed in a terminal window using `apt install `. To see all R-IDE image templates, including security scan results, or to inspect the container specification, see [https://public.cr.seqera.io/repo/platform/data-studio-ride][ds-ride]. ### Visual Studio Code 1.93.1 [Visual Studio Code][def-vsc] is an integrated development environment (IDE) that supports many programming languages. The default user is the `root` account. The container template image ships with the latest stable version of [Nextflow] and the [VS Code extension for Nextflow][nf-lang-server] to make troubleshooting Nextflow workflows easier. To install additional extensions during a running Studio session, select **Extensions**. Additional system-level packages can be installed in a terminal window using `apt install `. To see all Visual Studio Code image templates, including security scan results, or to inspect the container specification, see [public.cr.seqera.io/platform/data-studio-vscode][ds-vscode]. ### Docker-in-docker A common use of VS Code in Studios is developing and troubleshooting Nextflow pipelines, which requires running Docker inside the Dockerized container. The recommended method is: **1. Create an [AWS Cloud][aws-cloud] compute environment:** By default, this type of compute environment is optimized for running Nextflow pipelines. :::tip Many standard nf-core pipelines such as [*nf-core/rnaseq*](https://nf-co.re/rnaseq) require at least 4 CPUs and 16 GB memory. In **Advanced options**, specify an instance type with at least these resources (e.g., `m5d.xlarge`). ::: **2. Only have one running Studio session per compute environment:** This allows the Studio session, and Nextflow, to maximize the available CPU and memory. :::tip The nf-core pipeline template was updated, and many existing pipelines don't yet use the new multi-line shell command in `nextflow.config`. To ensure compatibility with the latest version of Nextflow (which ships with the VS Code container template image), include the following in your pipeline `nextflow.config` file. ```bash // Set bash options process.shell = [ "bash", "-C", // No clobber - prevent output redirection from overwriting files. "-e", // Exit if a tool returns a non-zero status/exit code "-u", // Treat unset variables and parameters as an error "-o", // Returns the status of the last command to exit.. "pipefail" // ..with a non-zero status or zero if all successfully execute ] ``` ::: ### Xpra 6.2.0 [Xpra][def-xpra], known as _screen for X_, allows you to run X11 programs by giving you remote access to individual graphical applications. The container template image also installs NVIDIA Linux x64 (AMD64/EM64T) drivers for Ubuntu 22.04 for running GPU-enabled applications. To use these GPU drivers, your compute environment must specify GPU instance families. The default user is the `root` account. The image is based on `ubuntu:jammy`. Additional system-level packages can be installed during a running Studio session in a terminal window using `apt install `. To see all Xpra image templates, including security scan results, or to inspect the container specification, see [public.cr.seqera.io/repo/platform/data-studio-xpra][ds-xpra]. ## EFS file system limitations If you configured your compute environment to include an EFS file system with **EFS file system > EFS mount path**, the mount path must be explicitly specified. The mount path cannot be the same as your compute environment work directory. If the EFS file system is mounted as your compute environment work directory, snapshots cannot be saved and sessions fail. To mount an EFS volume in a Studio session (for example, if your organization has a custom, managed, and standardized software stack in an EFS volume), add the EFS volume to the compute environment (system ID and mount path). The volume will be available at the specified mount path in the session. For more information on AWS Batch configuration, see [AWS Batch][aws-batch]. {/* links */} [contact]: https://support.seqera.io/ [aws-cloud]: ../compute-envs/aws-cloud [aws-batch]: ../compute-envs/aws-batch [custom-envs]: ./custom-envs [build-status]: ./custom-envs#build-status [cloud-bucket-subdirectory]: ./managing#cloud-bucket-subdirectory [ds-jupyter]: https://public.cr.seqera.io/repo/platform/data-studio-jupyter [ds-vscode]: https://public.cr.seqera.io/repo/platform/data-studio-vscode [ds-xpra]: https://public.cr.seqera.io/repo/platform/data-studio-xpra [ds-ride]: https://public.cr.seqera.io/repo/platform/data-studio-ride [ds-rstudio]: https://public.cr.seqera.io/repo/platform/data-studio-rstudio [def-vsc]: https://code.visualstudio.com/ [Nextflow]: https://nextflow.io/ [nf-lang-server]: https://marketplace.visualstudio.com/items?itemName=nextflow.nextflow [def-xpra]: https://github.com/Xpra-org/xpra [Wave]: https://seqera.io/wave/ --- ## Custom environments In addition to the Seqera-provided container images, you can build custom container environments by augmenting the Seqera-provided images with Conda packages or by supplying your own base container image. Studios uses the [Wave][wave-home] service to build custom container images. For ready-to-use examples, see [Example custom Studios][example-studios]. ## Conda packages Augment a Seqera-provided image with Conda packages to add the tools you need to a Studio session. :::info[**Prerequisites**] You need the following: - Wave configured. See [Wave containers][wave]. - A target repository set per workspace by the workspace Admin, in **Settings** > **Studios** > **Container repository**. - Workspace credentials with push access to the target repository. ::: ### Conda package syntax {#conda-package-syntax} When adding a new Studio, you can install Conda packages in the container image. The supported schema is identical to the Conda `environment.yml` file. For more information, see [Creating an environment file manually][env-manually]. ```yaml title="Example environment.yml file" channels: - conda-forge dependencies: - numpy - pip: - matplotlib - seaborn ``` To create a Studio with custom Conda packages, see [Add a Studio][add-s]. ## Custom container image {#custom-containers} For advanced use cases, you can build your own container image. :::note Public container registries are supported by default. Amazon Elastic Container Registry (ECR) is the only supported private container registry. ::: :::info[**Prerequisites**] You need the following: - A container image. - Access to a container image repository, either a public container registry or a private Amazon ECR repository. ::: ### Dockerfile configuration {#dockerfile} For your custom container image, you must use a Seqera-provided base image and include several additional build steps for compatibility with Studios. To create a Studio with a custom image, see [Add a Studio][add-s]. Custom images must include an `io.seqera.connect.version` label specifying the `connect-client` version used. Seqera Platform uses this label to determine available functionality when configuring and launching the Studio. :::note Studios starts without this label, but certain features (such as SSH connectivity) are unavailable. ::: #### Ports The container must use the value of the `CONNECT_TOOL_PORT` environment variable as the listening port for any interactive software you include in your custom container. #### Signals Upon termination, the container's main process must handle the `SIGTERM` signal and perform any necessary cleanup. After a 30-second grace period, the container receives the `SIGKILL` signal. #### Minimal Dockerfile The minimal Dockerfile includes directives to: - Pull a Seqera-provided base image with prerequisite binaries. - Set an image label indicating the version used. - Copy the `connect` binary into the build. - Set the container entry point. Customize the following Dockerfile to include any additional software you require: ```docker title="Minimal Dockerfile" # Add a default Connect client version. Can be overridden by build arg ARG CONNECT_CLIENT_VERSION="0.12" # Seqera base image # highlight-next-line FROM public.cr.seqera.io/platform/connect-client:${CONNECT_CLIENT_VERSION} AS connect # highlight-start # 1. Add connect version label to image metadata ARG CONNECT_CLIENT_VERSION LABEL io.seqera.connect.version="${CONNECT_CLIENT_VERSION}" # 2. Add connect binary COPY --from=connect /usr/bin/connect-client /usr/bin/connect-client # 3. Install connect dependencies RUN /usr/bin/connect-client --install # 4. Configure connect as the entrypoint ENTRYPOINT ["/usr/bin/connect-client", "--entrypoint"] # highlight-end ``` For example, to run a Python-based HTTP server, build a container from the following Dockerfile. When a Studio runs the custom template environment, the value for the `CONNECT_TOOL_PORT` environment variable is provided dynamically. ```docker title="Example Dockerfile with Python HTTP server" # Add a default Connect client version. Can be overridden by build arg ARG CONNECT_CLIENT_VERSION="0.12" # Seqera base image # highlight-next-line FROM public.cr.seqera.io/platform/connect-client:${CONNECT_CLIENT_VERSION} AS connect FROM ubuntu:20.04 RUN apt-get update --yes && apt-get install --yes --no-install-recommends python3 # highlight-start ARG CONNECT_CLIENT_VERSION LABEL io.seqera.connect.version="${CONNECT_CLIENT_VERSION}" COPY --from=connect /usr/bin/connect-client /usr/bin/connect-client RUN /usr/bin/connect-client --install ENTRYPOINT ["/usr/bin/connect-client", "--entrypoint"] # highlight-end # highlight-next-line CMD ["/usr/bin/bash", "-c", "python3 -m http.server $CONNECT_TOOL_PORT"] ``` ### Custom container image examples For example custom Studio environment container images, see the [custom Studios examples repository][custom-studios-examples]. ### Inspect container augmentation build status {#build-status} You can inspect the progress of a custom container image build, including any errors if the build fails. A link to the [Wave service][wave-home] container build report is available for every build. If the build fails, the Studio session has the **build-failed** status, and the build error details are available in the session's **Error report** tab. To inspect the status of a build, complete the following steps: 1. Select the **Studios** tab in Seqera Platform. 1. From the list of sessions, select the name of the session with `building` or `build-failed` status, then select **View**. 1. In the **Details** tab, scroll to **Build reports** and select **Summary** to open the Wave service container build report for your build. 1. Optional: If the build failed, select the **Error report** tab to view the build errors. {/* links */} [add-s]: ./add-studio [aws-batch]: ../compute-envs/aws-batch [wave]: https://docs.seqera.io/platform-enterprise/enterprise/configuration/wave [custom-studios-examples]: https://github.com/seqeralabs/custom-studios-examples [wave-home]: https://seqera.io/wave/ [env-manually]: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually [example-studios]: ./example-studios --- ## Example custom Studios Seqera provides a collection of example custom Studio environments for common bioinformatics and data science applications. Each example includes a Dockerfile and a pre-built container image you can deploy immediately or use as a template for your own custom Studio. Any application that serves its interface over HTTP can run in a Studio session. All example Dockerfiles and pre-built images are available via individual branches in the [custom-studios-examples](https://github.com/seqeralabs/custom-studios-examples) GitHub repository. For instructions on building your own custom container image from scratch, see [Custom environments][custom-envs]. | GitHub repository branch | Description | Pre-built image URL | |---|---|---| | [Marimo](https://github.com/seqeralabs/custom-studios-examples/tree/marimo) | Reactive Python notebook | `ghcr.io/seqeralabs/custom-studios-examples/marimo` | | [Streamlit](https://github.com/seqeralabs/custom-studios-examples/tree/streamlit) | Interactive web apps (MultiQC demo) | `ghcr.io/seqeralabs/custom-studios-examples/streamlit` | | [CELLxGENE](https://github.com/seqeralabs/custom-studios-examples/tree/cellxgene) | Single-cell data visualization | `ghcr.io/seqeralabs/custom-studios-examples/cellxgene` | | [Shiny](https://github.com/seqeralabs/custom-studios-examples/tree/shiny) | R-based interactive web apps | `ghcr.io/seqeralabs/custom-studios-examples/shiny` | | [TTYD](https://github.com/seqeralabs/custom-studios-examples/tree/ttyd) | Web-based terminal with Samtools | `ghcr.io/seqeralabs/custom-studios-examples/ttyd` | :::note Pre-built images may not reflect the latest version of the Seqera Connect client, system libraries, nor packages. See the [GitHub repository releases](https://github.com/seqeralabs/custom-studios-examples/releases) for current image tags. ::: ## Deploy an example Studio {#deploy} To deploy any example, follow the [Add a Studio][add-s] workflow either: 1. Select the **Import from Git repository** option. Copy and paste the repository path in the **Git repository URL** field. Then select the branch name in the auto-populated **Revision** field. 1. Select **Custom container template**, and enter the pre-built image URL from the table above. For environment variables and detailed setup instructions, see the `README.md` in each example's branch. For more information about managing Studios, see [Manage Studios][manage]. ### Provide files to Studios {#provide-files} Studios uses [Fusion][fusion] to mount cloud storage as a local filesystem inside the Studio container. When you mount a cloud bucket, its contents are available at `/workspace/data//`. There are two approaches to make files available to your custom Studio: #### Environment variables {#env-vars} Some examples define environment variables that accept cloud storage paths (such as `s3://bucket/path/to/file.csv`). When you create a Studio, set the value of these variables in the **Environment variables** section of the **Compute and Data** tab. The container translates the cloud path to the corresponding local path at `/workspace/data/` automatically. #### Data-links {#data-links} Data-links point to specific cloud storage paths. When you create a data-link, the linked directory appears in the running Studio at `/workspace/data//`. Once you [Add data-links](../data/data-explorer#add-data-repository-links), applications that support a file browser or path input can then access data at `/workspace/data//`. ## Overview of example Studios ### Marimo [Marimo](https://marimo.io/) is an open-source reactive Python notebook. Unlike traditional notebooks, Marimo automatically re-executes cells when their dependencies change, which makes it well-suited to iterative analysis where inputs change frequently. It also supports SQL natively and can publish notebooks as standalone shareable apps. The Marimo Studio uses the [uv](https://github.com/astral-sh/uv) package manager and comes pre-installed with common data science packages including scikit-learn, pandas, and altair. Access your pipeline outputs by mounting the relevant S3 buckets when you create the Studio, located at `/workspace/data/` inside the session. ### Streamlit [Streamlit](https://streamlit.io/) is an open-source Python framework for building interactive web applications. Hosting a Streamlit app in Studios gives it direct access to your S3 data through Fusion. This means no credentials to configure, no data to move or copy. The example Studio ships with a [MultiQC](https://multiqc.info/) demo app that illustrates a typical bioinformatics use case: interactive quality control reports served directly from pipeline output stored in S3. The same pattern applies to any Streamlit app you want to host within your Seqera workspace. ### CELLxGENE [CELLxGENE](https://chanzuckerberg.github.io/cellxgene/) is an interactive visualization tool for single-cell and spatial omics data. It supports exploration, analysis, and annotation of single-cell datasets in `.h5ad` format. The CELLxGENE Studio loads a dataset directly from S3 on startup using environment variables you set when creating the Studio. A default public dataset (PBMCs 3k) is pre-configured so you can verify the Studio is working before connecting your own data. ### Shiny [Shiny](https://shiny.posit.co/) is a popular framework for building interactive web applications in R or Python. The example Studio runs a demonstration R Shiny app that generates plots and output tables from CSV input data stored in S3. Running Shiny in Studios means your app runs inside your own cloud infrastructure, with access to pipeline outputs through Fusion. Each user who connects to the Studio gets their own private session, making it suitable for sharing results with colleagues who need to interact with the data directly rather than view a static report. ### TTYD [TTYD](https://tsl0922.github.io/ttyd/) is a web-based terminal emulator. The example Studio provides browser-based terminal access to a container with [Samtools](http://www.htslib.org/) pre-installed — useful when you need command-line access to a specific bioinformatics tool without the overhead of a full IDE. This pattern is straightforward to adapt: replace the Samtools base image with any containerized tool that supports `apt-get` or `yum`, then add the TTYD and Connect client layers. It's a practical option for giving colleagues access to a tool in a controlled, reproducible environment without requiring them to configure anything locally. ## Build an example image locally {#build-locally} To build any example image locally, clone the repository branch and run the Docker build command: ```bash git clone --branch --single-branch https://github.com/seqeralabs/custom-studios-examples.git docker build --platform linux/amd64 --build-arg CONNECT_CLIENT_VERSION=0.12 -t . ``` Replace `` with the branch name (such as `marimo` or `streamlit`) and `` with your preferred image tag. Then push the built image to your container registry, then use the image URI when you [deploy the Studio](#deploy). ## Extend or contribute examples {#extend} You can use these examples as a starting point for your own custom Studios. Any application that serves its graphical interface over an HTTP port can run in Studios. For detailed instructions on building custom container images, see [Custom environments](./custom-envs.md). To contribute new examples to the repository, see the [contributing guidelines][contribute] in the GitHub repository. {/* links */} [contribute]: https://github.com/seqeralabs/custom-studios-examples#contributing [fusion]: https://docs.seqera.io/fusion/ [custom-container]: ./add-studio-custom-container [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./add-studio-custom-container [manage]: ./managing [add-s]: ./add-studio [custom-envs]: ./custom-envs --- ## Manage Studios Select the **Studios** tab in Platform to: - Start, stop, or connect to an existing session. - Dynamically filter the list of Studios using the search bar. - Open a detailed view that displays configuration information. :::note - If you're not able to see the Studios tab, contact your Platform administrator. - Review the user roles documentation for details about role permissions. ::: ## Start a Studio session Select the three dots next to the status message for the Studio you want to start, then select **Start**. You can optionally change the configuration of the Studio, then select **Start in new tab**. Once the session is running, you can connect to it. A session will run until it is stopped manually or it encounters a technical issue. :::note A session consumes resources until it's **stopped**. ::: Once a Studio session is in a **running** state, you can connect to it, obtain a public link to the session to share with collaborators inside your workspace, and stop it. ## Start an existing Studio as a new session You can use any existing Studio as the foundation for adding a new session. This functionality creates a clone of the session, including its checkpoint history, preserving any modifications made to the original Studio. When you create a session in this way, future changes are isolated from the original session. When adding a new session from an existing session or checkpoint, the following fields cannot be changed: - **Studio template** - **Original Studio session and checkpoint** - **Compute environment** - **Installed Conda packages** - **Session duration** To add a new session from an existing **stopped** session, complete the steps described in [Add a Studio][add-s]. Additionally, you can add a new session from any existing Studio checkpoint except the currently running checkpoint. From the detail page, select the **Checkpoints** tab and in the **Actions** column, select **Add as new Studio**. This is useful for interactive analysis experimentation without impacting the state of the original Studio. ## Start a new session from a checkpoint You can start a new session from an existing stopped session. This will inherit the history of the parent checkpoint state. From the list of **stopped** Studios in your workspace, select the three dots next to the status message for the Studio you want to start and select **Add as new**. Alternatively, select the **Checkpoints** tab on the detail page, select the three dots in the **Actions** column, and then select **Add as new Studio** to start a new session. ## Stop a Studio session To stop a running session, select the three dots next to the status message and then select **Stop**. The status will change from **running** to **stopped**. When a session is stopped, the compute resources it's using are deallocated. You can stop a session at any time, except when it is **starting**. Stopping a running session creates a new checkpoint. ## Restart a stopped session When you restart a stopped session, the session uses the most recent checkpoint. ## Delete a Studio :::note This functionality is available to all user roles excluding the **View** role. ::: You can only delete a Studio when it's **stopped**. Select the three dots next to the status message and then select **Delete**. The Studio is deleted immediately and can't be recovered. ## Connect to a Studio To connect to a running session, select the three dots next to the status message and choose **Connect**. :::warning An active connection to a session will not prevent administrative actions that might disrupt that connection. For example, a session can be stopped by another workspace user while you are active in the session, the underlying credentials can be changed, or the compute environment can be deleted. These are independent actions and the user in the session won't be alerted to any changes - the only alert will be a server connection error in the active session browser tab. ::: Once connected, the session will display the status of **running** in the list, and any connected user's avatar will be displayed under the status in both the list of Studios and in each Studio's detail page. ## Collaborate in a Studio session :::note Collaborators need valid workspace permissions to connect to the running Studio. ::: To share a link to a running session with collaborators inside your workspace, select the three dots next to the status message for the session you want to share, then select **Copy Studio URL**. Using this link, other authenticated users can access the session directly. Seqera-managed container templates offer varying levels of multi-user collaboration: - **JupyterLab:** Supports multi-user collaboration via the `jupyter-collaboration` package. Each connected user has a randomly assigned color-coded avatar and the user cursor inherits the same color for easily differentiating multiple connected users. - **VS Code:** Supports multi-user collaboration by default, but each connected user is not readily distinguishable. For a more fully-featured collaborative experience, install the [Microsoft Live Share extension][liveshare] or [P2P Live Share][p2p-liveshare]. - **R-IDE:** By default, multi-user collaboration is not supported. When an additional user connects to the running session, the previously connected user is notified and forcibly disconnected. - **Xpra:** Supports multi-user collaboration by default and is similar to a remote desktop experience. Connected users are not readily distinguishable. :::note RStudio Professional Server supports multi-user collaboration. Add your own custom container and include your Posit Workbench license code as a environment variable to take advantage of this. ::: Multi-user collaboration in custom containers is dependent on the container configuration. ## Limit Studio access to a specific cloud bucket subdirectory {#cloud-bucket-subdirectory} For a cloud bucket that is writeable, as enabled by including the bucket in a compute environment's **Allowed S3 bucket** list, you can limit write access to that bucket from within a Studio session. To limit read-write access to a specific subdirectory, complete the following steps: 1. From your Seqera instance, select the **Data Explorer** tab. 1. Select **Add Cloud Bucket**. 1. Complete the following fields: - **Provider**: Select your cloud provider. - **Bucket path**: Enter the full path to the subdirectory of the bucket that you want to use with your Studio, such as `s3://1000genomes/data`. - **Name**: Enter a name for this cloud bucket, such as *1000-genomes-data-dir*, to indicate the bucket name and subdirectory path. - **Credentials**: Select your provider credentials. - Optional: **Description**: Enter a description for this cloud bucket. 1. Select **Add** to create a custom data-link to a subdirectory in the cloud bucket. When defining a new Studio, you can configure the **Mounted data** by selecting the custom data-link created by the previous steps. ## Migrate a Studio from an earlier container image template :::warning Due to the nature of fully customizable, containerized applications, users can modify environments leading to a variety of configurations and outcomes. This is therefore a best effort to support Studio migrations and a successful outcome is not guaranteed. ::: As Studios matures and new versions of JupyterLab, R-IDE, Visual Studio Code, and Xpra are released, new Seqera-provided image templates will be periodically released including updated versions of Seqera Connect. The most recent container template images will be tagged `recommended` and earlier template images will be tagged `deprecated`. Temporary container templates tagged with `experimental` are not supported and should not be used in production environments. :::tip Always use the `recommended` tagged template image for new Studios. Only two earlier minor versions of [Seqera Connect][connect] are supported by Seqera. ::: To migrate a Studio to a more recent container version and Seqera Connect: 1. Select the Studio to migrate. 1. Select **Add as new**. By default this selects the latest session checkpoint. 1. In the **General config** section, change the image template selection in the drop-down list to use the `latest` tagged version of the same interactive environment. 1. For the **Summary** section, ensure that the specified configuration is correct. 1. Immediately start the new, duplicated Studio session by selecting **Add and start**. 1. **Connect** to the new running Studio session. 1. Make a note of any package or environment errors displayed. 1. **Stop** the running Studio session. 1. Go back to the original Studio: 1. **Start** the session. 1. **Connect** to the session. 1. Uninstall any packages related to the errors: 1. JupyterLab: Execute `!pip uninstall ` or `apt remove ` to uninstall system-level packages. 1. R-IDE: Execute `uninstall.packages("")` to uninstall R packages or `apt remove ` to uninstall system-level packages. 1. Visual Studio Code: Select the **Manage** gear button at the right of an extension entry and then choose **Uninstall** from the drop-down. 1. Xpra: Use `apt remove ` to uninstall system-level packages. 1. **Stop** the running Studio session. A new checkpoint is created. 1. Repeat Step 1 **Add as new** using the new, most recent created checkpoint from the steps above. ## Migrate a Studio between compute environments You can switch an existing Studio to a different compute environment from the Studio's **Edit** screen, provided the new compute environment has the same working directory as the current one. This works for any switch, for example scaling resources up or down, moving between regions, or changing compute environment types in the same cloud provider. You can migrate in place to preserve the Studio's checkpoints and state, or migrate from scratch to copy specific files into a fresh Studio. ### Migrate in place (recommended) Use this path to preserve the Studio's [checkpoint][checkpoints] history, installed packages, and session state. When the new compute environment points at the same `workDir` as the current one, the Studio's existing checkpoints in the `.studios/checkpoints` folder remain reachable. Switching the compute environment binds the Studio to the new one while preserving its checkpoints and state. :::note Object storage bucket names are globally unique within a single cloud provider but not across providers. In-place migration is therefore limited to compute environments in the same cloud provider, for example AWS Batch to AWS Cloud, both backed by S3. ::: :::info[**Prerequisites**] You need the following: - A stopped Studio. - A new compute environment in the `AVAILABLE` status, configured with the same `workDir` as the current one. - [Credentials][credentials] on the new compute environment with read and write access to the `workDir` bucket. ::: #### Steps 1. From the **Studios** tab, open the details for the Studio you want to migrate. 1. Select **Edit**. 1. In the **Compute environment** drop-down, select the new compute environment. 1. Review the resource labels on the form (see [Resource label changes](#resource-labels-on-migration)). 1. Save your changes. 1. Start the Studio. The new session restores from the latest checkpoint stored in the shared `workDir`. The **Compute environment** field is editable only on the **Edit** screen. The **Add** and **Start** screens keep the Studio bound to its original compute environment. #### Compatible compute environments The drop-down lists only compute environments compatible with the Studio's current one. A compute environment is compatible when it: - Uses the same `workDir` as the Studio's current compute environment. - Is in the `AVAILABLE` status. The Studio's current compute environment is always listed first, even when it would not be selectable on its own. #### Resource label changes {#resource-labels-on-migration} When you select a different compute environment, the form syncs the Studio's [resource labels][resource-labels]: - Labels inherited from the **previous** compute environment are removed. - Labels that belong to the **Studio itself** (not inherited from a compute environment) are preserved. - The **new** compute environment's resource labels are added. For example, you switch a Studio with labels `[ce-a-1, ce-a-2, studio-1]` from compute environment `CE-A` to compute environment `CE-B`, whose resource labels are `[ce-b-1]`. The Studio's labels become `[studio-1, ce-b-1]`. ### Migrate from scratch Use this path when you don't need the Studio's checkpoint history and only want to copy specific files, such as datasets, notebooks, or scripts, into a fresh Studio backed by the new compute environment. :::note This path does not carry over checkpoints, installed packages, or environment customizations from the original Studio. Copy anything you want to keep through a shared bucket. ::: Move files between the source and target Studios through a shared bucket that both compute environments can read and write. The following example uses AWS S3: 1. Start the existing Studio. Confirm that its compute environment lists a shared S3 bucket in **Allowed S3 buckets**, and that the bucket is mounted on the Studio as a [data link](#studio-session-data-links). 1. Inside the running Studio, copy any files you want to save into the mount at `/workspace/data/`. 1. Create the new compute environment configured with the same shared S3 bucket in **Allowed S3 buckets**, then [add a new Studio][add-s] that uses it. 1. Start the new Studio with the shared bucket mounted, then copy files from `/workspace/data/` into the local Studio workspace. For common migration issues, see [Studios troubleshooting][studios-troubleshooting]. :::tip [AWS Cloud][aws-cloud] is the recommended runtime for new Studios. It starts sessions faster and manages resources more simply than [AWS Batch][aws-batch] for single-VM Studio workloads. To switch an existing Studio from AWS Batch to AWS Cloud, use the in-place migration steps. ::: ## Studio session statuses Sessions have the following possible statuses: - **building**: When a custom environment is building the template image for a new session. The [Wave] service performs the build action. For more information on this status, see [Inspect custom container template build status][build-status]. - **build-failed**: When a custom environment build has failed. This is a non-recoverable error. Logs are provided to assist with troubleshooting. For more information on this status, see [Inspect custom container template build status][build-status]. - **starting**: The Studio is initializing. - **running**: When a session is **running**, you can connect to it, copy the URL, or stop it. In addition, the session can continue to process requests/run computations in the absence of an ongoing connection. - **stopping**: The recently-running session is in the process of being stopped. - **stopped**: When a session is stopped, the associated compute resources are deallocated. You can start or delete the session when it's in this state. - **errored**: This state most often indicates that there has been an error starting the session but it is in a **stopped** state. :::note There might be errors reported by the session itself but these will be overwritten with a **running** status if the session is still running. ::: ## Connect to a Studio via SSH (public preview) :::info[**Prerequisites**] - Enterprise v25.3.3 or later - [Studios SSH configuration](../enterprise/studios-ssh) enabled for your workspace during deployment - Your SSH public key added to your Seqera Platform user profile - **SSH Connection** toggle enabled when adding the Studio - The Studio is in a **running** state. - **Connect client**: Version 0.10.0 or later ::: Direct SSH connections to running Studio containers support standard SSH clients, terminal access, and [VS Code Remote SSH](https://code.visualstudio.com/docs/remote/ssh). JupyterLab, R-IDE, VS Code, and Xpra container templates are supported. :::note If you didn't enable SSH when you initially added your Studio, stop the Studio, select **Start as New**, and enable **SSH Connection**. ::: ### Terminal access Connect to a Studio using standard SSH: ```bash ssh @@ -p 2222 ``` **Example:** ```bash ssh alice@a01ac8894@connect.example.com -p 2222 ``` Where: - ``: Your Seqera Platform username - ``: The Studio session ID (visible in the Studios list) - ``: Your connect proxy domain - Port: `2222` (default SSH proxy port) The session ID is displayed in the Studio details page and the Studios list. ### VS Code Remote SSH Connect to a Studio using VS Code Remote SSH: 1. Install the [Remote - SSH extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) in VS Code. 2. **Required:** Disable local server mode in your VS Code settings: - Open VS Code Settings (Code > Preferences > Settings or Cmd+,) - Search for `remote.SSH.useLocalServer` - Set to `false` Alternatively, add this to your `settings.json`: ```json { "remote.SSH.useLocalServer": false, "remote.SSH.enableRemoteCommand": true, "remote.SSH.useLocalServer": false, "remote.SSH.preconnect": "" } ``` :::warning VS Code's local server mode (SSH multiplexing over SOCKS) is not supported. Connections will fail if this setting is enabled. ::: 3. Connect to the Studio: - Open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P) - Run **Remote-SSH: Connect to Host** - Select your configured host or enter the SSH connection string directly - VS Code opens a new window connected to your Studio Once connected, you can: - Access the Studio filesystem - Open folders and files - Use the integrated terminal - Install VS Code extensions in the remote environment - Debug code running in the Studio - Install packages ### Claude Code desktop app The Claude Code desktop app requires later Connect versions than other SSH connection methods. :::info[**Prerequisites**] You need the following: - Connect server and proxy version 0.12.1 or later - Connect client version 0.13.0 or later ::: The app reads `~/.ssh/config`, but its **SSH Host** field accepts a hostname only. It cannot parse the `@` pair. Define a host alias, then reference the alias in the app. 1. Add an entry to `~/.ssh/config`: ``` Host my-studio HostName connect.example.com User alice@a01ac8894 Port 2222 IdentityFile ~/.ssh/id_ed25519 ``` Put the `@` pair in `User`, and only the connect domain in `HostName`. 2. Add an SSH connection in the app: - **SSH Host**: `my-studio` - **SSH Port**: `2222` :::warning Set **SSH Port** explicitly. The app ignores the `Port` value in `~/.ssh/config` and defaults to port 22. The connection then fails with a handshake timeout. ::: If the connection fails, see [SSH connections](../troubleshooting_and_faqs/studios_troubleshooting#ssh-connections-public-preview). ### SSH authentication SSH connections use public key authentication: 1. Platform validates your credentials and workspace permissions. 2. Your SSH client uses your private key for authentication. 3. The connection is encrypted end-to-end. For troubleshooting SSH connection issues, see [Studios troubleshooting](../troubleshooting_and_faqs/studios_troubleshooting#ssh-connections-public-preview). ## Studio session data-links You can configure a Studio session to mount one or more data-links, where cloud buckets that you have configured in your compute environment are read-only, or read-write available to the session. If your compute environment includes a cloud bucket in the **Allowed S3 bucket** list, the bucket is writeable from within a session when that bucket is included as a data-link. You can limit write access to just a subdirectory of a bucket by creating a custom data-link for only that subdirectory in Data Explorer, and then mount the data-link to the Studio session. For example, if you have the following S3 buckets: - `s3://biopharmaXs`: Entire bucket - `s3://biopharmaX/experiments/project-A/experiment-1/data`: Subdirectory to mount in a Studio session Mounted data links are exposed at the `/workspace/data/` directory path inside a Studio session. For example, the bucket subdirectory `s3://biopharmaX/experiments/project-A/experiment-1/data`, when mounted as a data-link, is exposed at `/workspace/data/biopharmaxs-project-a-experiment-1-data`. For more information, see [Limit Studio access to a specific cloud bucket subdirectory][cloud-bucket-subdirectory]. ## Studio session checkpoints When starting a Studio session, a *checkpoint* is automatically created. A checkpoint saves all changes made to the root filesystem and stores it in the attached compute environment's pipeline work directory in the `.studios/checkpoints` folder with a unique name. The current checkpoint is updated every five minutes during a session. :::warning Checkpoints vary in size depending on libraries installed in your session environment. This can potentially result in many large files stored in the compute environment's pipeline work directory and saved to cloud storage. This storage will incur costs based on the cloud provider. Due to the architecture of Studios, you cannot delete any checkpoint files to save on storage costs. Deleting a Studio session's checkpoints will result in a corrupted Studio session that cannot be started nor recovered. ::: When you stop and start a session, or start a new session from a previously created checkpoint, changes such as installed software packages and configuration files are restored and made available. Changes made to mounted data are not included in a checkpoint. Checkpoints can be renamed and the name has to be unique per Studio. Spaces in checkpoint names are converted to underscores automatically. Checkpoint files in the compute environment work directory may be shared by multiple Studios. Each checkpoint file is cleaned up asynchronously after the last Studio referencing the checkpoint is deleted. :::note The cleanup process is a best effort and not guaranteed. Seqera attempts to remove the checkpoint, but it can fail if, for example, the compute environment credentials used do not have sufficient permissions to delete objects from storage buckets. ::: ## Session volume automatic resizing By default, a session allocates an initial 2 GB of storage. Available disk space is continually monitored and if the available space drops below a 1 GB threshold, the file system is dynamically resized to include an additional 2 GB of available disk space. This approach ensures that a session doesn't initially include unnecessary free disk space, while providing the flexibility to accommodate installation of large software packages required for data analysis. The maximum storage allocation for a session is limited by the compute environment disk boot size. By default, this is 30 GB. This limit is shared by all sessions running in the same compute environment. If the maximum allocation size is reached, it is possible to reclaim storage space using a snapshot. Stop the active session to trigger a snapshot from the active volume. The snapshot is uploaded to cloud storage with Fusion. When you start from the newly saved snapshot, all previous data is loaded, and the newly started session will have 2 GB of available space. {/* links */} [contact]: https://support.seqera.io/ [aws-cloud]: ../compute-envs/aws-cloud [aws-batch]: ../compute-envs/aws-batch [google-cloud]: ../compute-envs/google-cloud [custom-envs]: ./custom-envs [build-status]: ./custom-envs#build-status [cloud-bucket-subdirectory]: ./managing#cloud-bucket-subdirectory [checkpoints]: ./managing#studio-session-checkpoints [resource-labels]: ../troubleshooting_and_faqs/resource-labels [studios-troubleshooting]: ../troubleshooting_and_faqs/studios_troubleshooting [credentials]: ../credentials/overview [ds-jupyter]: https://public.cr.seqera.io/repo/platform/data-studio-jupyter [ds-ride]: https://public.cr.seqera.io/repo/platform/data-studio-ride [def-vsc]: https://code.visualstudio.com/ [Nextflow]: https://nextflow.io/ [nf-lang-server]: https://marketplace.visualstudio.com/items?itemName=nextflow.nextflow [ds-vscode]: https://public.cr.seqera.io/repo/platform/data-studio-vscode [def-xpra]: https://github.com/Xpra-org/xpra [ds-xpra]: https://public.cr.seqera.io/repo/platform/data-studio-xpra [Wave]: https://seqera.io/wave/ [build-status]: ./custom-envs#build-status [add-s]: ./add-studio [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [connect]: ./connect [liveshare]: https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare [p2p-liveshare]: https://open-vsx.org/extension/kermanx/p2p-live-share --- ## Overview(Studios) Studios provides interactive analysis environments that pair a container image with a compute environment and your preferred tools, such as JupyterLab, an R-IDE, Visual Studio Code, or Xpra remote desktops. Each Studio session runs as an individual interactive environment for live data analysis. :::note Studios in Enterprise is not enabled by default. To enable it, see [Deploy Studios in Seqera Platform](../enterprise/install-studios). ::: - [Container image templates](./container-images): Provided templates for JupyterLab, R-IDE, Visual Studio Code, and Xpra. - [Custom environments](./custom-envs): Augment the Seqera-provided images with Conda packages or your own base container template image. - [Add a Studio](./add-studio): Configuration options for creating, running, and customizing Studio sessions. - [Manage Studios](./managing): Manage Studios and collaborator access. - [Connect changelog](./connect): Release notes for the Seqera Connect client. :::note Studios supports [AWS Cloud][aws-cloud], [Google Cloud][google-cloud], and [AWS Batch][aws-batch] compute environments that **do not** have Fargate enabled. ::: {/* links */} [aws-cloud]: ../compute-envs/aws-cloud [aws-batch]: ../compute-envs/aws-batch [google-cloud]: ../compute-envs/google-cloud [contact]: https://support.seqera.io/ --- ## Tower Agent Tower Agent connects Seqera Platform to high-performance computing (HPC) clusters that do not accept inbound SSH connections. ## When to use the agent Use Tower Agent if your HPC cluster has any of these constraints: - **No public-facing login node.** The cluster is behind a bastion host, VPN, or jump server, with login nodes that have no routable public IP. - **Strict inbound firewall rules.** Security teams allow outbound traffic but block unsolicited inbound connections, including SSH from third parties. - **Multi-factor authentication.** Login requires a hardware token or TOTP. Automated SSH from an external service is impractical. - **Air-gapped or regulated environments.** Clinical, pharmaceutical, and regulated research clusters are often isolated for compliance. - **No shared service accounts.** Some institutions require every job to run under an individual user identity rather than a shared account. If your cluster accepts inbound SSH from Seqera Platform, the standard SSH-based or managed-identity compute environment is simpler to operate (no persistent process to manage). Use Tower Agent when SSH is not an option. ## Connection model The default Seqera Platform HPC model opens an SSH connection to the cluster login node, submits the Nextflow head job, and monitors execution from there. That model requires the cluster to be reachable from the internet. Tower Agent reverses the connection direction. The agent runs on a node that can submit jobs to the scheduler (typically the login node) and opens a persistent outbound authenticated WebSocket connection to Seqera. Seqera sends pipeline commands (submit jobs, check status, stream logs) through that channel. The agent executes them locally as the user who started it. ```mermaid flowchart RL subgraph login["Login node"] direction TB agent["tw-agent"] scheduler["Slurm / LSF / PBS Pro / Grid Engine"] workers["Worker nodes"] agent -->|submits| scheduler scheduler --> workers end login ==>|outbound secure channel| seqera["Seqera Platform(Cloud or Enterprise)"] ``` This approach has three properties: - **Jobs run as you.** The agent submits to the scheduler as the Linux user who launched it. Job accounting, quotas, and audit logs reflect the correct identity, with no shared service account. - **No new firewall rules required.** The cluster only needs outbound HTTPS, the same traffic any browser already makes. - **Credentials stay on the cluster.** SSH keys, Kerberos tickets, and scheduler credentials never leave the cluster. Seqera does not authenticate to your HPC. The agent authenticates locally. Seqera Platform handles pipeline launch, monitoring, logs, resource metrics, and run reports. The agent forwards commands and returns results. ## Connect an HPC cluster Connecting your cluster to Seqera Platform takes six steps: generate an access token, create credentials, install the agent on a login node, start it under tmux, create an HPC compute environment, and launch a pipeline. Complete them in order. :::info[**Prerequisites**] You need the following: - SSH access to a login node, or any node that can submit jobs to your scheduler. - Outbound HTTPS access from that node to your Seqera Platform API endpoint. - A Seqera Platform account with a workspace you can add credentials to. ::: ### Generate a personal access token The agent authenticates to Seqera Platform with a personal access token (PAT) tied to your user account. 1. Log in to Seqera Platform. 2. Open your user menu and select **Your tokens**. 3. Select **Add token**, give it a descriptive name (for example, `hpc-agent-token`), and create it. 4. Copy the token immediately. You cannot view it again after leaving the page. ### Create Tower Agent credentials Create a Tower Agent credential in the workspace where you run pipelines. The agent uses the credential's connection ID to identify itself to Seqera Platform. 1. In your workspace, go to **Credentials** and select **Add credentials**. 2. Select **Tower Agent** as the provider. 3. Enter a name for the credential. 4. Accept the auto-generated **Agent Connection ID** or enter a custom one. Note it down. The ID in the credential must exactly match the ID you pass when starting the agent. 5. To let a single agent serve all workspace members, enable **Shared agent**. For per-user identity on submitted jobs, leave this disabled and ask each user to run their own agent. 6. Select **Add**. ### Install the agent on the login node The agent is a single self-contained binary with no other dependencies to install. 1. SSH into the login node and download the latest agent binary: ```bash curl -fSL https://github.com/seqeralabs/tower-agent/releases/latest/download/tw-agent-linux-x86_64 > tw-agent chmod +x ./tw-agent ``` 2. Optionally, move it to a directory in your `$PATH`: ```bash mkdir -p ~/bin mv tw-agent ~/bin/ ``` 3. Create the default work directory if it does not already exist: ```bash mkdir -p ~/work ``` :::note On most HPC clusters, home directories have small quotas. Use `--work-dir` to point the agent at a scratch filesystem (for example, `/scratch/$USER/nextflow-work`). ::: ### Start the agent inside tmux The agent must run continuously to accept incoming requests from Seqera. If you run it directly in an SSH session and disconnect, the process exits when the session closes. The standard solution on HPC is a terminal multiplexer. Both [tmux](https://github.com/tmux/tmux) and [GNU Screen](https://www.gnu.org/software/screen/) decouple processes from the terminal that started them. Your session runs inside a background server on the login node, and your terminal attaches to that server. If you detach or get disconnected, the session keeps running. SSH back in later and reattach to resume. Start a new tmux session: ```bash tmux new -s tower-agent ``` Inside tmux, export your access token and start the agent with your connection ID: ```bash export TOWER_ACCESS_TOKEN= ./tw-agent ``` For Seqera Platform Enterprise, also set your API endpoint: ```bash export TOWER_ACCESS_TOKEN= export TOWER_API_ENDPOINT=https://platform.yourcompany.com/api ./tw-agent ``` When the agent logs that it has connected to Seqera Platform, detach from tmux with **Ctrl-b**, then **d**. You return to the login shell, and the agent keeps running in the background. Verify the session is still active: ```bash tmux ls # tower-agent: 1 windows (created ...) [detached] ``` You can now log out. The agent keeps running. :::tip[tmux quick reference] | Action | Command | |---|---| | Start a new named session | `tmux new -s agent` | | Detach from current session | Ctrl-b then d | | List existing sessions | `tmux ls` | | Reattach to a session | `tmux attach -t agent` | | Kill a session | `tmux kill-session -t agent` | ::: :::note If your site reboots login nodes on a schedule, restart the agent afterwards. Some clusters support systemd user services for persistent processes. Check with your HPC administrators if tmux is not sufficient for your site. ::: ### Create an HPC compute environment Create an HPC compute environment that uses your Tower Agent credential. Seqera routes every pipeline launch in this environment through the agent. In Seqera Platform: 1. Go to **Compute environments** and select **Add compute environment**. 2. Select your HPC scheduler (Slurm, LSF, PBS Pro, or Grid Engine). 3. Under **Credentials**, select the Tower Agent credential you created earlier. 4. Set the work directory to a path the agent can access on the login node. 5. Complete the remaining fields: head queue, compute queue, and any environment variables or run scripts your site requires. 6. Select **Create**. Seqera validates the environment by running a test command through the agent. See [HPC compute environments](../../compute-envs/hpc) for full field descriptions. ### Launch a pipeline Select a pipeline from your workspace **Launchpad**, select your new HPC compute environment, and launch. Seqera sends the launch request to the agent. The agent submits the Nextflow head job to your scheduler, and the head job dispatches tasks to compute nodes. You get the same monitoring, logs, and metrics as any other compute environment. ## Configuration reference ### CLI options Run the agent with a connection ID and any options: ```bash tw-agent [OPTIONS] AGENT_CONNECTION_ID ``` **Parameters** | Parameter | Description | |---|---| | `AGENT_CONNECTION_ID` | Agent connection ID that identifies this agent. Must match the **Agent Connection ID** in the credential. | **Options** | Option | Default | Description | |---|---|---| | `-t`, `--access-token=` | — | Seqera personal access token. Required unless `TOWER_ACCESS_TOKEN` is set. | | `-u`, `--url=` | — | Seqera API endpoint URL. If not set, `TOWER_API_ENDPOINT` is used. | | `-w`, `--work-dir=` | `~/work` | Path where pipeline scratch data is stored. You can change it when launching a pipeline. | | `-h`, `--help` | — | Show the help message and exit. | | `-V`, `--version` | — | Print version information and exit. | ### Environment variables The agent reads the following environment variables: | Variable | Description | |---|---| | `TOWER_ACCESS_TOKEN` | Seqera personal access token. Required if `--access-token` is not set. | | `TOWER_API_ENDPOINT` | Seqera API endpoint URL. Required for Enterprise deployments if `--url` is not set. | | `TOWER_AGENT_HEARTBEAT` | Heartbeat interval in seconds. Defaults to `45`. Reduce this value if your network drops idle connections. | ## Troubleshooting For agent and connection issues, see [Tower Agent troubleshooting](../../troubleshooting_and_faqs/troubleshooting#tower-agent). --- ## Illumina DRAGEN DRAGEN is a platform provided by Illumina that offers accurate, comprehensive, and efficient secondary analysis of next-generation sequencing (NGS) data with a significant speed increase over tools that are commonly used for such tasks. The improved performance offered by DRAGEN is possible due to the use of Illumina proprietary algorithms in conjunction with a special type of hardware accelerator called field programmable gate arrays (FPGAs). For example, when using AWS, FPGAs are available via the [F1 instance type](https://aws.amazon.com/ec2/instance-types/f1/). ## Run DRAGEN on Seqera Platform We have extended the [Batch Forge](../../compute-envs/aws-batch#automatic-configuration-of-batch-resources) feature for AWS Batch to support DRAGEN. Batch Forge ensures that all of the appropriate components and settings are automatically provisioned when creating an AWS Batch [compute environment](../../compute-envs/aws-batch#automatic-configuration-of-batch-resources). When deploying data analysis workflows, some tasks will need to use normal instance types (e.g., for non-DRAGEN processing of samples) and others will need to be executed on F1 instances. If the DRAGEN feature is enabled, Batch Forge will create an additional AWS Batch compute queue which only uses F1 instances, to which DRAGEN tasks will be dispatched. ## Get started To showcase the capability of this integration, we have implemented a proof of concept pipeline called [*nf-dragen*](https://github.com/seqeralabs/nf-dragen). To run it, sign into Seqera Platform, navigate to the [Community Showcase](https://tower.nf/orgs/community/workspaces/showcase/launchpad) and select the *nf-dragen* pipeline. You can run this pipeline at your convenience without any extra setup. Note however that it will be deployed in the compute environment owned by the Community Showcase. To deploy the pipeline on your own AWS cloud infrastructure, follow the instructions in the next section. ## Deploy DRAGEN in your own workspace DRAGEN is a commercial technology provided by Illumina, so you will need to purchase a license from them. To run on Seqera, you will need to obtain the following information from Illumina: 1. DRAGEN AWS private AMI ID 2. DRAGEN license username 3. DRAGEN license password Batch Forge automates most of the tasks required to set up an AWS Batch compute environment. See [AWS Batch](../../compute-envs/aws-batch) for more details. In order to enable support for DRAGEN acceleration, simply toggle the **Enable DRAGEN** option when setting up the compute environment via Batch Forge. In the **DRAGEN AMI ID** field, enter the AWS AMI ID provided by Illumina. Then select the instance type from the drop-down. :::note The Region you select must contain DRAGEN F1 instances. ::: ## Using DRAGEN v4.4.4 AMI with F2 instances You can deploy DRAGEN pipelines on Seqera Platform using AWS F2 instances with the DRAGEN v4.4.4 AMI. This enables access to the latest DRAGEN features and improved performance. For Seqera Platform Enterprise, F2 instance support starts from version 25.2.0. ### Configuration steps Before launching the pipeline, you need to add a new library mount in the Nextflow configuration. This is done via **Advanced options > Nextflow config** in the Seqera Platform UI. If you are using Fusion: ``` aws.batch.volumes = '/scratch/fusion:/tmp,/opt/edico,/var/lib/edico,/lib64/libdragen.so.4.4.4' ``` If you are not using Fusion: ``` aws.batch.volumes = '/opt/edico,/var/lib/edico,/lib64/libdragen.so.4.4.4' ``` :::note The DRAGEN v4.4.4 AMI must be selected when configuring your environment. Ensure your AWS Region supports F2 instances and the DRAGEN v4.4.4 AMI. ::: ## Pipeline implementation and deployment See the [dragen.nf](https://github.com/seqeralabs/nf-dragen/blob/master/modules/local/dragen.nf) module implemented in the [nf-dragen](https://github.com/seqeralabs/nf-dragen) pipeline for reference. Any Nextflow processes that run DRAGEN must: 1. Define the `dragen` label in your Nextflow process: The `label` directive allows you to annotate a process with mnemonic identifiers of your choice. Seqera will use the `dragen` label to determine which processes need to be executed on DRAGEN F1 instances. ``` process DRAGEN { label 'dragen' } ``` See the [Nextflow label docs](https://docs.seqera.io/nextflow/process.html?highlight=label#label) for more information. 2. Define secrets in Seqera: At Seqera, we use secrets to safely encrypt sensitive information when running licensed software via Nextflow. This enables our team to use the DRAGEN software safely via the `nf-dragen` pipeline without the need to configure the license key. These secrets will be provided securely to the `--lic-server` option when running DRAGEN on the CLI to validate the license. In the nf-dragen pipeline, we have defined two secrets called `DRAGEN_USERNAME` and `DRAGEN_PASSWORD`, which you can add to Seqera from the [Secrets](../../secrets/overview) tab. ## Limitations DRAGEN integration with Seqera Platform is currently only available for use on AWS, however, we plan to extend the functionality to other supported platforms like Azure in the future. --- ## Fusion v2 file system Fusion v2 is a lightweight container-based client that enables containerized tasks to access data in Amazon S3, Google Cloud, or Azure Blob Storage buckets using POSIX file access semantics. Depending on your data handling requirements, Fusion can improve pipeline throughput and reduce cloud computing costs. See [here](https://docs.seqera.io/fusion) for more information on Fusion's features. ### Fusion mechanics The Fusion file system implements a lazy download and upload algorithm that runs in the background to transfer files in parallel to and from object storage into a container-local temporary folder. This means that the performance of the disk volume used to carry out your computation is key to achieving maximum performance. By default, Fusion uses the container `/tmp` directory as a temporary cache, so the size of the volume can be much lower than the actual needs of your pipeline processes. Fusion has a built-in garbage collector that constantly monitors remaining disk space and deletes old cached entries when necessary. ### Fusion performance and cost considerations Fusion v2 improves pipeline throughput for containerized tasks by simplifying direct access to cloud data storage. Compute instance performance, local storage, and networking influence pipeline execution — the following guidelines are important when creating a compute environment that uses Fusion: - Fusion requires compute instances with attached local storage: - We recommend at least 200 GB storage with a random read speed of 1000 MBps or more. Machines with local disks that do not meet this requirement may encounter issues where local storage cannot keep up with streaming data. - Based on internal benchmarking, we recommend instances with 16 vCPUs and 128 GB memory or more for large, long-lived production pipelines. Seqera benchmarking runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. - Dedicated networking and fast I/O influence pipeline performance and are important to consider when selecting compute instances. ### Configure Seqera Platform compute environments with Fusion See the compute environment page for your cloud provider for Fusion configuration instructions: - [AWS Batch](../../compute-envs/aws-batch.md) - [Amazon EKS](../../compute-envs/eks.md) - [Azure Batch](../../compute-envs/azure-batch.md) - [Google Cloud Batch](../../compute-envs/google-cloud-batch.md) - [Google Kubernetes Engine](../../compute-envs/gke.md) --- ## Developer tools When working with the Seqera Platform API and tw CLI, you might encounter the following issues. ## API #### Maximum results returned ``` {object} length parameter cannot be greater than 100 (current value={value_sent}) ``` This error occurs when you request more results than the maximum page size of 100. To resolve, paginate the results across multiple API calls with the `max` and `offset` parameters: ```bash curl -X GET "https://$TOWER_SERVER_URL/workflow/$WORKFLOW_ID/tasks? workspaceId=$WORKSPACE_ID&max=100" \ -H "Accept: application/json" \ -H "Authorization: Bearer $TOWER_ACCESS_TOKEN" curl -X GET "https://$TOWER_SERVER_URL/workflow/$WORKFLOW_ID/tasks? workspaceId=$WORKSPACE_ID&max=100&offset=100" \ -H "Accept: application/json" \ -H "Authorization: Bearer $TOWER_ACCESS_TOKEN" ``` ## tw CLI #### Connection errors with AWS Batch compute environments Creating or viewing an AWS Batch compute environment that uses the `SPOT_PRICE_CAPACITY_OPTIMIZED` [allocation strategy](../compute-envs/aws-batch#advanced-options) fails on tw CLI versions earlier than v0.8, which don't support it. To resolve, upgrade to CLI v0.9 or later, where this was [addressed](https://github.com/seqeralabs/tower-cli/issues/332). #### Segmentation faults Legacy tw CLI versions can produce segmentation faults on older operating systems. To resolve, upgrade the tw CLI to the latest version. If the fault persists, use the Java [JAR-based build](https://github.com/seqeralabs/tower-cli/releases/download/v0.8.0/tw.jar). #### `You are trying to connect to an insecure server…` ``` ERROR: You are trying to connect to an insecure server: http://hostname:port/api if you want to force the connection use '--insecure'. NOT RECOMMENDED! ``` This error occurs when your Seqera host accepts connections over insecure HTTP instead of HTTPS. To resolve, configure the host to accept HTTPS connections. If it can't, add the `--insecure` flag **before** the CLI command: ```bash tw --insecure info ``` :::caution HTTP must not be used in production environments. ::: #### Relaunch a run Relaunch a run with the [`tw runs relaunch`](../launch/cache-resume#relaunch-a-workflow-run) command: ``` tw runs relaunch -i 3adMwRdD75ah6P -w 161372824019700 Workflow 5fUvqUMB89zr2W submitted at [org / private] workspace. tw runs list -w 161372824019700 Pipeline runs at [org / private] workspace: ID | Status | Project Name | Run Name | Username | Submit Date ----------------+-----------+----------------+-----------------+-------------+------------------------------- 5fUvqUMB89zr2W | SUBMITTED | nf/hello | magical_darwin | seqera-user | Tue, 10 Sep 2022 14:40:52 GMT 3adMwRdD75ah6P | SUCCEEDED | nf/hello | high_hodgkin | seqera-user | Tue, 10 Sep 2022 13:10:50 GMT ``` --- ## Authentication(Troubleshooting_and_faqs) When configuring authentication for Seqera Platform, you might encounter the following issues. ## SCIM provisioning These issues apply to SCIM group provisioning with [Okta](../enterprise/configuration/authentication/idp-delegation/group-catalog/scim-okta) and [Entra ID](../enterprise/configuration/authentication/idp-delegation/group-catalog/scim-entra-id). #### Groups appear in the identity provider but not in Platform This issue occurs when the bearer token configured in your identity provider doesn't match the current Platform token. Generating a new token in Platform revokes the previous one. To resolve, confirm the token in your identity provider matches the current Platform token, and replace it if necessary. #### `401 Unauthorized` in provisioning logs This error occurs when the bearer token is invalid or expired. To resolve, generate a new token in Platform and replace it in your identity provider. #### `409 Conflict` on a specific group This error occurs when a group with the same display name already exists in another organization on the same Enterprise instance. See [Multi-organization routing](../enterprise/configuration/authentication/idp-delegation/multi-org-routing) for the cross-organization uniqueness rule and conflict resolution. #### Catalog shows GUID-style identifiers instead of group names This issue occurs when Entra ID emits group object IDs rather than display names. To resolve, configure Entra ID to emit display names. See [Group display names vs. object IDs](../enterprise/configuration/authentication/idp-delegation/group-catalog/scim-entra-id#group-display-names-vs-object-ids). #### A group assigned in Entra ID doesn't sync This issue occurs when the provisioning scope excludes the group. To resolve, set the scope to **Sync only assigned users and groups** and confirm the group is listed directly under **Users and groups**, not nested inside another assigned group. ## OpenID Connect #### OpenID Connect (OIDC) login fails with a 500 error in the frontend logs The OIDC callback request can contain large HTTP headers that exceed the buffer size, which causes login failures: ```console *8317 upstream sent too big header while reading response header from upstream, client: 10.170.157.186, server: localhost, request: "GET /oauth/callback ``` To resolve, rebuild the frontend container and add the following proxy directives to `/etc/nginx/nginx.conf`: ```nginx proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; ``` #### OIDC callback failure OIDC callbacks can fail for several reasons. To investigate: - Set the authentication logging level environment variable to `TOWER_SECURITY_LOGLEVEL=DEBUG`. - Ensure your `TOWER_OIDC_CLIENT`, `TOWER_OIDC_SECRET`, and `TOWER_OIDC_ISSUER` environment variables all match the values specified in your OIDC provider application. - Ensure your network infrastructure allows the necessary egress and ingress traffic. #### OIDC `redirect_url` set to HTTP instead of HTTPS This can occur for several reasons. Verify the following: - Your `TOWER_SERVER_URL` environment variable uses the `https://` prefix. - Your `tower.yml` has `micronaut.ssl.enabled` set to `true`. - Any Load Balancer instance that sends traffic to Seqera Enterprise is configured to use HTTPS as its backend protocol rather than HTTP/TCP. ## HPC cluster authentication #### `Exhausted available authentication methods` with HPC clusters This error indicates a problem with the SSH credentials that authenticate Seqera to your HPC cluster (such as LSF or Slurm), such as an invalid SSH key or incorrect permissions on the user directory. Check the following: - Ensure the SSH key is still valid. If not, create new SSH keys and [re-create the compute environment](../compute-envs/hpc) in Seqera with the updated credentials. - Check the backend logs for a stack trace similar to the following:
Error log ```console [io-executor-thread-2] 10.42.0.1 ERROR i.s.t.c.GlobalErrorController - Unexpected error while processing - Error ID: 5d7rDpS8pByF8YqfUVPvB4 net.schmizz.sshj.userauth.UserAuthException: Exhausted available authentication methods at net.schmizz.sshj.SSHClient.auth(SSHClient.java:227) at net.schmizz.sshj.SSHClient.authPublickey(SSHClient.java:342) at net.schmizz.sshj.SSHClient.authPublickey(SSHClient.java:360) at io.seqera.tower.service.platform.ssh.SSHClientFactory.createClient(SSHClientFactory.groovy:110) .. .. Caused by: net.schmizz.sshj.userauth.UserAuthException: Problem getting public key from PKCS5KeyFile{resource=[PrivateKeyStringResource]} at net.schmizz.sshj.userauth.method.KeyedAuthMethod.putPubKey(KeyedAuthMethod.java:47) at net.schmizz.sshj.userauth.method.AuthPublickey.buildReq(AuthPublickey.java:62) at net.schmizz.sshj.userauth.method.AuthPublickey.buildReq(AuthPublickey.java:81) at net.schmizz.sshj.userauth.method.AbstractAuthMethod.request(AbstractAuthMethod.java:68) at net.schmizz.sshj.userauth.UserAuthImpl.authenticate(UserAuthImpl.java:73) at net.schmizz.sshj.SSHClient.auth(SSHClient.java:221) ... 91 common frames omitted Caused by: net.schmizz.sshj.userauth.keyprovider.PKCS5KeyFile$FormatException: Length mismatch: 1152 != 1191 at net.schmizz.sshj.userauth.keyprovider.PKCS5KeyFile$ASN1Data.(PKCS5KeyFile.java:248) ```
- Enable SSH library log tracing with the following environment variable in your `tower.env` file for verbose debug logging of the SSH connection: ```bash TOWER_SSH_LOGLEVEL=TRACE ``` - Check the permissions of the `/home` directory of the user tied to the cluster's SSH credentials. `/home/` should be `chmod 755`, whereas `/home//.ssh` requires `chmod 700`: ```console $ pwd ; ls -ld . /home/user drwxr-xr-x 41 user user 20480 $ pwd; ls -ld . /home/user/.ssh drwx------ 2 user user 4096 ``` --- ## AWS When running pipelines on AWS, you might encounter the following issues. ## Elastic Block Store (EBS) #### Volumes remain active after job completion On large AWS Batch clusters (hundreds of compute nodes or more), EC2 API rate limits can cause the automatic deletion of unattached EBS volumes to fail. Orphaned volumes that remain after jobs complete incur additional costs. EBS autoscaling relies on an AWS-provided script on each container host that calls the EC2 API to delete each volume when its job finishes. When deletion fails, find orphaned volumes in the EC2 console or with a Lambda function and delete them manually. See [Controlling your AWS costs by deleting unused Amazon EBS volumes](https://aws.amazon.com/blogs/mt/controlling-your-aws-costs-by-deleting-unused-amazon-ebs-volumes/). ## Elastic Container Service (ECS) #### ECS agent Docker image pull frequency When Batch Forge creates an AWS Batch environment, it sets the ECS agent's `ECS_IMAGE_PULL_BEHAVIOUR` in the EC2 launch template: - Seqera Enterprise v22.01 or later: `once` - Seqera Enterprise v21.12 or earlier: `default` See the [AWS ECS documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html) for the difference between these values. :::note This behavior can't be changed within Seqera Platform. ::: ## Container errors #### `CannotPullContainerError … "Too Many Requests (HAP429)"` ``` CannotPullContainerError: Error response from daemon: error parsing HTTP 429 response body: invalid character 'T' looking for beginning of value: "Too Many Requests (HAP429)" ``` This error occurs when you exceed Docker Hub's rate limit of 100 anonymous pulls per 6 hours. To resolve, add the following to your launch template: ```bash echo ECS_IMAGE_PULL_BEHAVIOR=once >> /etc/ecs/ecs.config ``` #### `CannotInspectContainerError` ``` Essential container in task exited - CannotInspectContainerError: Could not transition to inspecting; timed out after waiting 30s ``` To resolve: 1. Upgrade your [ECS agent](https://github.com/aws/amazon-ecs-agent/releases) to [1.54.1](https://github.com/aws/amazon-ecs-agent/pull/2940) or later. See [Check for ECS Container Instance Agent Version](https://www.trendmicro.com/cloudoneconformity/knowledge-base/aws/ECS/latest-agent-version.html) to check your version. 2. Provision more storage for your EC2 instance, preferably with EBS autoscaling for scalability. 3. If the error includes `command exit status: 123` and a permissions-denied error on a system command, make the ECS agent binary executable (`chmod u+x`). ## Queues #### Distribute tasks across multiple AWS Batch queues You can identify only a single work queue when you define an AWS Batch compute environment, but you can distribute tasks across multiple queues in your pipeline configuration. Add a snippet like the following to your `nextflow.config`, or the **Advanced options > Nextflow config file** field of the launch form, to distribute processes across two queues by name: ```groovy # nextflow.config process { withName: foo { queue: `TowerForge-1jJRSZmHyrrCvCVEOhmL3c-work` } } process { withName: bar { queue: `custom-second-queue` } } ``` ## GPUs #### `CUDA safe call. System has unsupported display driver / CUDA driver combination` ``` CUDA safe call. System has unsupported display driver / CUDA driver combination exiting ``` This error occurs when the container's CUDA runtime is newer than the NVIDIA driver on the compute environment's AMI. To resolve, do one of the following: - Update the AMI to one with a newer NVIDIA driver. Use the latest AWS-recommended GPU-optimized ECS AMI (the default when **Enable GPUs** is set), or build a custom AMI with a driver version that meets the container's CUDA requirement. See the [NVIDIA CUDA compatibility matrix](https://docs.nvidia.com/deploy/cuda-compatibility/) for the minimum driver version. - Pin the container to a supported CUDA version. Use a container image built against a CUDA runtime the installed driver supports. NVIDIA Parabricks, for example, publishes image tags for each CUDA version. Select one that matches the AMI's driver. To confirm the active driver on a failed task, see the **Driver version** field in [GPU metrics](../compute-envs/overview#gpu-metrics). ## Spot instances **Tasks fail with exit code `143`, or no exit code, and the log contains `Host EC2 (instance i-xxxxxxxxx) terminated`** AWS reclaimed the Spot instance running the task. See [Manage AWS Spot interruptions](../compute-envs/aws-spot-interruptions) for retry and fallback strategies. ## Storage #### Write to S3 buckets that enforce AES256 server-side encryption :::note Requires Seqera v21.10.4 and Nextflow [22.04.0](https://github.com/nextflow-io/nextflow/releases/tag/v22.04.0) or later. ::: To save files to an S3 bucket with a policy that [enforces AES256 server-side encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html), configure the [nf-launcher](https://quay.io/repository/seqeralabs/nf-launcher?tab=tags) script that invokes the Nextflow head job: 1. Add the following to the **Advanced options > Nextflow config file** field of the **Launch Pipeline** screen: ```groovy aws { client { storageEncryption = 'AES256' } } ``` 2. Add the following to the **Advanced options > Pre-run script** field: ```bash export TOWER_AWS_SSE=AES256 ``` --- ## Azure When running pipelines on Azure, you might encounter the following issues. ## Batch compute environments #### Use separate Batch pools for head and compute nodes The default Azure Batch implementation in Seqera Platform uses a single pool for head and compute nodes, and all jobs spawn dedicated (on-demand) VMs. To save costs by running compute jobs on low-priority VMs, use separate pools for head and compute jobs: 1. Create two Batch pools in Azure: - One dedicated pool - One [low-priority](https://learn.microsoft.com/en-us/azure/batch/batch-spot-vms#differences-between-spot-and-low-priority-vms) pool :::note Both pools must meet the requirements of a pre-existing pool, as detailed in the [Nextflow documentation](https://docs.seqera.io/nextflow/azure#requirements-on-pre-existing-named-pools). ::: 2. Create a manual [Azure Batch](../compute-envs/azure-batch#manual) compute environment in Seqera Platform. 3. In **Compute pool name**, specify your dedicated Batch pool. 4. Specify the low-priority pool with the `process.queue` [directive](https://docs.seqera.io/nextflow/process#queue) in your `nextflow.config` file, either through the launch form or your pipeline repository. ## Azure Kubernetes Service (AKS) #### `.../.git/HEAD.lock: Operation not supported` This error occurs when your Nextflow pod uses an Azure Files (SMB) persistent volume for storage. The `jgit` library that Nextflow uses attempts a filesystem link operation that Azure Files (SMB) [doesn't support](https://docs.microsoft.com/en-us/azure/storage/files/files-smb-protocol?tabs=azure-portal#limitations). To resolve, add the following to your pipeline's [**Pre-run script**](../launch/advanced#pre-and-post-run-scripts) field: ```bash cat < ~/.gitconfig [core] supportsatomicfilecreation = true EOT ``` ## SSL #### SSL CA certificate errors This can occur when a tool or library in your task container requires SSL certificates to validate an external data source. To resolve, mount the SSL certificates into the container. See [SSL/TLS](../enterprise/configuration/ssl_tls#configure-seqera-to-trust-your-private-certificate). #### `Connections using insecure transport are prohibited while --require_secure_transport=ON` This Azure SQL database error occurs because Azure's default MySQL configuration enforces SSL connections between the server and client, as described in [SSL/TLS connectivity in Azure Database for MySQL](https://learn.microsoft.com/en-us/azure/mysql/single-server/concepts-ssl-connection-security). To resolve, append `useSSL=true&enabledSslProtocolSuites=TLSv1.2&trustServerCertificate=true` to your `TOWER_DB_URL` connection string: ``` TOWER_DB_URL: jdbc:mysql://mysql:3306/tower?permitMysqlScheme=true/azuredatabase.com/tower?serverTimezone=UTC&useSSL=true&enabledSslProtocolSuites=TLSv1.2&trustServerCertificate=true ``` ## Azure Entra ID / OIDC #### `No enum constant … SELF_SIGNED_TLS_CLIENT_AUTH` On Seqera Platform v25.2.3 and earlier, Entra ID (Azure) authentication fails and the following error appears in the backend logs: ``` java.lang.IllegalArgumentException: No enum constant io.micronaut.security.oauth2.endpoint.AuthenticationMethod.SELF_SIGNED_TLS_CLIENT_AUTH** ``` This issue is caused by a change in Azure's supported authentication methods, which is incompatible with the OIDC library in older versions of Seqera Platform. To resolve, force the authentication method to `client_secret_post` by adding the following environment variable to your `tower.env` file or Kubernetes ConfigMap: ```bash MICRONAUT_SECURITY_OAUTH2_CLIENTS_OIDC_OPENID_TOKEN_AUTH_METHOD=client_secret_post ``` --- ## Datasets(Troubleshooting_and_faqs) When working with datasets, you might encounter the following issues. ## Common issues #### Dataset upload fails with the API When you upload a dataset through the Seqera UI or CLI, Seqera performs some steps automatically. Uploading through the API requires two additional steps: 1. Explicitly define the MIME type of the file you upload. 2. Make two API calls: first create a dataset object, then upload the samplesheet to it. Create the dataset object: ```bash curl -X POST "https://api.cloud.seqera.io/workspaces/$WORKSPACE_ID/datasets/" -H "Content-Type: application/json" -H "Authorization: Bearer $TOWER_ACCESS_TOKEN" --data '{"name":"placeholder", "description":"A placeholder for the data we will submit in the next call"}' ``` Upload the samplesheet to the dataset object: ```bash curl -X POST "https://api.cloud.seqera.io/workspaces/$WORKSPACE_ID/datasets/$DATASET_ID/upload" -H "Accept: application/json" -H "Authorization: Bearer $TOWER_ACCESS_TOKEN" -H "Content-Type: multipart/form-data" -F "file=@samplesheet_full.csv; type=text/csv" ``` :::tip You can also upload a dataset to a workspace with the [`tw` CLI](https://github.com/seqeralabs/tower-cli): ```bash tw datasets add --name "cli_uploaded_samplesheet" ./samplesheet_full.csv ``` ::: #### Datasets converted to `application/vnd.ms-excel` data type ``` "Given file is not a dataset file. Detected media type: 'application/vnd.ms-excel'. Allowed types: 'text/csv, text/tab-separated-values'" ``` This issue occurs in Firefox on Seqera versions earlier than 22.2.0. To resolve, upgrade to 22.2.0 or later, or use Chrome. #### TSV-formatted datasets not shown In Seqera version 22.2, TSV datasets were unavailable in the input data drop-down on the launch form. This was fixed in version 22.4.1. --- ## Nextflow When running Nextflow pipelines with Seqera Platform, you might encounter the following issues. ## Nextflow configuration #### Default Nextflow DSL version From [Nextflow 22.03.0-edge](https://github.com/nextflow-io/nextflow/releases/tag/v22.03.0-edge), DSL2 is the default syntax. To minimize disruption to existing pipelines, versions 22.1.x and later default Nextflow head jobs to DSL1 for a transition period (end date to be confirmed). Force your Nextflow head job to use DSL2 syntax with one of the following: - Add `export NXF_DEFAULT_DSL=2` in the **Advanced options > Pre-run script** field of the launch form. - Specify `nextflow.enable.dsl = 2` at the top of your Nextflow workflow file. - Provide the `-dsl2` flag when you invoke the Nextflow CLI, for example `nextflow run ... -dsl2`. #### Invoke Nextflow CLI run arguments during launch From [Nextflow v22.09.1-edge](https://github.com/nextflow-io/nextflow/releases/tag/v22.09.1-edge), you can specify [Nextflow CLI run arguments](https://docs.seqera.io/nextflow/cli.html?highlight=dump#run) when you launch a pipeline from Seqera. Set the `NXF_CLI_OPTS` environment variable in a [pre-run script](../launch/advanced#pre-and-post-run-scripts): ```bash export NXF_CLI_OPTS='-dump-hashes' ``` #### Cloud execution: `--outdir` artifacts not available Nextflow resolves relative paths against the current working directory. On a classic grid HPC, this is usually a subdirectory of `$HOME`. In a cloud execution environment, the path resolves relative to the _container file system_. Output files are lost when the container terminates. See [this Nextflow issue](https://github.com/nextflow-io/nextflow/issues/2661#issuecomment-1047259845) for details. To resolve, specify the absolute path to your persistent storage with the `NXF_FILE_ROOT` environment variable in your [`nextflow.config`](../launch/advanced#nextflow-config-file) file. Nextflow then resolves relative paths so that output files are written to persistent storage rather than ephemeral container storage. #### Ignore the Singularity cache To ignore the Singularity cache, add this to your workflow: `process.container = 'file:///some/singularity/image.sif'`. #### `Cannot read project manifest … path=nextflow.config` This warning occurs when the source Git repository's default branch does not contain `main.nf` and `nextflow.config` files, regardless of whether the pipeline uses a non-default revision or branch (e.g., `dev`). To resolve, create empty `main.nf` and `nextflow.config` files in the default branch. The pipeline can then run and use the `main.nf` and `nextflow.config` from your target revision. #### Use multiple configuration files for different environments The main `nextflow.config` file is always imported by default. Instead of managing multiple `nextflow.config` files, each customized for an environment, create environment-specific config files and import them as [config profiles](https://docs.seqera.io/nextflow/config#config-profiles) in the main `nextflow.config`: ```groovy profiles { test { includeConfig 'conf/test.config' } prod { includeConfig 'conf/prod.config' } uat { includeConfig 'conf/uat.config' } } ``` #### AWS S3 upload file size limits You might see the following message in your Nextflow log: ``` WARN: Failed to publish file: s3:// ``` These messages are often caused by AWS S3 object size limits when using multipart upload. See the [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html), particularly _maximum number of parts per upload_. To resolve, adjust the head job resources and configuration: - Head Job CPUs: 16 - Head Job Memory: 60000 - [Pre-run script](../launch/advanced#pre-and-post-run-scripts): `export NXF_OPTS="-Xms20G -Xmx40G"` - Increase the chunk size and slow the transfers in `nextflow.config`: ```groovy aws { batch { maxParallelTransfers = 5 maxTransferAttempts = 3 delayBetweenAttempts = 30 } client { uploadChunkSize = '200MB' maxConnections = 10 maxErrorRetry = 10 uploadMaxThreads = 10 uploadMaxAttempts = 10 uploadRetrySleep = '10 sec' } } ``` #### Nextflow cannot parse a params file ``` Cannot parse params file: /ephemeral/example.json - Cause: Server returned HTTP response code: 403 for URL: https://api.tower.nf/ephemeral/example.json ``` Ephemeral endpoints can be consumed only once. Nextflow versions earlier than 22.04 can call the same endpoint more than once, which causes this error. To resolve, upgrade Nextflow to version 22.04.x or later. #### Prevent uploading intermediate files to the AWS S3 work directory Nextflow only unstages files and folders that you explicitly define as process outputs. If your workflow has processes that generate folder-type outputs, ensure each process also purges any intermediate files in those folders. Otherwise, Nextflow copies the intermediate files during task unstaging. This adds storage costs and lengthens execution times. #### Values in the repository `nextflow.config` change during launch Some values in your pipeline repository's `nextflow.config` can change when the pipeline is launched from Seqera, because Seqera applies a set of default values that override the pipeline configuration. For example, this block is specified in your `nextflow.config`: ```groovy aws { region = 'us-east-1' client { uploadChunkSize = 209715200 // 200 MB } ... } ``` When the job starts on the AWS Batch compute environment, `uploadChunkSize` changes: ```groovy aws { region = 'us-east-1' client { uploadChunkSize = 10485760 // 10 MB } ... } ``` This happens because Seqera applies its 10 MB default instead of the value in your `nextflow.config`. To force the Seqera-invoked job to use your value, add the setting in the workspace launch form's [**Nextflow config file** field](../launch/launchpad). For the example above, add `aws.client.uploadChunkSize = 209715200 // 200 MB`. Values affected by this behavior include: - `aws.client.uploadChunkSize` - `aws.client.storageEncryption` #### `Missing output file(s) [X] expected by process [Y]` with Fusion v1 Fusion v1 causes tasks that run for less than 60 seconds to fail, because Nextflow doesn't yet detect the output file the task generated. This limitation is inherited from the Goofys driver used in the Fusion v1 implementation. [Fusion v2](../supported_software/fusion/overview) resolves this issue. If you can't update to Fusion v2, instruct Nextflow to wait 60 seconds after the task completes. In **Pipeline settings > Advanced options > Nextflow config file**, add: ```groovy process.afterScript = 'sleep 60' ``` #### Jobs remain in RUNNING status after canceling a run Your instance's behavior when you cancel a run depends on the Nextflow [`errorStrategy`](https://docs.seqera.io/nextflow/process#errorstrategy) defined in your process script. If `errorStrategy` is set to `finish`, canceling (or otherwise interrupting) a run starts an orderly shutdown, which instructs Nextflow to wait for submitted jobs to complete. To terminate all jobs when you cancel a run, set `errorStrategy` to `terminate` in your Nextflow config: ```groovy process terminateError { errorStrategy 'terminate' script: } ``` #### Cached tasks run from scratch on relaunch When you relaunch a pipeline, Seqera relies on Nextflow's `resume` functionality to continue the execution. This skips previously completed tasks and uses cached results in downstream tasks, rather than running the completed tasks again. Nextflow calculates each task's unique ID (hash) from the task's: - Input values - Input files - Command line string - Container ID - Conda environment - Environment modules - Any executed scripts in the bin directory A change in any of these values changes the task hash, and a changed hash means the task runs again on relaunch. To debug an unexpected relaunch, run the pipeline twice with `dumpHashes=true` set in your Nextflow config file (**Advanced options > Nextflow config file** in the pipeline settings). Nextflow then dumps the task hashes for both executions in the `nextflow.log` file. Compare the log files to find where the hashes diverge. See [Demystifying Nextflow resume](https://www.nextflow.io/blog/2019/demystifying-nextflow-resume.html) for more on the `resume` mechanism. #### `Incorrect string value` ``` [scheduled-executor-thread-2] - WARN o.h.e.jdbc.spi.SqlExceptionHelper - SQL Error: 1366, SQLState: HY000 [scheduled-executor-thread-2] - ERROR o.h.e.jdbc.spi.SqlExceptionHelper - (conn=34) Incorrect string value: '\xF0\x9F\x94\x8D |...' for column 'error_report' at row 1 [scheduled-executor-thread-2] - ERROR i.s.t.service.job.JobSchedulerImpl - Unable to save status of job id=18165; name=nf-workflow-26uD5XXXXXXXX; opId=nf-workflow-26uD5XXXXXXXX; status=UNKNOWN ``` Runs fail when your Nextflow script or config contains illegal characters, such as emojis or other non-UTF8 characters. To resolve, validate your script and config files for illegal characters before you run again. #### Run fails: Nextflow script exceeds 64 KiB The Groovy shell that Nextflow uses to execute your workflow has a hard limit on string size (64 KiB). Check the size of your scripts with `ls -llh`. If a script is larger than 65,535 bytes, consider these mitigations: 1. Remove unnecessary code or comments from the script. 2. Move long script bodies into a separate script file in the pipeline `/bin` directory. 3. Use DSL2 so you can move each function, process, and workflow definition into its own script and include them as [modules](https://docs.seqera.io/nextflow/module). ## Nextflow Launcher #### nf-launcher image compatibility Your Seqera installation knows the [nf-launcher image](https://quay.io/repository/seqeralabs/nf-launcher?tab=tags) version it needs and sets this value automatically when launching a pipeline. If you're restricted from using public container registries, see Seqera Enterprise release instructions for the specific image to set as the default when invoking pipelines. #### Specify the Nextflow version Each Seqera Platform release uses a specific nf-launcher image by default. This image is loaded with a specific Nextflow version that any workflow in the container uses by default. To run a job with a different Nextflow version: - Use the [**Nextflow version**](../launch/advanced#nextflow-version) selector in the pipeline or launch advanced options. This is the recommended method. Setting `NXF_VER` in a pre-run script or the pipeline configuration is no longer recommended; a value set there overrides the selector. The selector is not available when the installation pins a [custom launch container](../enterprise/advanced-topics/custom-launch-container). - For jobs executing in an AWS Batch compute environment, create a [custom job definition](../enterprise/advanced-topics/custom-launch-container) which references a different nf-launcher image. ## Spot instance failures and retries Up to version 24.10, Nextflow silently retried Spot instance failures up to five times on AWS Batch and Google Batch. These retries were controlled by cloud-specific configuration parameters (e.g., `aws.batch.maxSpotAttempts`) and happened in cloud infrastructure without explicit visibility to Nextflow. From version 24.10, the default Spot reclamation retry setting changed to `0` on AWS and Google. By default, no _internal_ retries are attempted on these platforms. Spot reclamations now cause an immediate failure, exposed to Nextflow like any other generic failure (returning, for example, `exit code 1` on AWS). Nextflow treats these failures like any other job failure unless you configure a retry strategy. #### Impact on existing workflows If you rely on silent Spot retries (the previous default), you might now see more tasks fail with these characteristics: - **AWS**: Generic failure with `exit code 1`. You might see messages indicating the host machine was terminated. - **Google**: Spot reclamation typically produces a specific code, but is now surfaced as a recognizable task failure in Nextflow logs. Because the default for Spot retries is now zero, you must enable a retry strategy for Nextflow to handle reclaimed Spot instances automatically. For more information, see [manage Spot interruptions](../tutorials/retry-strategy). ## Nextflow syntax parser Up to version 25.10, Nextflow uses the v1 syntax parser (also known as the legacy parser) by default. The v2 parser introduces stricter validation and is available as an opt-in through `NXF_SYNTAX_PARSER=v2`. From version 26.04, Nextflow uses the v2 syntax parser by default. Pipelines that run without modification under the v1 parser can fail under v2. #### Pin the v1 parser To run existing pipelines unchanged under Nextflow 26, set `NXF_SYNTAX_PARSER` to `v1` in a [pre-run script](../launch/advanced#pre-and-post-run-scripts): ```bash export NXF_SYNTAX_PARSER=v1 ``` This restores the legacy parser behavior. For migration guidance to the v2 parser, see [Preparing for strict syntax](https://docs.seqera.io/nextflow/strict-syntax). --- ## Pre-flight checks When pre-flight checks flag a compute environment or credential as `INVALID`, you might encounter the following errors. See [Compute environment pre-flight checks](../compute-envs/preflight-checks) for feature background and manual re-validation steps. ## Compute environment banners These banners appear on the compute environment detail page when the compute environment is `INVALID`. #### `Associated credentials are invalid or expired` Full message: ``` Associated credentials are invalid or expired. Update the credentials and validate this compute environment, or contact your workspace maintainer to resolve this. ``` The background sweep found that the attached credential is no longer valid. To resolve, go to **Credentials**, update or rotate the credential, then use **Validate** on the compute environment. ## Launch-time errors These errors are returned immediately when a launch is blocked. Multiple failures are reported together. #### `The selected compute environment '...' is in an invalid state` The compute environment is marked `INVALID`. Check the compute environment banner for the specific reason. To resolve, fix the root cause, then use **Validate** on the compute environment. #### `The credentials '...' used by this compute environment are invalid` The credential attached to the compute environment is marked `INVALID`. To resolve, go to **Credentials**, update or rotate the credential, then use **Validate** on the compute environment. #### `Wave service connection is not active` Full message: ``` Wave is required by the selected compute environment but the Wave service connection is not active. Verify that Wave is running and check for connectivity issues. ``` Platform cannot reach the Wave service. To resolve, contact your platform administrator. Once Wave is restored, retry the launch. #### `No Tower Agent is online for the selected compute environment` Full message: ``` No Tower Agent is online for the selected compute environment. Check that Tower Agent is running at your cluster. ``` No Tower Agent is connected for this compute environment (HPC/grid environments only). To resolve, start or restart Tower Agent on the cluster. See [Tower Agent](../supported_software/agent/overview). ## Credential errors by provider When the credential sweep marks a credential `INVALID`, Platform stores the provider-specific reason on the credential record. It appears in the launch-time error message when a pipeline is blocked, but not in the compute environment banner. To see the specific provider error, check the credential record directly. | Provider | Example message | |---|---| | AWS | `AWS credentials are invalid or expired. Update or rotate the access keys.` | | Google Cloud | `Google credentials are invalid or expired. Update the service account key.` | | Google Cloud Workload Identity Federation | `Google WIF credential validation failed. Verify the provider and service account configuration.` | | Azure Batch | `Azure Batch credentials are invalid. Verify the Batch account name and key.` | | Azure Storage | `Azure Storage credentials are invalid. Verify the storage account name and key.` | --- ## Resource labels(Troubleshooting_and_faqs) When working with resource labels on AWS, Azure, and Google Cloud, you might encounter the following issues. ## Common issues #### Tags not appearing in cost reports Resource labels are applied to your cloud resources but don't appear in your provider's cost reporting tools. This is usually a propagation delay or a cost-reporting configuration gap. To resolve: - Allow up to 24 hours for tags to appear in the AWS cost allocation console. - For Azure, enable tag inheritance and allow 24 hours for processing. - Verify that resources are actively running and generating usage data. #### Permission errors Tagging fails, or cost data is inaccessible, when the credentials associated with the compute environment lack tagging or billing permissions. To resolve: - Ensure the compute environment credentials have the permissions required to tag resources. - For Google Cloud, verify billing account administrator access. - For Azure, confirm billing profile contributor permissions and permissions to view Cost Management reports. #### Missing tag values in cloud provider resources Resources launch without the expected tags, or dynamic label values are empty. This usually means the labels aren't attached to the compute environment the workflow ran on. To resolve: - Verify that resource labels are applied to the correct compute environment. - Check that workflows use the tagged compute environment. - For dynamic resource labels, ensure variables use the correct syntax: `${sessionId}`, `${userName}`, or `${workflowId}`. #### Costs missing for manually created AWS Batch queues Costs for some AWS Batch runs never appear in Cost Explorer or your data exports, even though resource labels are applied. This happens when the compute environment or job queue was created manually, outside of Batch Forge, and so doesn't inherit Seqera's cost-allocation tags. To resolve: - Add the relevant cost-allocation tag (for example, `project=`) to the manually created compute environments, job queues, and related resources in the AWS console. - Prefer Batch Forge-created compute environments where possible, so tags propagate automatically. #### Cost data missing from the AWS data export Resource labels are applied and cost-allocation tags are activated, but split or unblended cost fields are missing or show zero in your data export. To resolve: - Confirm that the cost-allocation tag keys are activated in the **AWS Billing and Cost Management console** of the payer (billing) account. - Enable [split cost allocation data](https://docs.aws.amazon.com/cur/latest/userguide/enabling-split-cost-allocation-data.html) in your Cost and Usage Report preferences — without it, downstream reporting returns blended-only or zero values. - Allow a 24–48 hour delay for cost data to appear, then inspect the export (for example, query the Parquet files with Amazon Athena) to confirm the tag keys and their costs are present. #### Resource label tag keys look different in the AWS Cost and Usage Report Tag keys or values in the AWS Cost and Usage Report (CUR) don't match the resource labels you applied, breaking Athena or QuickSight queries. This is expected CUR normalization: in CUR (version 2), colons (`:`) are rewritten as underscores (`_`), and mixed- or upper-case characters are lowercased and separated with underscores (for example, `costCenter` becomes `cost_center`). To resolve: - Design resource-label keys and values that remain unambiguous after normalization. - Reference the normalized key names in your downstream Athena or QuickSight queries. --- ## Studios(Troubleshooting_and_faqs) When working with Studios, you might encounter the following issues. ## Sessions #### Session is stuck in **starting** If your Studio session doesn't advance from **starting** status to **running** status within 30 minutes, and you are a **Maintain** role or higher, select the three dots next to the status message for the Studio you want to stop, then select **Stop**. If you are not a **Maintain** or higher user but you have access to the AWS Console for your organization, check that the AWS Batch compute environment associated with the session is in the **ENABLED** state with a **VALID** status. You can also check the **Compute resources** settings. Contact your organization's AWS administrator if you don't have access to the AWS Console. If sufficient compute resources aren't available, select **Stop** for the session and any others that are running before trying again. If you have access to the AWS Console for your organization, you can terminate a specific session from the AWS Batch Jobs page (filtering by compute environment queue). #### Session status is **errored** The **errored** status is generally related to problems creating the Studio session resources in the compute environment, such as invalid credentials, insufficient permissions, or network issues. It can also be related to insufficient compute resources set in your compute environment configuration. Contact your organization's AWS administrator if you don't have access to the AWS Console, and contact your Seqera account executive to investigate. #### Session can't be **stopped** If you can't stop a session, the Batch job running the session usually failed. If you have access to the AWS Console for your organization, stop the session from the compute environment screen. Contact your organization's AWS administrator if you don't have access to the AWS Console, and contact your Seqera account executive to investigate. #### Session performance is poor A slow or unresponsive session might be caused by its AWS Batch compute environment being used for other jobs, such as running Nextflow pipelines. The compute environment schedules jobs to the available compute resources. Sessions compete for resources with the Nextflow pipeline head job. Seqera does not currently give either precedence. If you have access to the AWS Console for your organization, check the jobs associated with the AWS Batch compute environment and compare the resources allocated with its **Compute resources** settings. #### Memory allocation of the session is exceeded The running container in the AWS Batch compute environment inherits the memory limits specified by the session configuration when adding or starting the session. The kernel then handles the memory as if running natively on Linux. Linux can overcommit memory, leading to possible out-of-memory errors in a container environment. The kernel has protections to prevent this, but when it happens, the kernel kills the process. This can manifest as a performance lag, killed subprocesses, or at worst, a killed session. Seqera creates automated snapshots of running sessions every five minutes. If the running container is killed, you lose only the changes made after the prior snapshot. #### Session with GPUs doesn't start Check whether the instance type you selected [supports GPU](https://aws.amazon.com/ec2/instance-types/). If you specify multiple GPUs, make sure that your compute environment can launch multi-GPU instances and that your maximum CPU configuration doesn't limit them. #### R-IDE session initializes with error Connecting to a running R-IDE session with R version 4.4.1 (2024-06-14) -- "Race for Your Life" returns a `[rsession-root]` error similar to the following: ``` ERROR system error 2 (No such file or directory) [path:/sys/fs/cgroup/memory/memory.limit_in_bytes]; OCCURRED AT rstudio::core::Error rstudio::core::FilePath::openForRead(std::shared_ptr >&) ... ``` You can safely ignore this error. It appears because logging is set to `stderr` by default so that all logs are shown during the session. #### When starting an existing Studio session, extra processes are not automatically restarted A process you start manually in a running Studio session (e.g., `eval $(ssh-agent)`) is not automatically restarted when the Studio restarts, because the Connect client does not manage user-initiated daemon processes. Automatically starting extra processes on each Studio restart would require a user-defined startup script or an integrated supervisor such as `s6`, `s6-overlay`, or `supervisord`, none of which are currently supported. ## Compute environments #### Session size limited by head job CPUs and memory When you add a compute environment, the Advanced options **Head job CPUs** and **Head job memory** for Nextflow also apply to any Studio session created in the compute environment, because the Nextflow runner job manages Studio sessions. To avoid constraining the resources of your Studio sessions, don't define these optional settings. #### New compute environment doesn't appear in the drop-down when migrating a Studio When [migrating a Studio to a different compute environment](../studios/managing#migrate-a-studio-between-compute-environments), the **Compute environment** drop-down filters out any compute environment that isn't compatible with the Studio's current one. Confirm the new compute environment is in the `AVAILABLE` status and uses the same `workDir` as the Studio's current compute environment. #### Studio fails to start after switching compute environments The new compute environment's [credentials](../credentials/overview) must have read and write access to the `workDir` bucket. Confirm they have the required S3 permissions on the checkpoint location. #### Resource labels change after switching compute environments When you switch a Studio to a different compute environment, labels inherited from the previous compute environment are removed and the new compute environment's labels are added automatically. If you need a label that was tied to the old compute environment, attach it to the Studio directly so that it survives future compute environment switches. See [Resource label changes](../studios/managing#resource-labels-on-migration). ## Data and storage #### All datasets are read-only By default, AWS Batch compute environments created with Batch Forge restrict S3 access to the working directory only, unless you specify additional **Allowed S3 Buckets**. If the compute environment does not have write access to the mounted dataset, the dataset is mounted as read-only. #### Running session does not show new data in object storage By default, Fusion does not resync objects from remotely mounted data-link(s) after initial mounting. If you have a running session with data mounted and the underlying storage is updated, the data is not resynced to the Studio session. You can change this behavior when you [add a Studio session](../studios/add-studio) by setting the `FUSION_REFRESH_TIMEOUT` environment variable to a number of seconds (e.g., `120`). Fusion then refreshes the view of the mounted data links at that interval. :::note Setting the environment variable _inside_ an already running Studio session by executing the command `export FUSION_REFRESH_TIMEOUT=120` won't change the behavior of the outer Fusion session. Set the environment variable in the **General config** section during Studio creation. ::: :::warning Fusion waits two minutes before it uploads the working chunk. Always set `FUSION_REFRESH_TIMEOUT` to `120` or higher. Lower values can create orphaned chunks in the Studio environment that are never uploaded to object storage and cannot be recovered. ::: ## Custom environments and container images #### Failed custom environment rebuilds use the cached image Building a custom Studios image with the Wave service occasionally fails, typically because of conflicting libraries. If you rebuild the image with the same name and tag, Studios and Wave use the cached version if available. Change the version number or tag to pull a fresh image. The Elastic Container Service (ECS) agent's `ECS_IMAGE_PULL_BEHAVIOR` environment variable determines this behavior. In Seqera Platform Cloud, it is set to `once` when the compute environment is created. Enterprise installations might be configured differently. Contact your organization's administrator to learn more. #### Container template image security scan false positives When you run a software composition analysis (SCA) security scan (e.g., with Trivy) on the latest Seqera-provided VS Code image [container template](../studios/custom-envs), you might encounter multiple false-positive findings. VS Code defines extensions in a way that can cause some security scanners to incorrectly identify them as `npm` packages. This is a known limitation, discussed in the Trivy community [discussion](https://github.com/aquasecurity/trivy/discussions/6112). These are the false positive confirmed findings: | Component | Vulnerability id⁠ | | :--------------- | :------------------- | | handlebars:1.0.0 | CVE-2021-23383⁠ | | handlebars:1.0.0 | CVE-2021-23369⁠ | | handlebars:1.0.0 | CVE-2019-19919⁠ | | handlebars:1.0.0 | GHSA-q42p-pg8m-cqh6 | | handlebars:1.0.0 | GHSA-q2c6-c6pm-g3gh⁠ | | handlebars:1.0.0 | GHSA-g9r4-xpmj-mj65⁠ | | handlebars:1.0.0 | GHSA-2cf5-4w76-r9qv⁠ | | handlebars:1.0.0 | CVE-2019-20920⁠ | | handlebars:1.0.0 | CVE-2015-8861⁠ | | handlebars:1.0.0 | GMS-2015-33⁠ | | npm:1.0.1 | CVE-2019-16777⁠ | | npm:1.0.1 | CVE-2019-16776⁠ | | npm:1.0.1 | CVE-2019-16775⁠ | | npm:1.0.1 | CVE-2018-7408⁠ | | npm:1.0.1 | CVE-2016-3956⁠ | | npm:1.0.1 | CVE-2020-15095⁠ | | npm:1.0.1 | CVE-2013-4116⁠ | | npm:1.0.1 | GMS-2016-23⁠ | | grunt:1.0.0 | CVE-2022-1537⁠ | | grunt:1.0.0 | CVE-2020-7729⁠ | | grunt:1.0.0 | CVE-2022-0436⁠ | | pug:1.0.0 | CVE-2021-21353⁠ | | pug:1.0.0 | CVE-2024-36361⁠ | | json:1.0.0 | CVE-2020-7712⁠ | | ini:1.0.0 | CVE-2020-7788⁠ | | diff:1.0.0 | GHSA-h6ch-v84p-w6p9⁠ | ## Connect proxy #### Permission denied errors on OpenShift The `connect-proxy` pod starts, but the logs show that Caddy, the reverse proxy that `connect-proxy` is built on, can't create its configuration and data directories: ``` ERROR unable to create folder for config autosave {"dir": "/.config/caddy", "error": "mkdir /.config: permission denied"} WARN unable to get instance ID; storage clean stamps will be incomplete {"error": "mkdir /.local: permission denied"} ``` This issue occurs when OpenShift's `restricted-v2` security context constraint runs the container as an arbitrary user ID (UID) from the namespace's assigned range, ignoring the user the container image defines. Because that UID has no entry in the container image's `/etc/passwd` file, `HOME` resolves to `/`, a directory the UID can't write to. The `runAsUser`, `runAsGroup`, and `fsGroup` values of `65532` in the proxy deployment template are also incompatible with this constraint. To work around this issue on Kubernetes: 1. Remove the `runAsUser`, `runAsGroup`, and `fsGroup` values from your [Studios Kubernetes deployment](../enterprise/studios-kubernetes). 2. Caddy uses `XDG_CONFIG_HOME` and `XDG_DATA_HOME` to locate its configuration and data directories. Set them on the proxy container to directories under the `/data` volume that the template already mounts: ```yaml env: - name: XDG_CONFIG_HOME value: /data/config - name: XDG_DATA_HOME value: /data/lib ``` If writes to `/data/config` and `/data/lib` still fail with permission denied errors, mount a writable volume, such as an `emptyDir`, at each path. ## SSH connections (public preview) #### SSH Connection toggle not available If the **SSH Connection** toggle doesn't appear when adding a Studio, or SSH-related options are missing, your Platform version doesn't support SSH access to running Studios. SSH access requires: - **Seqera Platform Enterprise v25.3.3 or later** - **connect-server/proxy v0.12.0 or later** - **connect-client v0.12.0 or later** If your Platform meets these requirements but SSH is still unavailable, verify your administrator configured the required environment variables during deployment. #### Host key verification failed ``` @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Host key verification failed. ``` This error occurs when multiple proxy pods are using different SSH keys. Ensure all proxy pods share the same SSH key. If the issue persists, edit your `~/.ssh/known_hosts` file and remove the line that contains the connect-proxy address. #### Permission denied (publickey) ```bash ssh user@studio-session-id@connect.example.com # user@studio-session-id@connect.example.com: Permission denied (publickey). ``` If you receive a permission denied error, there are several possible causes: 1. Verify the user has the correct role and permissions in the workspace. 2. Check that the user's SSH public key is configured in their Seqera user profile. 3. Ensure SSH was enabled when adding the Studio using the **SSH Connection** toggle. The SSH setting persists across stop/start but defaults to disabled for new Studios. If the issue persists, verify your administrator configured the SSH environment variables during Studios deployment. #### Connection closed by remote host ```bash ssh user@studio-session-id@connect.example.com # Connection to connect.example.com closed by remote host. ``` This error indicates an SSH fingerprint mismatch when `TOWER_DATA_STUDIO_CONNECT_SSH_KEY_FINGERPRINT` is configured. Verify the fingerprint matches the proxy's SSH key: ```bash ssh-keygen -lf /path/to/connect-proxy-key ``` Check Studio logs for: ```json { "msg": "SSH fingerprint auth result", "authorized": false, "expected": "SHA256:NEu6MAPGJpImFJ3raQzv6+NubCPy/92hqR+CVyMjKvM", "incoming": "SHA256:NYu6MAPUJpImFQ3raQzv6+NubCPy/97hqR+CVyMjKvM" } ``` The `authorized` field should be `true` and `expected` should equal `incoming`. If they differ, the proxy SSH key configuration is incorrect. #### VS Code Remote SSH not working If VS Code fails to connect or shows errors when using the Remote SSH extension, disable local server mode in VS Code settings: ```json { "remote.SSH.useLocalServer": false } ``` VS Code's local server mode uses SSH multiplexing over SOCKS proxy, which is not supported. See [Connect to a Studio via SSH - VS Code Remote SSH](../studios/managing#vs-code-remote-ssh) for detailed setup instructions. Additionally, you might need to update your `~/.ssh/config` file to connect directly to the Studio session: ```bash Host HostName User @ Port ``` #### AI coding assistant fails with `Pseudo-terminal will not be allocated` ```bash ssh alice@a01ac8894@connect.example.com -p 2222 # Pseudo-terminal will not be allocated because stdin is not a terminal. ``` This issue occurs when an AI coding assistant runs `ssh` as a subprocess, such as Claude Code in a terminal. The assistant doesn't attach a terminal to stdin, and the SSH client refuses to allocate a pseudo-terminal. To resolve, force pseudo-terminal allocation with `-tt`: ```bash ssh -tt alice@a01ac8894@connect.example.com -p 2222 ``` #### Claude Code desktop app fails with `Couldn't inspect the remote machine` ``` Connecting to remote host... Detecting remote OS and shell... Couldn't inspect the remote machine. ``` This issue occurs when the connect-server/proxy is earlier than version 0.12.1, or the Connect client is earlier than version 0.13.0. Earlier versions don't run remote commands through a shell, and the app's environment checks fail. To resolve, upgrade the connect-server/proxy to 0.12.1 or later, and ensure your Studio runs Connect client 0.13.0 or later. See [Claude Code desktop app](../studios/managing#claude-code-desktop-app) for setup instructions. #### Claude Code desktop app fails with `Timed out while waiting for handshake` This issue occurs because the app ignores the `Port` value in `~/.ssh/config` and defaults to port 22. To resolve, set **SSH Port** to `2222` in the app's connection settings. See [Claude Code desktop app](../studios/managing#claude-code-desktop-app) for setup instructions. #### SSH connection string format **Correct format:** ```bash ssh @@ -p 2222 ``` **Example:** ```bash ssh alice@a01ac8894@connect.example.com -p 2222 ``` Where: - ``: Your Seqera Platform username - ``: The Studio session ID (8-character hex string visible in the Studios list) - ``: Your connect proxy domain - Port: `2222` (default SSH proxy port) #### Debugging SSH connections Enable debug logging for detailed SSH connection traces: **Proxy logs:** ```bash CONNECT_LOG_LEVEL=debug ``` **Client logs (in Studio):** ```bash CONNECT_CLIENT_LOG_LEVEL=debug ``` Debug logs include SSH handshake details, authentication attempts, channel lifecycle, and data transfer errors. ## Data transfer quotas #### A Studio stalls after a large upload or download The user receives an `HTTP 429` (Too Many Requests) response, or an active WebSocket or SSH connection drops. This issue occurs when the bucket reaches its quota and the proxy denies further traffic. Confirm the cause with the `connect_proxy_quota_exceeded_total` metric and the `quota exceeded, denying traffic for bucket` log line. As a workaround, wait for the window to reset. If the denial is a false positive, resolve it by raising the cap in the [policy](../enterprise/studios-transfer-quotas#define-a-policy). #### A per-IP quota blocks unrelated users Redis shows keys such as `ip:172.x`, `ip:10.x`, or `ip:192.168.x`. This issue occurs when the proxy cannot resolve the real client IP and buckets traffic on Kubernetes node IPs instead. To resolve, configure client-IP resolution. Set `CONNECT_TRUSTED_PROXY_CIDRS` for HTTP traffic and `externalTrafficPolicy: Local` for SSH traffic. See [Resolve the client IP for the `ip` bucket](../enterprise/studios-transfer-quotas#resolve-the-client-ip-for-the-ip-bucket). #### Quotas are not enforced This issue occurs when no policy is loaded, because the wrong environment variable is set or the variable is empty. To resolve, confirm that either `CONNECT_POLICY_FILE` or `CONNECT_POLICY_B64` is set and non-empty, then check the startup logs for `traffic policy loaded`. #### The proxy does not start or crash-loops This issue occurs when the Redis command preflight check fails or the policy JSON is invalid. The proxy fails to start rather than enforce quotas incorrectly. Check the startup logs for the missing Redis command or the [policy validation error](../enterprise/studios-transfer-quotas#extractor-source-types). To resolve, fix the `ConfigMap` or the Redis configuration, then redeploy. #### A VS Code or IDE client does not reconnect after a quota breach The proxy tears down the stream mid-session, and some interactive clients do not recover cleanly. This is a known limitation. As a workaround, reconnect the session. #### A policy or limit change has no effect This issue occurs because the proxy reads the policy once at startup and never reloads it at runtime. To resolve, perform a rolling restart of the proxy Deployment. #### SSH connections time out with no `HTTP 429` and no handshake This is not a quota issue. Check the load balancer target group health and the SSH service, then confirm the port is reachable from the client network. ## Working in a Studio session #### View all mounted datasets In your interactive analysis environment, open a new terminal and type `ls -la /workspace/data`. This displays all the mounted datasets available in the current session. #### Enable AI coding assistants in Studios VS Code, RStudio, and Jupyter environments natively integrate with [GitHub Copilot][gh-copilot]. Enabling it requires a GitHub account and an active Copilot subscription. - **VS Code:** To enable GitHub Copilot in your VS Code session, install the extension and then sign in with your GitHub account. [Learn more][vscode-blog]. - **RStudio:** Enabling GitHub Copilot in your RStudio session requires RStudio configuration changes. By default, the Studio session user has root permissions and can make these changes. Restart RStudio afterward. [Learn more][posit-ghcopilot-guide]. - **Jupyter:** [Notebook Intelligence (NBI)][nbi] is an AI coding assistant and extensible AI framework for Jupyter. It can use GitHub Copilot or AI models from any other LLM Provider. [Learn more][nbi-blog]. {/* links */} [gh-copilot]: https://github.com/features/copilot [open-vscode-server]: https://github.com/gitpod-io/openvscode-server [open-vsx]: https://open-vsx.org/ [posit-ghcopilot-guide]: https://docs.posit.co/ide/user/ide/guide/tools/copilot.html [nbi]: https://github.com/notebook-intelligence/notebook-intelligence [nbi-blog]: https://blog.jupyter.org/introducing-notebook-intelligence-3648c306b91a --- ## General When working with Seqera Platform, you might encounter the following issues. ## Common errors #### `timeout is not an integer or out of range` This error occurs on Seqera Platform v24.2 and later when Redis is outdated. Version 24.2 requires Redis 6.2 or later. To resolve, upgrade your Redis instance according to your cloud provider's instructions. #### `Unknown pipeline repository or missing credentials` from public GitHub repositories GitHub imposes [rate limits](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting) on repository pulls, including public repositories: unauthenticated requests are capped at 60 per hour and authenticated requests at 5000 per hour. This error is usually caused by the 60-per-hour cap. To resolve: 1. Ensure there's at least one GitHub credential in your workspace's **Credentials** tab. 2. Ensure the **Access token** field of every GitHub credential is populated with a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and **not** a user password. GitHub personal access tokens (PATs) are typically longer than passwords and include a `ghp_` prefix. For example: `ghp_IqIMNOZH6zOwIEB4T9A2g4EHMy8Ji42q4HA` 3. Confirm that your PAT provides the elevated threshold and that transactions are charged against it: `curl -H "Authorization: token ghp_LONG_ALPHANUMERIC_PAT" -H "Accept: application/vnd.github.v3+json" https://api.github.com/rate_limit` #### `Row was updated or deleted by another transaction (or unsaved-value mapping was incorrect)` This error occurs when incorrect configuration values are assigned to the `backend` and `cron` containers' [`MICRONAUT_ENVIRONMENTS`](../enterprise/configuration/overview#compute-environments) environment variable. You might see other unexpected behavior, such as two exact copies of the same Nextflow job submitted to the executor for scheduling. Verify the following: 1. The `MICRONAUT_ENVIRONMENTS` environment variable associated with the `backend` container: - Contains `prod,redis,ha` - Does not contain `cron` 2. The `MICRONAUT_ENVIRONMENTS` environment variable associated with the `cron` container: - Contains `prod,redis,cron` - Does not contain `ha` 3. You don't have another copy of the `MICRONAUT_ENVIRONMENTS` environment variable defined elsewhere in your application (such as a `tower.env` file or Kubernetes `ConfigMap`). 4. If you're using a separate container/pod to execute `migrate-db.sh`, ensure there's no `MICRONAUT_ENVIRONMENTS` environment variable assigned to it. #### `No such variable` This error occurs when you execute a DSL1-based Nextflow workflow with [Nextflow 22.03.0-edge](https://github.com/nextflow-io/nextflow/releases/tag/v22.03.0-edge) or later. #### Sleep commands in Nextflow workflows The behavior of `sleep` commands in your Nextflow workflows depends on where they are used: - In an `errorStrategy` block, Nextflow uses the Groovy sleep function, which takes its value in milliseconds. - In a process script block, that language's sleep binary or method is used. For example, [this bash script](https://docs.seqera.io/nextflow/metrics) uses the bash sleep binary, which takes its value in seconds. #### Large number of batch job definitions Platform normally looks for an existing job definition that matches your workflow requirement. If nothing matches, it recreates the job definition. Use a bash script to clear job definitions. Tailor it to your needs, for example to deregister only job definitions older than a set number of days: ```bash jobs=$(aws --region eu-west-1 batch describe-job-definitions | jq -r .jobDefinitions[].jobDefinitionArn) for x in $jobs; do echo "Deregister $x"; sleep 0.01; aws --region eu-west-1 batch deregister-job-definition --job-definition $x; done ``` ## Containers #### Use rootless containers in Nextflow pipelines Most containers use the root user by default. Some users prefer a non-root user in the container to minimize the risk of privilege escalation. Because Nextflow and its tasks use a shared work directory to manage input and output data, rootless containers can cause file permission errors in some environments: ``` touch: cannot touch '/fsx/work/ab/27d78d2b9b17ee895b88fcee794226/.command.begin': Permission denied ``` This should not occur with AWS Batch from Seqera version 22.1.0. In other cases, force all task containers to run as root. Add one of the following to your [Nextflow configuration](../launch/advanced#nextflow-config-file): ```groovy // cloud executors process.containerOptions = "--user 0:0" // Kubernetes k8s.securityContext = [ "runAsUser": 0, "runAsGroup": 0 ] ``` ## Databases #### Database connection failure in Seqera Enterprise 22.2.0 Seqera Enterprise 22.2.0 introduced a breaking change: `TOWER_DB_DRIVER` must now be `org.mariadb.jdbc.Driver`. If you use Amazon Aurora as your database, you might encounter a `java.sql.SQLNonTransientConnectionException: ... could not load system variables` error, likely because of a [known error](https://jira.mariadb.org/browse/CONJ-824) tracked in the MariaDB project. To resolve, modify the Seqera Enterprise configuration: 1. Ensure your `TOWER_DB_DRIVER` uses the specified MariaDB URI. 2. Modify your `TOWER_DB_URL` to: `TOWER_DB_URL=jdbc:mysql://:/?usePipelineAuth=false&useBatchMultiSend=false` #### `java.sql.SQLException` time zone errors on login After login authentication, Seqera presents an `Unexpected error while processing` error, with `java.sql.SQLException` errors related to the server time zone in the backend log:
Error log ``` io.micronaut.transaction.exceptions.CannotCreateTransactionException: Could not open Hibernate Session for transaction … Caused by: org.hibernate.exception.GenericJDBCException: Unable to acquire JDBC Connection … java.sql.SQLException: The server time zone value 'CEST' is unrecognized or represents more than one time zone. You must configure either the server or JDBC driver (via the 'serverTimezone' configuration property) to use a more specific time zone value if you want to utilize time zone support. … ```
Seqera can't connect to the database because the JDBC client doesn't specify a time zone. Set it with the `serverTimezone` property. To resolve, append `serverTimezone` to [`TOWER_DB_URL`](../enterprise/configuration/overview#seqera-and-redis-databases). For the `Europe/Amsterdam` time zone: ```bash export TOWER_DB_URL="jdbc:mysql://:3306/tower?permitMysqlScheme=true&serverTimezone=Europe/Amsterdam" ``` #### `java.io.IOException: Unsupported protocol version 252` When a service is restarted or otherwise interrupted, it can create invalid entries that corrupt your installation's Redis cache. Completed or terminated runs then display as in progress. To resolve, delete the key with the invalid entry (replace `` with your container name): ```bash ## Check if the key exists docker exec -ti redis-cli keys \* | grep workflow ## Show the hash contents of the key docker exec -ti redis-cli hgetall "workflow/modified" ## Delete the key docker exec -ti redis-cli del "workflow/modified" ``` ## Email and TLS #### TLS errors Nextflow and Seqera Platform can both interact with email providers on your behalf. These providers often require TLS connections, many now requiring at least TLSv1.2. TLS connection errors can occur because of variability in the [default TLS version specified by your JDK distribution](https://aws.amazon.com/blogs/opensource/tls-1-0-1-1-changes-in-openjdk-and-amazon-corretto/). If you encounter any of the following errors, there is likely a mismatch between your default TLS version and what the email provider supports: - `Unexpected error sending mail ... TLS 1.0 and 1.1 are not supported. Please upgrade/update your client to support TLS 1.2` - `ERROR nextflow.script.WorkflowMetadata - Failed to invoke 'workflow.onComplete' event handler ... javax.net.ssl.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate)` To resolve: 1. Set a JDK environment variable to force Nextflow and Seqera containers to use TLSv1.2 by default: ```bash export JAVA_OPTS="-Dmail.smtp.ssl.protocols=TLSv1.2" ``` 2. Add this parameter to your [nextflow.config file](../launch/advanced#nextflow-config-file): ```groovy mail { smtp.ssl.protocols = 'TLSv1.2' } ``` 3. Ensure these values are also set for Nextflow and Seqera: - `mail.smtp.starttls.enable=true` - `mail.smtp.starttls.required=true` ## Git integration #### `Get branches operation not supported by BitbucketServerRepositoryProvider provider` If you supplied the correct Bitbucket credentials and URL details in your `tower.yml` and still see this error, upgrade to at least v22.3.0. This version addresses SCM provider authentication issues and likely resolves the retrieval failure. ## Healthcheck #### Seqera Platform API healthcheck endpoint To implement automated healthcheck functionality, use Seqera's `service-info` endpoint. For example: ```bash curl -o /dev/null -s -w "%{http_code}\n" --connect-timeout 2 "https://api.cloud.seqera.io/service-info" -H "Accept: application/json" 200 ``` ## Login #### Login fails: screen frozen at `/auth?success=true` From version 22.1, Seqera Enterprise implements stricter cookie security by default and only sends an auth cookie if the client is connected over HTTPS. Login attempts over HTTP fail by default. To resolve, set the environment variable `TOWER_ENABLE_UNSAFE_MODE=true` to allow HTTP connectivity to Seqera (**not recommended for production environments**). #### Restrict Seqera access to a set of email addresses Removing the email section from the login page is not currently supported. You can, however, restrict which email identities can log in to your Seqera Enterprise instance with the `trustedEmails` configuration parameter in your `tower.yml` file: ```yaml # tower.yml tower: trustedEmails: # Any email address pattern which matches will have automatic access. - '*@seqera.io' - 'named_user@example.com' # Alternatively, specify a single entry to deny access to all other emails. - 'fake_email_address_which_cannot_be_accessed@your_domain.org' ``` Users with email addresses outside the `trustedEmails` list undergo an approval process on the **Profile > Admin > Users** page. This is an effective backup method when SSO becomes unavailable. :::note 1. You must rebuild your containers (`docker compose down`) to force Seqera to implement this change. Ensure your database is persistent before you issue the teardown command. See [Docker Compose](../enterprise/platform-docker-compose) for more information. 2. All login attempts are visible to the root user at **Profile > Admin panel > Users**. 3. Any user logged in before the restriction is not subject to the new restriction. An organization admin should remove users that previously logged in with an untrusted email from the Admin panel users list. This restarts the approval process before they can log in by email. ::: #### Login fails: admin approval required with Entra ID OIDC The Entra ID app integrated with Seqera must have user consent settings configured to "Allow user consent for apps" so that admin approval is not required for each application login. See [User consent settings](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/configure-user-consent?pivots=portal#configure-user-consent-settings). #### `Username and Password not accepted` with Google SMTP Seqera Enterprise email integration with Google SMTP can fail as of May 30, 2022, because of a [security posture change](https://support.google.com/accounts/answer/6010255#more-secure-apps-how&zippy=%2Cuse-more-secure-apps) by Google. To re-establish email connectivity, follow [these instructions](https://support.google.com/accounts/answer/3466521) to provision an app password. Update your `TOWER_SMTP_PASSWORD` environment variable with the app password, then restart the application. ## Logging #### Broken Nextflow log file in v22.3.1 A Seqera Launcher issue affects the Nextflow log file download in version 22.3.1. Version 22.3.2 fixes it. Update to version 22.3.2 or later. ## Miscellaneous #### Maximum parallel Seqera browser tabs Because of a limitation in [server-side event technology in HTTP/1.1](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events), up to five tabs can be open simultaneously per browser product. Additional tabs remain stuck in a loading state. ## Monitoring #### Integrate third-party Java Application Performance Monitoring (APM) solutions Mount the APM solution's JAR file in Seqera's `backend` container and set the agent JVM option through the `JAVA_OPTS` environment variable. #### Retrieve the trace logs for a workflow run You can't download the trace logs directly through Seqera, but you can configure your workflow to export the file to persistent storage: 1. Set this block in your [`nextflow.config`](../launch/advanced#nextflow-config-file): ```groovy trace { enabled = true } ``` 2. Add a copy command to your pipeline's **Advanced options > Post-run script** field: ```bash aws s3 cp ./trace.txt s3:///trace/trace.txt ``` #### Seqera Platform intermittently reports `Live events sync offline` Seqera Platform uses [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to push real-time updates to your browser. The client must connect to the server's `/api/live` endpoint to start the data stream, and this connection can occasionally fail because of factors like network latency. To resolve, reload the Platform browser tab to re-establish the client's connection to the server. If reloading fails, contact [Seqera support](https://support.seqera.io) for help adjusting webserver timeout settings. ## Networking #### 503 errors during pipeline execution A 503 error indicates that one or more services that Seqera Enterprise contacts during workflow execution are unavailable. [Database](../enterprise/configuration/overview#seqera-and-redis-databases) connectivity is a common cause. To resolve, ensure all required services are running and available. #### `SocketTimeoutException: connect timed out` with self-hosted Git servers You might see connection timeout errors when launching workflows from a self-hosted Git server, such as Bitbucket or GitLab. If you configured the correct Git credentials in Seqera Enterprise, this error means the `backend/cron` container can't connect to the Git remote host, often because of a missing or incorrect proxy configuration.
Error log ``` ERROR i.s.t.c.GlobalErrorController - Unexpected error while processing - Error ID: 6h3HBUkaPe03vgzoDPc5HO java.net.SocketTimeoutException: connect timed out at java.base/java.net.PlainSocketImpl.socketConnect(Native Method) at java.base/java.net.AbstractPlainSocketImpl.doConnect(AbstractPlainSocketImpl.java:399) at java.base/java.net.AbstractPlainSocketImpl.connectToAddress(AbstractPlainSocketImpl.java:242) at java.base/java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:224) at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:392) at java.base/java.net.Socket.connect(Socket.java:609) at java.base/sun.security.ssl.SSLSocketImpl.connect(SSLSocketImpl.java:289) at java.base/sun.net.NetworkClient.doConnect(NetworkClient.java:177) at java.base/sun.net.www.http.HttpClient.openServer(HttpClient.java:474) at java.base/sun.net.www.http.HttpClient.openServer(HttpClient.java:569) at java.base/sun.net.www.protocol.https.HttpsClient.(HttpsClient.java:265) at java.base/sun.net.www.protocol.https.HttpsClient.New(HttpsClient.java:372) at java.base/sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.getNewHttpClient(AbstractDelegateHttpsURLConnection.java:203) at java.base/sun.net.www.protocol.http.HttpURLConnection.plainConnect0(HttpURLConnection.java:1187) at java.base/sun.net.www.protocol.http.HttpURLConnection.plainConnect(HttpURLConnection.java:1081) at java.base/sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.connect(AbstractDelegateHttpsURLConnection.java:189) at java.base/sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1592) at java.base/sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1520) at java.base/java.net.HttpURLConnection.getResponseCode(HttpURLConnection.java:527) at java.base/sun.net.www.protocol.https.HttpsURLConnectionImpl.getResponseCode(HttpsURLConnectionImpl.java:334) at nextflow.scm.RepositoryProvider.checkResponse(RepositoryProvider.groovy:167) at nextflow.scm.RepositoryProvider.invoke(RepositoryProvider.groovy:136) at nextflow.scm.RepositoryProvider.memoizedMethodPriv$invokeAndParseResponseString(RepositoryProvider.groovy:218) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.base/java.lang.reflect.Method.invoke(Method.java:566) at org.codehaus.groovy.reflection.CachedMethod.invoke(CachedMethod.java:107) at groovy.lang.MetaMethod.doMethodInvoke(MetaMethod.java:323) at groovy.lang.MetaClassImpl.invokeMethod(MetaClassImpl.java:1259) at groovy.lang.MetaClassImpl.invokeMethod(MetaClassImpl.java:1026) at org.codehaus.groovy.runtime.InvokerHelper.invokePogoMethod(InvokerHelper.java:1029) at org.codehaus.groovy.runtime.InvokerHelper.invokeMethod(InvokerHelper.java:1012) at org.codehaus.groovy.runtime.InvokerHelper.invokeMethodSafe(InvokerHelper.java:101) at nextflow.scm.RepositoryProvider$_closure2.doCall(RepositoryProvider.groovy) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.base/java.lang.reflect.Method.invoke(Method.java:566) at org.codehaus.groovy.reflection.CachedMethod.invoke(CachedMethod.java:107) at groovy.lang.MetaMethod.doMethodInvoke(MetaMethod.java:323) at org.codehaus.groovy.runtime.metaclass.ClosureMetaClass.invokeMethod(ClosureMetaClass.java:263) at groovy.lang.MetaClassImpl.invokeMethod(MetaClassImpl.java:1026) at groovy.lang.Closure.call(Closure.java:412) at org.codehaus.groovy.runtime.memoize.Memoize$MemoizeFunction.lambda$call$0(Memoize.java:137) at org.codehaus.groovy.runtime.memoize.ConcurrentCommonCache.getAndPut(ConcurrentCommonCache.java:137) at org.codehaus.groovy.runtime.memoize.ConcurrentCommonCache.getAndPut(ConcurrentCommonCache.java:113) at org.codehaus.groovy.runtime.memoize.Memoize$MemoizeFunction.call(Memoize.java:136) at groovy.lang.Closure.call(Closure.java:428) at nextflow.scm.RepositoryProvider.invokeAndParseResponse(RepositoryProvider.groovy) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.base/java.lang.reflect.Method.invoke(Method.java:566) at org.codehaus.groovy.runtime.callsite.PlainObjectMetaMethodSite.doInvoke(PlainObjectMetaMethodSite.java:43) at org.codehaus.groovy.runtime.callsite.PogoMetaMethodSite$PogoCachedMethodSiteNoUnwrapNoCoerce.invoke(PogoMetaMethodSite.java:193) at org.codehaus.groovy.runtime.callsite.PogoMetaMethodSite.callCurrent(PogoMetaMethodSite.java:61) at org.codehaus.groovy.runtime.callsite.AbstractCallSite.callCurrent(AbstractCallSite.java:185) at nextflow.scm.BitbucketRepositoryProvider.getCloneUrl(BitbucketRepositoryProvider.groovy:114) at nextflow.scm.AssetManager.memoizedMethodPriv$getGitRepositoryUrl(AssetManager.groovy:394) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.base/java.lang.reflect.Method.invoke(Method.java:566) at org.codehaus.groovy.reflection.CachedMethod.invoke(CachedMethod.java:107) at groovy.lang.MetaMethod.doMethodInvoke(MetaMethod.java:323) at groovy.lang.MetaClassImpl.invokeMethod(MetaClassImpl.java:1259) at groovy.lang.MetaClassImpl.invokeMethod(MetaClassImpl.java:1026) at org.codehaus.groovy.runtime.InvokerHelper.invokePogoMethod(InvokerHelper.java:1029) at org.codehaus.groovy.runtime.InvokerHelper.invokeMethod(InvokerHelper.java:1012) at org.codehaus.groovy.runtime.InvokerHelper.invokeMethodSafe(InvokerHelper.java:101) at nextflow.scm.AssetManager$_closure1.doCall(AssetManager.groovy) at nextflow.scm.AssetManager$_closure1.doCall(AssetManager.groovy) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.base/java.lang.reflect.Method.invoke(Method.java:566) at org.codehaus.groovy.reflection.CachedMethod.invoke(CachedMethod.java:107) at groovy.lang.MetaMethod.doMethodInvoke(MetaMethod.java:323) at org.codehaus.groovy.runtime.metaclass.ClosureMetaClass.invokeMethod(ClosureMetaClass.java:263) at groovy.lang.MetaClassImpl.invokeMethod(MetaClassImpl.java:1026) at groovy.lang.Closure.call(Closure.java:412) at org.codehaus.groovy.runtime.memoize.Memoize$MemoizeFunction.lambda$call$0(Memoize.java:137) at org.codehaus.groovy.runtime.memoize.ConcurrentCommonCache.getAndPut(ConcurrentCommonCache.java:137) at org.codehaus.groovy.runtime.memoize.ConcurrentCommonCache.getAndPut(ConcurrentCommonCache.java:113) at org.codehaus.groovy.runtime.memoize.Memoize$MemoizeFunction.call(Memoize.java:136) at groovy.lang.Closure.call(Closure.java:406) at nextflow.scm.AssetManager.getGitRepositoryUrl(AssetManager.groovy) ```
To resolve, update the HTTP proxy configuration in the `backend` and `cron` environment with your proxy details: ```bash export http_proxy="http://:" export https_proxy="https://:" ``` ## Optimization #### `OutOfMemoryError: Container killed due to memory usage` Nextflow can underestimate the memory allocation for containerized tasks. As a workaround, add a `retry` error strategy to the failing process that increases the allocated memory on each retry: ```groovy process { errorStrategy = 'retry' maxRetries = 3 memory = { 1.GB * task.attempt } } ``` ## Plugins #### Use the Nextflow SQL DB plugin to query AWS Athena From [Nextflow 22.05.0-edge](https://github.com/nextflow-io/nextflow/releases/tag/v22.05.0-edge), your Nextflow pipelines can query data from AWS Athena. Add these items to your `nextflow.config`. Secrets are optional: ```groovy plugins { id 'nf-sqldb@0.4.0' } sql { db { 'athena' { url = 'jdbc:awsathena://AwsRegion=;S3OutputLocation=s3://' user = secrets.ATHENA_USER password = secrets.ATHENA_PASSWORD } } } ``` Then call the functionality in your workflow: ```groovy channel.sql.fromQuery("select * from test", db: "athena", emitColumns:true).view() ``` :::note This example uses the legacy `nf-sqldb@0.4.0` syntax. Newer plugin versions use an explicit `include { fromQuery } from 'plugin/nf-sqldb'` statement instead. See the [nf-sqldb documentation](https://github.com/nextflow-io/nf-sqldb). ::: See the [nf-sqldb discussion](https://github.com/nextflow-io/nf-sqldb/discussions/5) for more information. ## Repositories #### Private Docker registry integration Seqera-invoked jobs can pull container images from private Docker registries, such as JFrog Artifactory. The method depends on your computing platform. For **AWS Batch**, modify your EC2 launch template using [these AWS instructions](https://docs.aws.amazon.com/batch/latest/userguide/private-registry-auth.html). :::note This solution requires Docker Engine [17.07 or later](https://docs.docker.com/engine/release-notes/17.07/) to use `--password-stdin`. You might need to add commands to your launch template, depending on your security posture: ```bash cp /root/.docker/config.json /home/ec2-user/.docker/config.json && chmod 777 /home/ec2-user/.docker/config.json ``` ::: For **Azure Batch**, create a **Container registry**-type credential in your Seqera workspace and associate it with the Azure Batch compute environment in the same workspace. For **Kubernetes**, use an `imagePullSecret`, per [#2827](https://github.com/nextflow-io/nextflow/issues/2827). #### `Remote resource not found` This error occurs when the Nextflow head job fails to retrieve the repository credentials from Seqera. If your Nextflow log contains an entry like `DEBUG nextflow.scm.RepositoryProvider - Request [credentials -:-]`, check the protocol of your instance's `TOWER_SERVER_URL` value. It must be set to `https` rather than `http`, unless you use `TOWER_ENABLE_UNSAFE_MODE` to allow HTTP connections to Seqera in a test environment. ## Secrets #### `Missing AWS execution role arn` during launch The [ECS agent must have access](https://docs.aws.amazon.com/batch/latest/userguide/execution-IAM-role.html) to retrieve secrets from AWS Secrets Manager. Secrets-using pipelines launched in an AWS Batch compute environment encounter this error when an IAM execution role is not provided. See [Secrets](../secrets/overview). #### AWS Batch task failures with secrets You might encounter errors when executing pipelines that use secrets on AWS Batch: - If you use `nf-sqldb` version 0.4.1 or earlier and have secrets in your `nextflow.config`, you might see `nextflow.secret.MissingSecretException: Unknown config secret` errors in your Nextflow log. To resolve, explicitly define the `xpack-amzn` plugin in your configuration: ```groovy plugins { id 'xpack-amzn' id 'nf-sqldb' } ``` - If you have two or more processes that use the same container image but only some of them use secrets, your secret-using processes might fail during the initial run and then succeed when resumed. This is caused by a bug in how Nextflow (22.07.1-edge and earlier) registers jobs with AWS Batch. To resolve, upgrade Nextflow to version 22.08.0-edge or later. If you can't upgrade, use one of these workarounds: - Use a different container image for each process. - Define the same set of secrets in each process that uses the same container image. ## Tower Agent #### `Unexpected Exception in WebSocket … Operation timed out` Tower Agent reconnection logic was improved in version 0.5.0. [Update your Tower Agent](https://github.com/seqeralabs/tower-agent) before relaunching your pipeline. #### Reattach to a running agent When you SSH back to the login node, attach to the agent session at any time: ```bash tmux attach -t tower-agent ``` You can see the current log output. Detach again with **Ctrl-b**, then **d**, to leave the agent running. #### Agent process stopped If `tmux ls` shows no sessions, or attaching reveals the agent has exited, restart it as in [Tower Agent setup](../supported_software/agent/overview#start-the-agent-inside-tmux). Common causes: login node reboot, the process killed for exceeding login-node resource limits, or a revoked access token. #### Agent shows as disconnected in Seqera Platform If Seqera Platform shows the agent as disconnected while it's running on the cluster, verify that the **Agent Connection ID** in your workspace credential exactly matches the argument you passed to `tw-agent`. #### _Authentication errors_ on agent startup Personal access tokens can be revoked or expire. If the agent logs authentication errors, generate a new token in Seqera Platform and restart the agent with the updated `TOWER_ACCESS_TOKEN` value. #### _Permission denied_ on the work directory The agent needs read and write access to the work directory. If launches fail with permission errors, confirm that the directory exists and is owned by the user running the agent: ```bash mkdir -p ~/work ``` #### Enable trace logging To diagnose connection or execution issues in detail, enable trace-level logging: ```bash export TOWER_ACCESS_TOKEN= export LOGGER_LEVELS_IO_SEQERA_TOWER_AGENT=TRACE ./tw-agent ``` Trace logging shows WebSocket connection details, message exchanges, reconnection attempts, command execution details and exit codes, and full stack traces for errors. ## Google #### Spot VM preemption causes task interruptions Spot VMs reduce cost but increase the likelihood that a task is interrupted before completion. When Google Cloud reclaims a Spot VM, Google Cloud Batch terminates the task with exit code `50001`. Add a retry strategy to your Nextflow configuration so interrupted tasks are automatically re-executed. See [Spot Instances](https://docs.seqera.io/nextflow/google#spot-instances) in the Nextflow documentation. For example: ```groovy process { errorStrategy = { task.exitStatus == 50001 ? 'retry' : 'finish' } maxRetries = 5 } ``` #### Seqera service account permissions for Google Cloud Batch Grant the following roles to the custom service account that submits Batch jobs: - Batch Agent Reporter (`roles/batch.agentReporter`) - Batch Job Editor (`roles/batch.jobsEditor`) - Logs Writer (`roles/logging.logWriter`) - Logs Viewer (`roles/logging.logViewer`) - Service Account User (`roles/iam.serviceAccountUser`) - Storage Admin (`roles/storage.admin`), or bucket-level Storage access For detailed setup instructions, see [Service account permissions](../compute-envs/google-cloud-batch#service-account-permissions). ## Kubernetes #### `Invalid value: "xxx": must be less or equal to memory limit` This error can occur when you specify a value in the **Head Job memory** field while creating a Kubernetes-type compute environment. If you receive an error that includes `field: spec.containers[x].resources.requests` and `message: Invalid value: "xxx": must be less than or equal to memory limit`, your Kubernetes cluster might be configured with [system resource limits](https://kubernetes.io/docs/tasks/administer-cluster/manage-resources/) that deny the Nextflow head job's resource request. To isolate the component causing the problem, launch a pod directly on your cluster through your Kubernetes administration solution. For example: ```yaml --- apiVersion: v1 kind: Pod metadata: name: debug labels: app: debug spec: containers: - name: debug image: busybox command: ["sh", "-c", "sleep 10"] resources: requests: memory: "xxxMi" # or "xxxGi" restartPolicy: Never ``` ## On-premises HPC #### `java: command not found` When submitting jobs to your on-premises HPC (using either SSH or Tower Agent authentication), the following error might appear in your Nextflow logs, even with Java on your `PATH` environment variable: ``` java: command not found Nextflow is trying to use the Java VM defined for the following environment variables: JAVA_CMD: java NXF_OPTS: ``` Possible causes: 1. The queue where the Nextflow head job runs is in a different environment or node than your login node userspace. 2. If your HPC cluster uses modules, the Java module might not be loaded by default. To troubleshoot: 1. Open an interactive session with the head job queue. 2. Launch the Nextflow job from the interactive session. 3. If your cluster uses modules, add `module load ` in the **Advanced options > Pre-run script** field when creating your HPC compute environment in Seqera. 4. If your cluster doesn't use modules, source an environment with Java and Nextflow in the **Advanced options > Pre-run script** field when creating your HPC compute environment in Seqera. #### Pipeline submissions to HPC clusters fail for some users Nextflow launcher scripts fail if processed by a non-Bash shell, such as zsh or tcsh. You can identify this problem from these error entries: 1. Your `.nextflow.log` contains an error like `Invalid workflow status - expected: SUBMITTED; current: FAILED`. 2. Your Seqera **Error report** tab contains an error like: ``` Slurm job submission failed - command: mkdir -p /home//\//scratch; cd /home//\//scratch; echo | base64 -d > nf-.launcher.sh; sbatch ./nf-.launcher.sh - exit : 1 - message: Submitted batch job <#> ``` Connect to the head node over SSH and run `ps -p $$` to verify your default shell. If you see an entry other than Bash, fix it as follows: 1. Check which shells are available: `cat /etc/shells` 2. Change your shell: `chsh -s /usr/bin/bash` (the path to the binary might differ, depending on your HPC configuration). 3. If submissions continue to fail after the shell change, ask your Seqera Platform admin to restart the **backend** and **cron** containers, then submit again. #### Execution logs don't update in real time for HPC compute environments While a task runs on an HPC compute environment (such as Slurm, Grid Engine, LSF, or PBS Pro), the **Execution log** tab on the run details page does not refresh automatically. This is expected behavior. Real-time log streaming is supported only for compute environments that stream logs from a cloud logging service: AWS Batch, Azure Batch, Google Cloud Batch, Kubernetes, and the AWS Cloud and Azure Cloud environments. For HPC compute environments, Seqera Platform retrieves the task log from the task work directory (the task's `.command.log` file) instead of streaming it. To load the latest log content, change tabs or refresh the page. Other run details, such as run status, task counters, and metrics, update in real time regardless of the compute environment type. --- ## Workspaces(Troubleshooting_and_faqs) When working with workspaces, you might encounter the following issues. ## Common issues #### Seqera-invoked pipeline contacts a workspace other than the launch workspace You might see this entry in your Nextflow log: ``` Unexpected response for request http://TOWER_SERVER_URL/api/trace/TRACE_ID/begin?workspaceId=WORKSPACE_ID ``` If the workspace ID in this message differs from your launch workspace, Seqera retrieved an incorrect access token from a Nextflow configuration file. Check these locations for a hardcoded token: - The `tower.accessToken` block of your `nextflow.config`, either from the Git repository or an override in the launch form. - In an HPC cluster compute environment, a stateful `nextflow.config` in the credential user's home directory, for example `~/.nextflow/config`. To resolve, remove the hardcoded access token so that Seqera uses the launch workspace's token. # Seqera Platform Cloud > Documentation for Seqera Platform Cloud. This file contains all documentation content in a single document following the llmstxt.org standard. ## Billing and credit management Seqera Compute environments and Co-Scientist share a credit pool at the organization level. Each user also receives a monthly Co-Scientist allowance based on their plan. Once a user exhausts their allowance, further Co-Scientist usage draws from the shared pool. Compute credits are deducted from the shared pool in real time at task completion. One Seqera credit equals $1 USD. Compute resources are charged at AWS on-demand rates for the selected region, with transparent pass-through pricing. ## How billing works ### Real-time credit deduction - **Task-level billing (Compute)**: Credits are deducted as each pipeline task completes, providing real-time visibility into run costs. Credit spend for running Studio sessions updates at regular intervals. - **Per-inference billing (Co-Scientist)**: Once your monthly included allowance is consumed, credits are deducted per AI inference call. Usage under the included allowance is not charged. - **Cost aggregation**: The [usage report](#usage-report) shows aggregated compute and memory costs per workflow or Studio session. ### Compute resources Seqera Compute bills for four resource types: | Resource | Rate (credits) | Billing unit | Based on | Billing frequency | Details | | -------------------- | -------------- | ------------ | --------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **CPU time** | 0.1 | CPU-hour | Requested vCPUs × runtime | At task completion | Charged based on requested vCPUs | | **Memory** | 0.025 | GB-hour | Requested memory × runtime | At task completion | Charged based on requested memory. If tasks request no memory, peak memory at task completion is charged (minimum 2 GB per task). | | **Storage** | 0.025 | GB-month | Actual usage | Daily reconciliation | S3 storage costs at AWS rates, varies by region | | **Network transfer** | Varies by region | GB | Actual data transfer | Daily reconciliation | Data egress charges at AWS rates. Network charges reflect in billing reports after 48 hours. | :::info CPU and memory are billed based on **requested** resources in your pipeline configuration, not actual usage. Storage and network costs are billed based on actual consumption. ::: ### Co-Scientist usage Co-Scientist follows a tiered billing model: - **Included usage**: Each plan includes a monthly allowance of Co-Scientist usage. Usage within this allowance is not charged. The included allowance resets monthly. - **Credit overage**: Usage above the included allowance is billed against your organization's credit balance, deducted per AI inference call. The **Credit usage** dialog in Co-Scientist shows your usage on both tiers, including included usage with a monthly progress bar and remaining org credits with the credit expiration date. When included usage is exhausted, requests automatically draw from available credits. :::info Co-Scientist usage is tracked per workspace. Your organization administrator can review per-workspace AI consumption alongside compute spend in the workspace **Settings**. ::: #### Billing example: pipeline run The [nf-core/rnaseq](https://nf-co.re/rnaseq/3.21.0) pipeline is run on a Seqera Compute environment with a test dataset as input. The following run metrics are recorded at workflow completion: ![Run details](_images/run-details.jpg) To calculate the credit spend for this run, the vCPUs and memory **requested** for each task are multiplied by task runtime: | Task | Duration | CPUs | Memory | | ----------------------------------------------------------------------------- | -------- | ---- | ------- | | PREPARE_GENOME:GUNZIP_ADDITIONAL_FASTA (gfp.fa.gz) | 3 m 28 s | 1 | 6.0 GB | | PREPARE_GENOME:UNTAR_SALMON_INDEX (salmon.tar.gz) | 3 m 28 s | 1 | 6.0 GB | | PREPARE_GENOME:GUNZIP_GTF (genes_with_empty_tid.gtf.gz) | 3 m 28 s | 1 | 6.0 GB | | RNASEQ:FASTQ_QC_TRIM_FILTER_SETSTRANDEDNESS:CAT_FASTQ (WT_REP1) | 3 m 29 s | 1 | 6.0 GB | | RNASEQ:FASTQ_QC_TRIM_FILTER_SETSTRANDEDNESS:FQ_LINT (WT_REP2) | 3 m 29 s | 2 | 12.0 GB | | RNASEQ:FASTQ_QC_TRIM_FILTER_SETSTRANDEDNESS:FQ_LINT (RAP1_UNINDUCED_REP1) | 3 m 29 s | 2 | 12.0 GB | | RNASEQ:FASTQ_QC_TRIM_FILTER_SETSTRANDEDNESS:CAT_FASTQ (RAP1_UNINDUCED_REP2) | 3 m 29 s | 1 | 6.0 GB | | RNASEQ:FASTQ_QC_TRIM_FILTER_SETSTRANDEDNESS:FQ_LINT (RAP1_IAA_30M_REP1) | 3 m 29 s | 2 | 12.0 GB | | PREPARE_GENOME:GTF_FILTER (genome.fasta) | 47 s | 1 | 6.0 GB | | FASTQ_FASTQC_UMITOOLS_TRIMGALORE:FASTQC (WT_REP2) | 46 s | 4 | 15.0 GB | :::info The **Tasks** tab of the [run details](../monitoring/run-details) page lists the processes and tasks executed during the run. Select a task from the list to view the task's details, including metrics for **Execution time** and **Resources requested**. ::: The usage report for this run shows the CPU and memory cost as separate line items: | Date | WorkflowId | WorkspaceId | Region | ProductName | UnitPrice(USD) | Quantity | Total(USD) | | ---------- | ------------- | ---------------- | --------- | ----------- | -------------- | ------------------ | --------------------- | | 2025-10-10 | 2BYxxxxxxxMoy | 1884xxxxxxx2036 | us-east-2 | Cpu Hours | 0.1 | 1.3255897223 | 0.13255897223 | | 2025-10-10 | 2BYxxxxxxxMoy | 1884xxxxxxx2036 | us-east-2 | Memory Gb | 0.025 | 5.514970833333334 | 0.13787427083333334 | This run consumed approximately 0.27 credits, for a total cost of $ 0.27 (USD). ## Credit management ### Credit balance and spend overview - Navigate to your organization or workspace **Settings** tab to view credit balance and spend information, request more credits, and download usage reports. - Select **Usage overview** in the top navigation bar to view real-time run, Studio, user, and credit usage information for your workspace. Select **Details** to navigate to workspace **Settings**. - In Co-Scientist, the **Credit usage** dialog shows monthly included usage alongside available org credits, so you can see at a glance whether you're consuming included allowance or drawing from credits. ### Usage report From your organization or workspace **Settings** tab, select **Download report** in the **Credits** section to download a usage report in CSV format. The report is structured as follows: | Date | WorkflowId | WorkspaceId | Region | ProductName | UnitPrice(USD) | Quantity | Total(USD) | | ---------- | ------------- | ---------------- | --------- | ----------- | -------------- | ------------------ | --------------------- | | 2025-10-10 | 2BYxxxxxxxMoy | 1884xxxxxxx2036 | us-east-2 | Cpu Hours | 0.1 | 1.3255897223 | 0.13255897223 | | 2025-10-10 | 2BYxxxxxxxMoy | 1884xxxxxxx2036 | us-east-2 | Memory Gb | 0.025 | 5.514970833333334 | 0.13787427083333334 | The report includes: - Separate line items for compute and memory per workflow or Studio session - Aggregated costs (not individual task breakdowns) ### Request additional credits To request more credits: 1. Select **Request more credits** in the organization or workspace settings **Credits** view. 2. Complete the form with your contact, organization, and credit request details. 3. Credits are typically allocated within one business day. :::info [**Request credits**](https://seqera.io/platform/compute/request-credits/) online or contact your Seqera account manager for assistance. ::: ### Credit limits and service suspension When your organization or workspace credit balance is exhausted, all credit-billable services are affected: 1. **Running pipelines paused**: All active pipeline runs and Studio sessions are automatically suspended. 2. **Seqera Compute buckets locked**: Data can no longer be browsed or downloaded from Data Explorer. 3. **New launches blocked**: No new pipeline runs or Studios can be started using Seqera Compute environments. 4. **Co-Scientist requests blocked**: Once both your included monthly AI usage and your org credit balance are exhausted, new requests are blocked until credits are added. 5. **Resume runs manually**: After purchasing additional credits, manually [resume](../launch/cache-resume) paused pipelines. :::warning Long-running tasks are periodically monitored. If a single task's estimated cost would exceed remaining credits, the workflow is preemptively paused. ::: --- ## Cloud changelog ### v24.2.0_cycle24 — 25 September 2024 - Feature: Azure service principal credentials - Feature: Data Studios: Add direct Data Explorer browse link to mounted data items - Feature: Data Studios: Make studio details page tabs routable - Feature: Define cache configuration once, only override changes - Improvement: Data Explorer: Highlight invalid custom datalinks - Improvement: Disable AWS and Google Batch spot instance auto retry - Improvement: Data Explorer: Remove folder validation - Improvement: Update 204 pipeline schema response description - Improvement: Patch workflow revision - Improvement: Render Parameters UI correctly with new schemas based on 2020-12 draft - Improvement: Upgrade to Angular 16 - Improvement: Pipeline launch form: Delegate form creation to a form builder service - Fix: Connection to Redis SSL server - Fix: `pairingId` declaration in API schema - Fix: Copying empty list for cloud data links - Fix: Visual glitches in launch form - Fix: Datalink status always null - Fix: Update last used field in compute environment when creating a data studio job - Fix: `Terminated by Tower` error ### v24.2.0_cycle23 — 2 September 2024 - Fix: [Data Explorer] enable task working directory navigation using Data Explorer in personal workspaces by adding routing - Fix: Remove -/+ increment buttons from numeric input components in Platform, including compute environment and launch form interfaces - Fix: Hide compute environment variables section actions when component is disabled (previously indicated that environment variables could be edited in this state) ### 24.2.0_cycle21 — 13 August 2024 - Feature: Add global Nextflow configuration support in compute environments - Feature: Add flexibility for pipeline names in workspaces - Feature: Add tag propagation to launch templates - Feature: Add managed identities support for manual Azure Batch compute environments - Feature: Implement custom launch container logic - Fix: Improve workflow launch screen look and feel - Fix: Allow pipeline work directory to be changed during pipeline launch - Fix: Handle special characters in prompt modal confirmation text regex - Bump nf-launcher:j17-24.04.4 - Bump codecommit 0.2.1 ### 24.2.0_cycle20 — 25 July 2024 - Feature: Add code blocks syntax highlighting and background color - Improvement: Role selector drop-down detail - Improvement: Update navbar help & support links - Fix: Disable launch form submit button during form validation - Fix: Update team guest welcome email visuals and copy - Fix: Tag search with underscore - Fix: Add missing gap between shared badge and labels - Fix: Data Studios template override - Fix: View credentials back navigation - Fix: Data Explorer search bar misalignment - Fix: Parameters merging in schema form without key in schema - Bump nf-launcher:24.04.3 ### 24.1.0 - May 2024 - Managed identities: * Allow organization members and collaborators to list managed identities - Data Studios: * Data studio user activity auditlog * Delete checkpoints * Rename checkpoints - Data Explorer: * Multi-download functionality ### 23.3.0 - 16 October 2023 - Feature: Add feedback form to mkdocs - Feature: [Data Explorer M4.2]: use Data Explorer to navigate workflow and tasks work directories - Feature: Do not install aws cli when fusion 2 is enabled - Added: Reverse proxy instructions to the docs - Added: Audit logs to data explorer - Added: Docs page about meta endpoint for firewall configuration - Improved: Audit logs count query by - Improve error message when creating private data link as public - Updated: Git integration page - admonition fix - Fixed: Do not leave search box disabled when there are no results in r… - Fixed: Dataset limit provides misleading result - Fixed: add missing https://*.$host to connect-src CSP headers - Fixed: Missing double quote for _JAVA_OPTIONS value - Fixed: Data explorer previewing Google files instead of downloading - Fixed: Optimization service response proxied by Tower - Fixed: Redisson Hibernate 2nd-level cache config - Fixed: Live updates broadcasting - Fixed: Description of wall time - Migrate: Several Modals to Material design MatDialog - Migrate WorkflowLaunchReportsComponent to use MatDialog - Decrease audit log lifespan for cloud - tw CLI note about spot allocation strategy in AWS CEs - task add download as json option for workflow run parameters - Show cloud data links without schema prefix - [Task] Implement pipelinesecretsprovider for Google Cloud - [Data Explorer M3.2] Support uploading files to bucket - Implement live events endpoint with WebSockets - Set workflow unknown refactor - Permission checker for pipeline launch with simple labels - Remove objects without name from explorer - Delete unused LaunchpadItemComponent - Add support for cloudcache - Creation of public AWS datalinks fails in cloud - Enhancements on the cloud bucket creation dialog - tweak: adjust dataset form buttons according to figma - Adjust batch locations and gcp locations list - Return full error message when JsonParseException - Hide data explorer navigation elements if it is not enabled in the workspace - Configuration overview updates ### 23.2.0 - 31 Jul 2023 - Added: Support for Fargate for head job - Added: Support for Graviton architecture in AWS Batch compute environments - Added: Ability to rename Actions, CEs, Pipelines, and Workspaces - Added: support for AWS SES (simple email service) as alternative to SMTP service for sending emails - Added: Ability to edit the names of Tower entities: - Organizations - Workspaces - Compute environments - Pipelines - Actions - Added: Support for mobile screen layout in **Runs** list page - Allow advanced settings in the AWS ECS config field - Allow Launcher users to create, edit, and upload datasets - Fixed: AWS Batch allocation strategy: `BEST_FIT_PROGRESSIVE` for on-demand CEs and `SPOT_CAPACITY_OPTIMIZED` for spot CEs - Updated: **Runs** list page with new status badges and improved layout - Updated: Enable GPU label, sublabel, and add warning when activated - Increase the AWS Batch Memory / CPUs ratio to 4GB - Harmonize list sorting in **Compute environments** and **Credentials** list pages - Set workflow status to unknown when job status is also in an unknown state ### 23.1.3 - 09 Jun 2023 - Reverted: `Set BEST_FIT_PROGRESSIVE` as default AWS Batch allocation strategy (#5126) - Fixed: Unable to view workflow details on runs page on the newest version of Chrome #5105 - Fixed: AWS SSE setting configuration (#5067) - Fixed: Failing tests - Fixed: Mat drop-down options height (#5134) - Bump: nf-launcher version j17-23.04.2 ### 23.1.0 - 28 Apr 2023 - Added: Fusion logs download (#4385) [49eb6dbe] - Added: Fusion support for Google Batch (#4654) [968d9fb1] - Added: Missing launch option in pipeline action menu (#4441) [56313780] - Added: Source reference to launch entity (#4527) [bd073128] - Added: Support for AWS Parameters Store (#4563) [0f9f5400] - Added: Teams management to admin panel (#4553) [8e019921] - Added: **Save run as pipeline** (#4610) [a14e1280] - Added: Workspace selection in All runs page [b574db06] - Added: Launchpad redesign with list and cards views (#4110) [92345120] - Added: Ability to export dashboard data as CSV (#4463) [765931ad] - Added: Azure repos credentials (#4012) [f03f8a55] - Added: The possibility to customize the log format (#4558) [3891345c] - Added: Wave pairing via websockets (#4624) [cf16292e] - Added: Dashboard stats date filter (#4575) [86e95d3e] - Added: `AWS_MAX_ATTEMPTS` and `AWS_RETRY_MODE` to Batch launch environment (#4738) [e7ec2c96] - Allowed: S3 `PutObjectTagging` to instance role created by Batch Forge (#4511) [c8c8e76a] - Allowed: Exact match search filters (#4396) [d90acc18] - Allowed: To share a Tower Agent connection (#4395) [1cfaee91] - Allowed: The customization prefix of Batch Forge resources (#4693) [67072462] - Move workflow deletion audit event to service method (#4531) [9b56ad79] - Remove required check from "headQueue" field in grid platform providers (#4655) [782ab02d] - Improved: Fusion v2 support for EBS disk (#4740) [e1d280d1] - Improved: Config properties documentation reference (#4757) [01d08d9d] - Improved: Support for AWS SSM as Params store (#4824) [3e2c568d] - Improved: Trace service removing blocking queue (#4427) [1c788612] - Increase 10 min length for pwd hint (#4606) [6adaba95] - Deprecate Fusion v1 (#4694) [74fb5bd6] - Fixed: Partial failure workflow status icon shows green check (#4371) [981aeb26] - Fixed: Missing AWS Cloudstream logs (#4476) [3d88a618] - Fixed: NPE when retrieving progress usage data (#4621) [85c4836c] - Fixed: Bug that throws ConcurrentModificationException while cancelling tasks (#4656) [9d0eda97] - Fixed: Cancellation of a workflow already terminated (#4622) [d665beeb] - Fixed: "Row size too large" MySQL problem (#4688) [793471da] - Fixed: Incorrect loading of Runs page after launching a pipeline (#4530) [b297bf42] - Fixed: Make OAuth 2 cookies secured (#4478) [904e1e2d] - Fixed: Return HTTP 503 error when Redis is not available (#4605) [fa88e17d] - Fixed: Set name on FSx file system create by Tower (#4393) [cb631a72] - Fixed: Datasets page CSV viewer crashes if there is an empty column and first row as header is checked (#4489) [21275c9a] - Fixed: Handle unexpected error when accessing Azure repos with node creds (#4707) [6df882f0] - Fixed: Relaunch workflow form does not populate the CE field if initial CE was deleted (#4538) [1fc7494f] - Fixed: Do not show incomplete text on Launchpad for Launcher users (#4495) [1ed88626] - Fixed: Navigate to Pipeline detail from "Pipeline successfully saved" notification (#4774) [0420c0d8] - Fixed: Prevent changing launch work dir inside pipeline input form (#4408) [496827ea] - Fixed: Properly display default Launchpad sort option (#4492) [1e712aa3] - Fixed: Remove duplicate ECS config input in AWS CE form (#4423) [52d057ab] - Fixed: Remove secrets controls if CE does not support them (#4714) [f3137ca7] - Fixed: Restore Launchpad loading indicator (#4509) [9b3fbc26] - Fixed: Sanitize characters in job and workflow error text messages (#4712) [0e6b2b7d] - Fixed: Tag correctly compute environment and service role when resource (#4379) [ed96b5a6] - Fixed: Workflow deletion failure when has a launch record associated (#4786) [9778e579] - Fixed: Workflow launch form autoselects CE when workspace is shared (#4744) [9b6c5df8] - Bump: Version nf-launcher:j17-23.04.1 [72eaa795] - Bump: Micronaut to version 3.8.5 (#4324) [79c1e50c] ### 22.4.2 - 21 Feb 2023 - Fixed: Issue retrieving execution logs from CloudWatch (#4476) [638513b7] - Fixed: Issue setting AWS CloudWatch custom log group name (#4475) [f020719c] - Chore: Improve cloudwatch labels (#4498) [69b790fa] - Bump: nf-launcher:j17-22.10.7 [a7b6fd26] ### 22.4.1 - 10 Feb 2023 - Fixed: Add auto height to selectable columns (#4409) [e4f62488] - Fixed: Remove duplicate ECS config input in AWS CE form (#4423) [3dbb0dad] ### 22.4.0 - 6 Feb 2023 - Feat: All workflow runs page (#3777) [b89ba895] - Feat: Refresh the dashboard data every 5 seconds (#3935) [dd65935d] - Feat: Support for Gitea provider (#3995) [c1640d7b] - Feat: Allow resume workflow in different CEs having compatible work directory (#4169) [ae782606] - Feat: AWS Batch ECS custom configuration [1a5faf12] - Feat: Wave pairing naming refactor (#4300) [c9c9dc8f] - Feat: Pipeline and workflow resource labels customization (#3955) [b1fa9756] - Added: `europe-west2` location for Google Batch (#4203) [8bfda45c] - Added: Missing lvm2 package to be able to mount multiple NVMe disks as a single volume (#4091) [4ffba872] [80c72e1c] - Added: Support for custom CloudWatch logs group name (#3866) [97156c57] - Added: Missing sourceWorkspaceId OpenAPI parameters (#4050) [72fa1822] - Added: Fusion NVMe support (#3942) [9ea72cc9] - Added: Credentials/keys endpoint [25906e00] - Fixed: Prevent calling BE with undefined `workspaceId` (#4349) [25943dd3] - Fixed: Relaunch of Tower actions should preserve parameters (#4270) [2a232104] - Fixed: iframe for HTML reports (#4135) [bb878118] - Fixed: Azure CE creation fails in CI because of auto-scaling formula (#4180) [35543dd4] - Fixed: Replace clr running color with the proper primary one (#4222) [8e424cf5] - Fixed: Add explicit `Authorization` header as param name to security scheme in order to fix issue with wrong header in OpenAPI GUI requests (#4218) [48fdb2fa] - Fixed: Improve search syntax error handling (#4020) [a19ffbd5] - Fixed: AWS Batch kernel issue causing OOM error (#4015) [7a8c5488] - Fixed: Move authentication method to private app for HubSpot (#3960) [a8aa6e79] - Fixed: Additional joins for audit publisher entity (#3934) [23deb598] - Chore: gh actions workflows updates to suppress deprecation warnings (#4342) [b9bce117] - Chore: Implements patch gcp registry credentials to remove newlines (#4307) [aed573ff] - Chore: Increase `pipeline/projectName` limit to 200 chars (#4317) [beb79d8d] - Chore: Run status time enhancements (#4289) [69848871] - Chore: Task 2882/add validation for custom role (#4068) [86967166] - Chore: Increase prod labels limit to 1k [9e5cccd9] - Chore: Update AWS regions (#4118) [99d7f6bb] - Chore: Revert FSx unmount (#4177) [199eb24b] - Chore: When running with Gitpod, create valid AWS credentials with assume role (#4114) [7ed1491f] - Chore: Improve task duration stats (#4106) [4a51d956] - Chore: Update workflow status timing messages (#4075) [9939145b] - Chore: [BREAKING] remove autoinjection of roles when `allowInstanceCredentials` property is true (#4093) [5de61137] - Chore: Limit the time range selection when querying stats (#3993) [e273130d] - Chore: Cache restore and backup via Tower plugin (#3599) [719442fb] - Chore: Set `BEST_FIT_PROGRESSIVE` as default AWS Batch allocation strategy (#3956) [6442dcd8] - Test: Create Playwright e2e tests for Google Life Sciences CEs (#3899) [ba1c1254] - Bump: Upgrade to Java 17 (#3973) [2e915336] - Bump: nextflow 22.10.6 in get started page [28f44796] - Bump: nf-launcher:j17-22.10.6 [570658c5] - Bump: Upgrade backend to Micronaut 3.7 (#3876) [11203a05] ### 22.3.2 - 9 Feb 2022 - nf-launcher:j17-tw-22.3-nf-22.10.6 ## 2022 #### 22.3.1 - 12 Dec 2022 - Fixed: Remove autoinjection of roles when `allowInstanceCredentials` property is true [BREAKING] (#4093) [1d6adc9f] - Fixed: AWS Batch kernel issue causing OOM error (#4015) [f59b9edd] - Bump: nf-launcher:j17-22.10.4 [26da757f] #### 22.3.0 - 4 Nov 2022 - [BREAKING] Added: `batch:TagResource` to Batch instance role [dba6cb34] - Added: Support for Google Batch (#3532) [ba641280] - Added: Support for Resource Labels (#3511) [1fa2dc7e] - Added: Support for Resource Labels for Google Batch (#3836) [157f3cd8] - Added: Support for Wave + Fusion (#3713) [0f49a7cb] - Added: Users and orgs management to admin panel (#3659) [9fda24b6] - Added: Ability to expand boot EBS volume size (#3299) (#3425) [b523c5dc] - Added: Runs dashboard page (#3734) [35073fdb] - Added: Support for txt reports preview (#3862) [bba73371] - Added: Confirmation dialog enhancements (#3470) [bd19b70d] - Added: Unmount FSx lustre filesystem on Spot instance termination (#3430) [155c8a7b] - Added: Run detail page link to both HTML and txt email templates (#3907) [58f5ef4e] - Added: Allow organization owners to access all workspaces in the organization (#3703) [a0fad25f] - Fixed: 3423 optimization configuration not retained on relaunch (#3841) [19b4bbe4] - Fixed: 3654 regression optimization column in workflow list lost (#3655) [10471ade] - Fixed: 3769 delete confirmation message allows prompts to be bypassed without entering delete in the text box (#3770) [ba442e24] - Fixed: 3773 invalid unit for `vol ctxt` and `inv ctxt` at tasks table (#3774) [0e34ae0e] - Fixed: `BitBuckerServer` Git provider #3670 [c91635b0] - Fixed: Container registry name (#3708) [1f42959e] [9dd37809] - Fixed: Missing file existence check for GLS in nf-launcher [7ca43e51] - Fixed: Resume functionality on Google Life Sciences (#3539) [10419c93] - Fixed: Stalling on failing local submit (#3492) [ea82e5f4] - Fixed: **Pre-run script** errors are not displayed in the logs (#3484) [65134954] - Fixed: Cannot add optimization status to unknown response object (#3450) [ac1fd478] - Fixed: Invalid unit in the tasks table (#3714) [53399902] - Fixed: Resume does not work when user has `launch` permission (#3072) [15433b31] - Fixed: Unable to save status for job when a DB exception occurs (#3490) [9788ace0] - Fixed: Escape `qstat` command for Altair PBS batch scheduler (#3489) [adb2b773] - Fixed: Failing test due to phantom job interval on Mysql (#3537) [b4249066] - Fixed: Trim sub-second precision from dates (mysql compat) (#3788) [2ade7174] - Fixed: Disallow dashes in secret names (#3643) (#3644) [81d09056] - Fixed: Invalid job transition to unknown status [ci fast] [65f44fc2] - Fixed: Resource label input parses whole word before `'='` (#3847) [12d6b09d] - Fixed: Admin tests race condition (#3868) [977fbff1] - Fixed: Gray screen when navigating back after opening a task detail (#3873) [3a04872a] - Fixed: Add `ListWorkspaceSettings` permission to admin and maintainer (#3453) [d9bae03a] - Fixed: Added new query for star row deletion and modified test (#3514) [459bc3e4] - Fixed: Broken labels input formcontrol binding (#3656) [139e633a] - Fixed: Broken quick-launch page layout on personal workspace (#3495) [ebd0cf11] - Fixed: Increase the quota limit for datasets (and dataset versions) per workspace to 100 (#3673) [818c4bf5] - Fixed: Bypass name checks if the label name has not changed (case-insensitive) (#3578) [293e5478] - Fixed: Case-insensitive search for orgs and users (#3739) [766d8056] - Fixed: Datasets suggestions for pipelines with schemas that expect tsv type (#3582) [1f48e0de] - Fixed: Disable ngx-bootstrap collapsible component animation (#3727) [a13dcecc] - Fixed: Highlight support nav button when in welcome page (#3798) [312f1c91] - Fixed: Humanize values for duration and realtime in tasks table (#3707) [30819908] - Fixed: Include personal workspace as possible value for last accessed workspace item in local storage (#3885) [151b708a] - Fixed: Inconsistent navigation to an organization when the organization name matches a resource label name [e2e] (#3685) [d045ac0c] - Fixed: Inherit from DataSpecification (#3745) [be04f004] - Fixed: Lazy load workflow details page main tabs (#3857) [8e504625] - Fixed: Make routing service always get routeContext from params when requested [e2e] [ci fast] [a6baca64] - Fixed: Check for `workspace id` in the endpoint URL of an action in the workspace context (#3464) [db80231f] - Fixed: Move credentials keys patching/removal logic into credentials component base (#3765) [4537df99] - Fixed: Prevent double task endpoint invocation (#3830) [49a14f6e] - Fixed: Prevent null reference exception on `humanizeCounter` formatter util (#3785) [e5810dec] - Fixed: Redirect to personal workspace if user is not a participant in any workspace (#3683) [21e98d3c] - Fixed: Redirect to the last route on login after jwt token failed to refresh (#3619) [7ec1cfe3] - Fixed: Remove deprecated share button (#3496) [55b47cd3] - Fixed: Restore inline credentials creation functionality for grid platforms (#3542) [8707a05e] - Fixed: Restore MOAB platform icon (#3821) [e6688528] - Fixed: Restore tasks table column formatters after migration to mat table [e2e] (#3787) [009f5e76] - Fixed: Restore vertical scroll inside inputs (#3853) [df65253c] - Fixed: Set `resume` param depending on workflow completion status [e2e] (#3572) [177a7805] - Fixed: Show actionable error message on unparsable config file (#3451) [3cfd96d6] - Fixed: Small visual bugs fixes (#3837) [ci fast] [1b0a685b] - Fixed: Wrong launchpad layout when pipeline names are long (#3527) [318b02b3] - Chore: Restore workflow reports messaging (#3802) [9640254a] - Chore: Bad request response when query parameters are malformed (#3649) [376def9c] - Tweak: Switch typing method to help prompt display (#3698) [c31b02f3] - Tweak: Required/optional field labels enhancement (#3544) [e7f08557] - Tweak: Allow path variables for grid platform launch directory field (#3883) [6ed1eba6] - Tweak: Apply standard glob surrounding to task list search (#3672) [d66c8740] - Tweak: Check that users with invalid names are not rejected when registering (#3816) [02e89664] - Tweak: Move repo link to repo name in workflow detail header (#3564) [44fdd0ba] - Tweak: Pass date filters when clicking on the run stat inside the dashboard page (#3901) [5cfda8b6] - Tweak: Remove confirmation input from cancel workflow prompt [5d3aca10] - Tweak: Remove redundant logs.length from log view (#3446) [794cbe3b] - Tweak: Set max length of revision field to 100 characters (#3882) [4040166c] - Tweak: Enable angular strict template checking (#3596) [a569e5fe] - Tweak: Display provider icon in credentials/CE selection drop-downs, encapsulate in icon component (#3690) [8a4c7ffd] - Tweak: Do not allow email using a top-level domain hostname (#3526) [0bae08ca] - Tweak: Email validators are out of sync (FE side) (#3778) [0d564656] - Tweak: Establish use of english locale globally in tower-web (#3679) [a40d0483] - Tweak: Customize the head node resources in the launch/relaunch form (#3448) (#3449) [42caa475] - Tweak: Update pages layout (#3481) [24fc32cf] - Tweak: Improve SSH connector resilience + UGE qstat [cbdab74d] - Bump: nf-launcher:j17-22.10.1 [ci fast] [bfc1ea0d] - Bump: Angular 14 (#3660) [130f0ffc] - Make stage URL config (#3700) [b7219259] - Open up all endpoints and parameters related to labels and resource labels (#3814) [bf9a30e8] - Restyling of workflow detail header (#3547) [d2024f66] - Update xpack urls [BREAKING] [700436e5] #### 22.2.4 - 2 Sept 2022 - Fixed: `BitBucketServer` Git provider #3670 [3b4172b] - Bump the quota limit for dataset per workspace to 100 (#3673) [c8df0e6] #### 22.2.3 - 11 Aug 202 - Rollback to nf-launcher:j17-22.06.1-edge [135f5d59] #### 22.2.2 - 8 Aug 202 - Fixed: Resume functionality on Google Life Sciences (#3539) [5b2a50b7] - Fixed: Remove deprecated share button (#3496) [5af149f8] - Bump: nf-launcher@22.08.0-edge [786d43be] #### 22.1.8 - 8 Aug 2022 - Fixed: Resume functionality on Google Life Sciences (#3539) [5b389773] #### 22.2.1 - 5 Aug 2022 - Feat: Unmount FSx lustre filesystem on SPOT instance termination - Fixed: Escape qstat command for Altair PBS batch scheduler - Fixed: Improve SSH connector resilience + UGE qstat - Fixed: Patch invalid job transition to unknown status #### 22.1.7 - 25 Jul 2022 - Improved: SSH connector resilience + UGE qstat [755b6ce4][8e876d22] #### 22.2.0 - 15 Jul 2022 ##### Breaking Changes - The MySql DB driver `com.mysql.cj.jdbc.Driver` has been replaced by `org.mariadb.jdbc.Driver` - Env variable `TOWER_DB_DRIVER` referencing the first should be changed with the latter ##### Other Changes - Feat: Added support for Illumina DRAGEN - Feat: Added support to mysql8 - Feat: Allow access remote pipelines via Tower Agent - Feat: Feature 3025 reports download limit - Feat: Adds used datasets tab to run details page - Feat: Add support for redis password - Feat: Pipeline reports index page - Feat: Feature 2663 / Labels - Feat: Add support for AWS CodeCode repositories - Feat: `runName` filled with random run name by default if not in relaunch mode - Feat: Allow the ability to send cluster options from head queue to child nodes - Feat: Add advanced search capabilities to runs page - Fixed: Error when trying to remove unexistent csv renderer options component - Fixed: Invalid escape of blank chars in URL [ci fast] - Fixed: Issue download report with blanks - Fixed: Nginx proxy pass decoding - Fixed: Solves #3077 by modifying the validation logic - Fixed: Set dataset file mime type depending on file extension - Fixed: Use mdiag command to check MOAB platform - Fixed: Do not force a `main.nf` file at default branch when creating a pipeline - Fixed: Suggest valid runName when launcher resumes - Fixed: Populate timestamps for partial workflow progress updates - Fixed: Enable maintainers to create workspace secrets - Fixed: Prevent infinite redirection when `landingUrl` = `applicationUrl` - Fixed: Change MOAB queue status command - Fixed: Hide workflow run datasets tab in the personal workspace context - Fixed: Add the support for USR2 signal for grid providers launcher script - Fixed: Fix perms for encrypted bucket - Fixed: Missing dataset in workflow run page - Fixed: 3309 compute environment not visible when viewing actions - Fixed: Multiple drop-downs remain when selecting - Fixed: `IllegalArgumentException` on empty config file - Fixed: Can't relaunch failed workflow without commit - Fixed: Cancel button malfunctions in most menus where elements get added - Fixed: Prevent the deletion of a CE when the status is CREATING. - Fixed: Produce two different entries for custom user config and optimized config - Fixed: Tweak: remove "None" item from select inputs when the field is required - Fixed: Fixed the case when optimization config was not shown for workflow details page - Fixed: Disallow relative path workdir - Fixed: Use `NotFound` exception at Google LS provider - Chore: Update `ENVIRONMENT*VARIABLE_NAME` regex to allow `NXF*` env variables - Chore: Update `computeJobRole` and `headJobRole` validation - Chore: Bump ebs-autoscale to version 2.4.6-6ce65d32 [ci fast] - Chore: Add KMS permissions required by EBS autoscale - Chore: Upgrade to Micronaut 3.4.x - Chore: Typography sync between tower and design * Full Changelog: v22.1.5-enterprise...v22.2.0-rc0-enterprise #### 22.1.6 - 15 Jul 2022 - Patch invalid job transition to unknown status [5ac1a4fd] #### 22.1.5 - 7 Jun 2022 - Fixed: Perms for encrypted bucket [96f00f39] - Add the support for USR2 signal to launcher script [40c4ab68] #### 22.1.4 - 1 Jun 2022 - Enable maintainers to create workspace secrets [2d1a225f] - Forward revision when creating a pipeline (#3203) [2ff2f171] - Change MOAB queue status command (#3219) [4eda7f90] #### 22.1.3 - 18 May 2022 - Update Nextflow to 22.04.3 - Bump: nf-launcher:j17-22.04.3 - Bump: nf-jdk:corretto-11.0.15_up1 #### 22.1.2 - 9 May 2022 - Fixed: Add KMS permissions required by EBS autoscale with encrypted volumes [387ed6c3] - Fixed: Update HTTP content security policy to allow host URLs for frames and workers [327b27ac] - Fixed: Minor navigation error when removing unexistent CSV renderer component [a501225c] - Fixed: Issue downloading a report with containing a blank character [70ab2033] - Fixed: Nginx proxy pass decoding break query parameters with blank character [48a2ef6b] - Fixed: Kubernetes control plan URL only allow host name [1b4b1240][da552afc] - Bump: ebs-autoscale to version 2.4.6-6ce65d32 [d52de172] #### 22.1.1 - 25 Apr 2022 - Added: EBS encrypt role policy at AWS forge creation (#2817) [ci fast] - Added: `TOWER_ENABLE_UNSAFE_MODE` setting to allow cookies over HTTP (#3023) [69100d51] - Improved: Cloud price download logs [a0e69b57] - Fixed: Azcopy cache commands (#3022) [4932a54d] - Fixed: AES regular expression [a7b1ed02] - Fixed: Update CSP to allow captcha frame [a984ec39] - Fixed: Download of task log files (#3004) [3389a8d7] - Fixed: Dataset table is not rendered in Safari [ab297ff4] - Fixed: Avoid analytics service making calls when there's no analytics URL (#2991) [fd56afab] - Fixed: NF version in welcome page [c5c8492c] - Allow NXF env variables (#3026) [553015d8] - Remove log trace from workflow limiter [64f8161e] - Bump: nf-launcher:j17-22.04.0 [9e55c873] - Bump: nf-jdk:corretto-11.0.15 as base image [1832c282] #### 22.1.0 - 12 Apr 2022 - Added: Secure cookies [e28a3388] - Added: `GetLogsEvents` perm to AWS Batch instance role [04b18668] - Added: Credentials view page [f3c63483] - Added: ECS pull strategy in user-data template [e1b4914a] - Added: Root users environment when `TOWER_ROOT_USERS` variable is provided [e09db3e5] - Added: Tower system message - Added: Support for JSON formatted logs [92122adb] - Added: Support for AWS agent and logging [6e68fd98][c080e9d4] - Added: Navigate back button to second level screens (#2578) (#2623) (5 weeks ago) - Added: Validation for SSH hostname and username [d0115de0][efb962bf] - Added: Config option to disable user private workspace [9e667bc0] - Added: Share run deprecation banner - Improved: Secrets obfuscation in log file [7e52c76b] - Improved: EBS autoscaling [fe7fe728] - Fixed: Job status is updated in the in-memory tracker before running the job in the local CE platform (#2460) (3 months ago) - Fixed: Normalize dataset name [fcbe417d] - Fixed: Allow dot in AWS ARN string [d5c5cd9e] - Fixed: Issue with K8s compute env stalling in creating status [72c03cd9] - Fixed: Set cookie acceptance cookie path to / e2e [ba0cae7a] - Fixed: EFS and FSx permission when job run with non-root user (#2659) [0e169bb9] - Fixed: Reports at grid and agent platforms [ba397137] - Fixed: Load SLURM CE details in view mode [80cc0e9b] - Fixed: Display dates with YYYY-MM-DD format on runs page [830606af] - Fixed: Unable to download execution log from a workflow with working directory specified just as "bucket" name [d025917c] - Fixed: Prevent the creation of Spot fleet role [95acea2c] - Fixed: Prevent deletion of an active workflow run [ba1f1ce9] - Fixed: Prevent XSS attacks when uploading a datatable file [#2944] (6d98210c) - Allow partial searches [b8788b38] - Allow the use S3 bucket work dir along with EFS or FSx mounts [368d5caa] - Upload encrypted files at AWS S3 [40b87a2e] - Use default listening port (80) [a64852d9] - Increase tower config max size to 3500 character [a01ee72c] - Disable resume for failed workflows [3c2c7ad3] - Set max length validator to the workflow launch form fields [5326114b] - Check valid EFS and FSx mount points [633fdcd8] - Make Dataset api public (#2240) [2fd32c51] - Increase agent websockets payload size to 5Mb [5f3e5428] - 484005bd - Always retry NF process when using AWS sport instances - fe7fe728 - Improve EBS autoscaling (8 days ago) - 8dc800c2 - feature: improve parse the pipeline schema - Default to Nextflow DSL version 1 [e88a3e59] - 8759d92e - Validate launch/relaunch action depending the user role - Upgrade Angular 13 - Upgrade Micronaut 3.x (#2364) - Upgrade logback to version 1.2.8 (#2418) - Bump: log4js from 6.3.0 to 6.4.0 in /tower-web (#2535) - Bump: base image nf-jdk:corretto-11.0.14_2 - Bump: nf-launcher 22.03.1-edge - Bump: base image nf-jdk:corretto-11.0.14_2 [ci fast] [d6113805] #### 21.12.3 - 31 Mar 2022 - Bump base image nf-jdk:corretto-11.0.14_2 [8cc71b91] #### 21.12.2 - 31 Mar 2022 - Fixed: Issue with K8s compute env stalling in creating status [3745e793] - Fixed: Upload encrypted files at AWS S3 [716d2938] - Fixed: EFS/FSx permission when using non-root container (#2659) [002f4426] - Create `/.nextflow` folder in backend container [333a8a68] - Bump: nf-launcher:j17-21.10.6 [8b3d6490] #### 21.12.1 - 3 Feb 2022 - Fixed: Reports endpoint exception on NF CLI workflows [c310c3cf] - Disable H8 stats verbose logging [7e5e08b0] - Enable root users environment when `TOWER_ROOT_USERS` variable is provided [390e079a] #### 21.12.0 - 17 Jan 2022 - Added: Shared workspace feature - Added: Pipeline reports feature [preview] - Added: Dataset public APIs - Added: Tower agent reverse connection - Added: Dataset API public ci fast [942f3f4e3] - Fixed: Auto-normalize inline credentials name (#2405) [9d5453716] - Fixed: Prevent making multiple get pipeline info requests in workflow launch form ci skip [e21619bd1] - Fixed: Set `Launch.resumeLaunchId` only if it's a resume. (#2427) [a784e635b] - Fixed: Possible `connectionId null` reference exception ci skip - Updated: Resources descriptions [538069df9] - Prevent the use of master as default branch (#2499) [791f45a11] - Allow the use of S3 as work directory when using EFS and FSx mounts [6199d8fd6] - Display dates with YYYY-MM-DD format on runs page [5d2f3215a] - Change email template office address [5edfa3a26] - Increase agent websockets payload size to 5Mb [4ce9af8f2] - Bump: nf-launcher 21.10.4 based on corretto:17.0.1 based image #### 21.10.3 - 3 Feb - Enabled: `root` users environment when `TOWER_ROOT_USERS` variable is provided [0ba7190e0] ## 2021 #### 21.10.2 - 10 Dec - Fixed: NPE error when marking unknown status - Bump: nf-launcher 21.10.5 #### 21.10.1 - 8 Dec The `21.10.x` release series starts with `v21.10.1` - Added: Container registry creds for Azure - Added: Datasets feature - Added: Support custom CE environment variables - Added: New Workflows Runs list page - Added: Support for custom landing page - Added: Display job info on workflow general panel (#2142) (#2151) - Improved: landing page config #1996 #748 - Fixed: Make hidden params a part of pipeline input form even if not shown + small fix (#2134) - Fixed: Validate final values of config properties on startup (#2100) - Fixed: Redisson default connection pool size (#2229) - Fixed: Return a bad request when `workspaceId` is not parsable (#2220) #2205 - Fixed: Race condition on repo pull (#2110) - Fixed: Grid platform default launch dir (#2037) - Fixed: Redirect to the Runs page after launch (#2057) - Fixed: Discard deleted entities from name validation queries and rename them (#2052) - Fixed: Download hangs when streaming a S3 file (#2005) - Hide `ebsBlockSize` field from AWS manual config (#2004) - Make hidden params a part of pipeline input form even if not shown + small fix (#2134) - Parallelize Az metadata retrieval - Refactor Google LifeScience head job execution (#1981) - Make sure to authenticate the Google storage (#1984) - Use amazoncorretto:11.0.13 as base image - Minor schema fetching improvement (#2183) - Make sure the workflows list query returns the workflows in a workspace even if they have been starred by other users (#2174) - Bump: nf-launcher 21.10.4 #### 21.06.5 - 10 Dec - Increasing the throttling rate on the ECS agent metadata endpoint (#2338) [51a519691] - Bump nf-launcher 21.10.5 #### 21.06.4 - 25 Nov - Increasing the throttling rate on the ECS agent metadata endpoint (#2338) - Bump: nf-launcher 21.10.3 #### 21.06.3 - 19 Nov - Bump: nf-launcher 21.10.1 #### 21.06.2 - 5 Oct - Fixed: Race condition on repo pull when using Kubernetes platform (#2110) [90b1dbe7c] - Fixed: Altair `infoCli` method [f5226d03d] - Hide `ebsBlockSize` field from aws manual config (#2004) [24650f47c] - Connection pool properties log can leak sensitive data [1878a2e4f] - Changing workspace multiple requests fix (#1985) [5f66be4b0] - Make sure to authenticate the Google storage (#1984) [398897422] #### 21.06.1 - 27 Aug - Fixed: OpenId attributes blows up response header - Fixed: Mention in the Get started page how setup Tower workspace id - Fixed: Tune AWS client caching timeout - Fixed: Pipeline params JSON parsing on Windows client #1949 - Fixed: Add better control of cron/redis config (#1944) [45579b5bd] - Fixed: DB migration detected table on foreign schema - Bump migtool 1.0.2 705c905db - Fixed: For the case when blur event handler was executed before chip selection event handler #1932 - Fixed: Bug 1926/Modify bootDiskSize Config Param #1931 #### 21.06.0 - 26 Jul - Added: Support for AWS Host credentials and role-based permissions - Added: Support for AWS EFS storage - Added: Ability to specify custom AWS CLI path - Added: AWS regions `eu-south-1` and `af-south-1` - Added: `uploadChunkSize` configuration parameter to abstract k8 provider (#1820) - Fixed: Launch form `pipelineParameters` after navigating to pipeline input form (#1847) - Fixed: Error report for missing invalid/creds - Fixed: GitHub action creation - Fixed: Prevent GitHub delete action hook exception - Display team ID in team page - Disable `index.html` caching in `nginx.config` - Limit compute env error message length - Invalidate compute envs associated to deleted credentials - Bump: Nextflow launcher 21.04.3 - Bump: groovy 3.0.8 #### 21.04.9 - 2 Aug - Fixed: Nextflow plugins deps #### 21.04.8 - 14 Jul - Improved: Error report for missing/invalid AWS creds [b5c550236] - Do not trigger config profiles field reset after patching the workflow launch form (#1836) [f863c8cbb] #### 21.04.7 - 21 Jun - Added: Head service account to deployment pod (#1773) [6e0e7281f] - Parse profiles using the correct revision at launch time (#1572) [e78eda2f2] #### 21.04.6 - 21 Jun - Fixed: GitHub action creation - Fixed: The case when the drop-down was over-shadowing other fields - Change schema and default params usage - K8s use deployment for service pod #### 21.04.5 - 8 Jun - Fixed: Action update settings (#1679) [a485c5d75] - K8s head pod custom specs (#1668) [d82a864c8] - Allow selecting empty values for schema drop-down fields (#1674) [d27e5b905] #### 21.04.4 - 3 Jun - Fixed: Missing scm server and platform #### 21.04.3 - 2 Jun - Fixed: Pattern test validator when the value is empty - Fixed: Navigation drop-down display when user has no `CreateOrganization` permission #### 21.04.2 - 1 Jun - Fixed: FSx creation failure #### 21.04.1 - 31 May - Added: Timeout on AWS Forge waiters - Added: Log response to UI error message (#1602) [2d705289c] - Added: Support for BitBucket server [8c09241e3] - Fixed: Admin project security vulnerabilities (#1637) [972255faf] - Fixed: Missing GitLab token creds (#1631) [c188a76b2] - Fixed: Action launch user (#1615) #1611 [691fe4c9d] - Use `RegExp.test` for json schema pattern validation + small pipeline input form fix (#1619) [d9d2cd317] - Reorganized login page (#1635) [9a46f393a] - Do not config mail proxy using global proxy settings (#1626) [e1c8b1dab] #### 21.04.0 - 21 May - New organizations feature - New teams feature - New workspace feature - New launchpad feature - Added: Support for private Git repositories - Added: Support for Nextflow timeline downloads - Fixed: Issues with Compute environment status reporting - Updated: Nextflow runtime to version 21.04.0 #### 21.02.5 - 12 May - Fixed: S3 log downloads when using fusion feature #### 21.02.4 - 29 Apr - Bump Nextflow 21.04.0-edge required to fix BitBucket server #### 21.02.3 - 21 Apr - Fixed: Cloud price downloader using Seqera Labs endpoint - Fixed: Error message when S3 bucket is not accessible #### 21.02.2 - 14 Apr - Fixed: Missing commit ID when resuming execution fails to start #### 21.02.1 - 12 Apr - Fixed: Support for custom bitbucket servers - Bump: Nextflow launcher 21.04.0-edge #### 21.02.0 - 16 Mar - Added: Azure Batch provider - Added: Altair PBS pro provider - Added: `sessionId` to workflows search-box criteria - Added: Support for multiple GLS zones - Added: Grid provider head job options - Added: Support for AWS Batch cost percentage - Added: Azure Batch Forge - Added: Support for Grid Engine batch scheduler - Added: K8s service pod - Added: Support for Tower license - Improved: Detection of NF config profiles #1074 - Fixed: Issue on work dir path composition with ending slash - Fixed: Issue when retrieving non-existing file via SSH/SCP - Fixed: Issue resolving non-canonical GitHub/Gitlab project name #353 - Fixed: Issue with AWS Batch allocation strategy #931 - Fixed: Phantom job unknown status - Fixed: Prevent requeuing of mail with invalid addresses - Fixed: Issue on creating AWS CE with manual config - Updated: Backend base image to corretto:11.0.10 - Updated: nf-launcher to 21.03.0-edge - Upgrade to Angular 11 - Use Kubernetes Java-client 10.0.1 #### 20.12.4 - 23 March - Added: Support for AWS Marketplace #### 20.12.2 - Feb 16 - Fixed: Phantom job status - Fixed: Invalid email rejection #### 20.12.1 - 21 Jan - Fixed: Head job submission to head queue when using batch schedulers eg. Slurm, GridEngine, LSF #### 20.12.0 - 11 Jan - Added: Support for Kubernetes clusters - Added: Support for AWS EKS clusters - Added: Support for Google Kubernetes Engine clusters - Added: Support for Launch stub-run feature - Added: AWS Batch Fusion mounts - Improved: System security - Upgraded: Java runtime to version 11 - Upgraded: Micronaut runtime to version 2.1 - Upgraded: Nextflow launcher to version 20.12.0-edge - Enhanced security, API uses bearer auth #### 20.10.4 - 11 Jan - Improved: SSH client debugging - Fixed: Backend container security ## 2020 #### 20.10.3 - 30 Nov - Fixed: Migration tool when using MariaDB - Fixed: Execution issue with Batch forge when creating a new FSx file system - Fixed: Invalid warn message #### 20.10.2 - 2 Nov - Added: Support for `TOWER_LAUNCH_CONTAINER` env var [6fd06581f] - Fixed: EBS autoexpand volume issue + add ebs block size [cbdb8b1af] - Disable cache on problematic cached query (#608) [11ef28e10] - Allow pre-run script to modify launch env [56ed5cca1] #### 20.10.1 - 27 Oct - Updated: Nextflow launcher container #### 20.10.0 - 22 Oct - Added: Workflow sharing feature - Added: Support for Slurm batch cluster - Added: Support for IBM LSF batch cluster - Added: Customizable navbar menu - Added: Built-in support for MariaDB - Added: Built-in support for Google SSO - Added: Auth allow-list emails - Improved: System security - Updated: Java mail 1.6.2 #### 20.08.0 - 28 Aug - Added: Support for AWS FSx mount name to Launch feature - Added: Batch Forge option to to Launch feature - Added: Support for GPU instances to Launch feature - Added: Execution and tasks logs view and downloads features - Added: Support for Compute env AWS advanced options - Added: Compute environment primary option feature - Added: Pipeline Actions - Added: Support for GA4GH WES API (beta) - Added: Status & process name filtering to dashboard - Added: Favicon for dark theme - Added: Login pass-through mechanism - Improved: Workflow general stats tooltips - Fixed: AWS Batch workflow cancellation - Fixed: Issue when launching projects w/o config file - Fixed: Issue on port and scheme forwarding - Fixed: Local repositories configuration issue - Updated: Launch base image to AWS corretto:262 - Updated: MN version 1.3.7 #### 20.06.1 - 12 Aug - Fixed: Reverse proxy scheme and port forwarding when using local Docker environment #### 20.06.0 - 16 Jun - Added: Pipeline Launch feature - Added: Pipeline execution cancellation - Added: Tomcat DB connection pool - Improved: UI look and feel - Improved: security - Improved: OAuth login - Upgraded: Micronaut runtime to 1.3.3 #### 20.05.1 - 12 May - Add: `TOWER_SECURITY_LOGLEVEL` env variable for security module debugging - Path OpenID connect upgrading MN security to 1.2.3 #### 20.05.0 - 28 Apr - Added: Support for OpenId connect - Added: Limit to max records returned - Improved: K8s deployment descriptors - Fixed: Critical issue saving tasks - Fixed: Invalid tag deserialization error --- ## Release notes for Seqera Cloud version 24.1.x ## Data Studios Data Studios is now publicly available for Seqera Cloud. Data Studios closes the loop from development to deployment and insights, allowing you to create, manage, and share notebook environments in Seqera with the click of a button. It's now easier than ever to transition Nextflow-generated data to JupyterLab, RStudio, and VSCode environments with pre-built templates that can easily leverage existing compute environments and data. Data Studios also makes it seamless to work across teams with multi-user support, built-in authentication, and automatic snapshots as you work that enable collaboration and reproducibility while remaining secure. ## Data Explorer Data Explorer is now Generally Available, with an even more exciting update - multi-file and multi-folder download capability! This allows users to effortlessly download entire datasets of pipeline results with just a few clicks and share them with their team. This update bypasses the need for cloud credentials or complex DevOps configurations, offering a user-friendly alternative to traditional cloud storage services without the hassle of command-line interface wrangling or intricate user interfaces. --- ## Authentication The Seqera CLI uses your Seqera Platform account to authenticate you with Co-Scientist. This page covers how to log in and out, authenticate in automated environments, manage your organization, and how token refresh works. ## Log in To authenticate with your Seqera Platform account, run: ```bash seqera login ``` This will: 1. Open your default browser to the Seqera login page. 1. Prompt you to sign in with your Seqera Platform credentials. 1. Automatically capture the authentication token. 1. Display a success message in your terminal: ```console [Login] Starting Seqera CLI authentication... [Login] ✓ Authentication successful! [Login] ✓ Organization set: ``` ## View session status To view your current session status, run the `/status` command: ``` /status ``` This shows your authentication status and organization details. ## Add access tokens for automation For automated environments, provide a Seqera Platform access token directly using the `SEQERA_ACCESS_TOKEN` environment variable: ```bash export SEQERA_ACCESS_TOKEN= ``` When this environment variable is set, the CLI skips the OAuth login flow and uses the provided token directly. ## Point a development build at the hosted Co-Scientist backend If you are testing a development build of the CLI against the hosted production Co-Scientist service, set the following environment variables before starting `seqera ai`. | Variable | Purpose | Example value | | --- | --- | --- | | `SEQERA_AI_BACKEND_URL` | Co-Scientist backend endpoint used by the CLI | `https://ai-api.seqera.io` | | `SEQERA_AUTH_DOMAIN` | Platform API base URL used for browser-based login | `https://cloud.seqera.io/api` | | `SEQERA_AUTH_CLI_CLIENT_ID` | OAuth client ID for the Seqera CLI | `seqera_ai_cli` | | `TOWER_ACCESS_TOKEN` | Platform personal access token used instead of browser login | `` | Use the OAuth login flow: ```bash export SEQERA_AUTH_DOMAIN=https://cloud.seqera.io/api export SEQERA_AUTH_CLI_CLIENT_ID=seqera_ai_cli export SEQERA_AI_BACKEND_URL=https://ai-api.seqera.io ``` Use a Platform personal access token instead of browser login: ```bash export TOWER_ACCESS_TOKEN= export SEQERA_AI_BACKEND_URL=https://ai-api.seqera.io ``` :::note You only need `SEQERA_AUTH_DOMAIN` and `SEQERA_AUTH_CLI_CLIENT_ID` when using the OAuth login flow. ::: This command revokes your current authentication token and removes locally stored credentials. You will need to re-authenticate on next use. ## Manage organizations The Seqera CLI operates against one organization at a time, which determines billing. Use `seqera org` commands to view or change the active organization. View your current organization: ```bash seqera org ``` List all organizations: ```bash seqera org list ``` Switch organization: ```bash seqera org switch ``` Clear organization selection: ```bash seqera org clear ``` ## Refresh tokens The Seqera CLI automatically refreshes your authentication token when needed. You are not required to log in again unless: - You explicitly log out - Your refresh token expires (typically after extended inactivity) - Your Seqera Platform account permissions change ## Log out To sign out from the current session, run: ```bash seqera logout ``` ## Learn more - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Coding agents The `seqera skill` command installs a skill file that lets your coding agent use Co-Scientist as a subagent. Once installed, the agent can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. ## Supported agents Co-Scientist installs as a skill into any of the following agents. Each guide covers installation, update, and the available `seqera skill` options for that agent: - [Claude Code](./skill-claude-code.md): Install the skill for [Claude Code](https://claude.ai/code) - [Codex](./skill-codex.md): Install the skill for [Codex](https://openai.com/codex) - [GitHub Copilot](./skill-github-copilot.md): Install the skill for [GitHub Copilot](https://github.com/features/copilot) - [Antigravity/Gemini](./skill-antigravity.md): Install the skill for [Antigravity/Gemini](https://blog.google/technology/google-deepmind/gemini-model-thinking-updates-march-2025/) - [Other coding agents](./skill-other-agents.md): Install the skill for Cursor, OpenCode, Pi, Windsurf, and others --- ## Command approval Co-Scientist can execute local commands and edit files in your environment. This page explains approval modes that control which operations run automatically versus which require your permission, including dangerous commands, workspace boundaries, and best practices. :::info Starting a persistent task with `/goal ` switches the session to `full` approval mode automatically so Co-Scientist can continue working without repeated prompts. ::: ## Approval prompts When a command requires approval, you will see a prompt similar to: ``` APPROVAL REQUIRED (default mode) Command: rm -rf ./build/ [1] Yes, approve this command [2] Always approve this session [3] No, reject Press 1, 2, or 3 to choose ``` You can: - **1**: Run the command once (or press Enter) - **2**: Run the command and auto-approve all commands for the rest of the session - **3**: Reject the command (or press Escape) ## Approval modes Approval modes control which local commands Co-Scientist can execute automatically and which require your explicit approval. This provides a balance between convenience and safety when working with local files and commands. There are three approval modes: | Mode | Description | Best for | |------|-------------|----------| | **basic** | Only safe, read-only commands run automatically | Maximum security | | **default** | Safe commands and workspace file edits run automatically | Typical development | | **full** | Everything except dangerous commands runs automatically | Experienced users | You can set the approval mode when starting the CLI: ```bash seqera ai --approval-mode full ``` Or change it during a session using the `/approval` TUI command: ``` /approval basic ``` ### Basic **Rule**: Only safe, read-only commands run automatically. Everything else requires approval. This is the most restrictive mode. The assistant can only auto-execute commands that view information without making changes. **Auto-executes**: - `cat` - View file contents - `ls` - List directory contents - `pwd` - Show current directory - `head` - View file beginning - `tail` - View file end - `tree` - Display directory tree - `echo` - Print text (without file redirection) - `date` - Show current date/time - `whoami` - Show current user - `env` - Display environment variables - `printenv` - Print environment variables - `stat` - Show file status - `uptime` - Show system uptime **Requires approval**: All other commands, including file edits, directory creation, and any other command execution. Safe commands that include file redirections (e.g., `echo "hello" > file.txt`) also require approval. **Use when**: You want maximum control and visibility over every action the assistant takes. **Examples**: ``` > Create a new file called test.txt with "hello world" APPROVAL REQUIRED (basic mode) Command: Write ./test.txt [1] Yes, approve this command [2] Always approve this session [3] No, reject ``` ### Default **Rule**: Safe commands and file operations within your workspace run automatically. All other commands require approval. This is the recommended mode for most users. It allows productive workflow while protecting system files and preventing destructive operations. **Auto-executes**: - All safe commands from basic mode (without file redirections) - File edits **within your current workspace**: - Creating files (`touch`, file creation) - Editing files (text modifications) - Creating directories (`mkdir`) - Copying files (`cp` within workspace) - Moving files (`mv` within workspace) **Requires approval**: - File operations **outside your workspace** - All dangerous commands (see below) - Commands with file redirects to paths outside workspace - All other commands (e.g., `curl`, `wget`, `git`, `npm`, `python`, etc.) **Use when**: You're doing typical development work and want convenience without compromising safety. **Examples**: ``` > Create a new file called test.txt with "hello world" Created ./test.txt ``` File creation in the workspace runs automatically. ``` > Edit /etc/hosts APPROVAL REQUIRED (default mode) Command: Edit /etc/hosts [1] Yes, approve this command [2] Always approve this session [3] No, reject ``` Editing outside the workspace requires approval. ### Full **Rule**: Everything runs automatically except explicitly dangerous commands. This is the most permissive mode. Use it when you fully trust the assistant's actions and want minimal interruption. **Auto-executes**: All commands except those on the dangerous list. **Requires approval**: Only dangerous commands (see below). **Use when**: You're an experienced user comfortable with automated command execution, or when working in an isolated/disposable environment. ## Dangerous commands These commands **always require approval** in any mode: | Command | Risk | |---------|------| | `rm` | Delete files/directories | | `chmod` | Change file permissions | | `chown` | Change file ownership | | `kill` | Terminate processes | | `killall` | Terminate multiple processes | | `pkill` | Kill processes by name | | `sudo` | Execute as superuser | | `dd` | Low-level data operations | | `mount` | Mount filesystems | | `umount` | Unmount filesystems | | `mkfs` | Create filesystems | | `reboot` | Restart system | | `shutdown` | Power off system | **Examples**: ``` > Create files and directories as needed Created ./src/utils.py Created ./tests/test_utils.py Created ./config/settings.json ``` Most operations run without prompts. ``` > Delete the build directory APPROVAL REQUIRED (full mode) Command: rm -rf ./build/ [1] Yes, approve this command [2] Always approve this session [3] No, reject ``` Dangerous commands still require approval. ## Workspace boundaries In **default** mode, the "workspace" is your current working directory and its subdirectories. File operations are evaluated as: - **Inside workspace**: `/path/to/workspace/src/file.txt` - auto-executes - **Outside workspace**: `/etc/config` or `~/other-project/file.txt` - requires approval The workspace is set to your current directory when you start the CLI: ```bash # Workspace is /home/user/my-project cd /home/user/my-project seqera ai ``` ## Best practices - **Start with default mode**: It provides a good balance for most workflows - **Use basic mode for unfamiliar projects**: When exploring new codebases - **Reserve full mode for trusted contexts**: Disposable environments or well-understood tasks - **Review dangerous command prompts carefully**: These commands can have significant impact ## Learn more - [Co-Scientist](index.md): Co-Scientist overview - [Installation](./installation): Detailed installation instructions - [Authentication](./authentication): Log in, log out, and session management - [Use cases](./use-cases.md): Co-Scientist use cases - [Credits](./credits.md): Co-Scientist credits and how to request more - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Using Co-Scientist Use Co-Scientist day to day: explore common tasks, switch between modes, manage sessions, add skills, control command approval, and organize your workspace. ## In this section - [Use cases](./use-cases.md): Common tasks you can do, with example prompts - [Modes](./modes.md): Work in build, plan, and goal modes - [Sessions](./sessions.md): Start, continue, resume, and exit sessions, and run non-interactively - [Skills configuration](./skills.md): Discover, create, and install skills - [Command approval](./command-approval.md): Control which commands run automatically - [Code intelligence](./nextflow-lsp.md): Language-server support for Nextflow, Python, and R - [Projects](./projects.md): Organize workspace resources into projects using Platform labels - [Credits](./credits.md): Co-Scientist credits and how to request more --- ## Credits Co-Scientist usage on Seqera Cloud is metered through credits. Users receive a monthly credit allowance. Organizations can purchase additional credits, managed at the organization level and shared across all users. ## Usage Each user receives a monthly included usage allowance for Co-Scientist. The allowance refreshes at the start of every month and varies by your organization's plan tier. Co-Scientist displays your consumption as a percentage of this allowance. ## Drawing from the credit pool When a user exceeds their monthly included allowance, further Co-Scientist activity draws from the organization's shared credit pool. If both your included allowance and your organization's credit pool are exhausted, Co-Scientist access pauses until credits are added or your allowance refreshes at the start of the next month. ## Check your balance Run `/credits` in an interactive Co-Scientist session to view your organization's credit balance and your usage against your allowance. ## Request more credits [Contact us](https://seqera.io/platform/seqera-ai/request-credits/) to request additional credits for your organization. ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Co-Scientist in Seqera CLI Co-Scientist is Seqera's AI assistant for bioinformatics. You interact with it through the [Seqera CLI](./installation.mdx) (`seqera ai`) to build, run, and debug Nextflow pipelines, manage your data, and drive Seqera Platform from a single terminal session. It combines self-service bioinformatics, conversational intelligence, and autonomous execution in one experience. Co-Scientist works across three contexts: - **Your Seqera Platform workspace**: View and manage workflows, pipelines, and data through your authenticated account. - **Your local environment**: Run commands and edit files in your working directory, with configurable approval controls. - **AI capabilities**: Natural language understanding, code generation, and intelligent suggestions. ## Get started To get started with Co-Scientist: 1. Install Seqera CLI: ```bash npm install -g seqera ``` 1. Log in to Seqera: ```bash seqera login ``` 1. Start your first session: ```bash seqera ai ``` See [Installation](./installation.mdx) for prerequisites, updates, and development builds. Then see [Quickstart](./quickstart.md) to walk through your first session. ## What you can do Co-Scientist helps across the full pipeline lifecycle, from writing code to running it on Seqera Platform: ### Develop pipelines Generate Nextflow configurations and pipeline schemas, convert scripts from other languages (WDL, R) to Nextflow, and discover over 1,000 nf-core modules with ready-to-run commands. Build reproducible Wave containers from conda or pip packages without writing a Dockerfile. Real-time LSP code intelligence detects errors and powers AI navigation across Nextflow, Python, and R files. ### Run and debug on Platform Launch, monitor, and debug Nextflow workflows from your terminal with real-time status, logs, and run metrics. Browse cloud storage through data links, manage datasets, generate upload and download URLs, and access reference genomes. Co-Scientist has full access to your compute environments, datasets, and workspace. ### Work your way Interact in plain English, or use reusable [skills](./skills.md) exposed as slash commands in the `/` palette. Switch between [build, plan, and goal modes](./modes.md) to match execution, analysis, or long-running tasks. Resume earlier sessions with `seqera ai -c`, and organize workspace resources into [projects](./projects.md) using Platform labels. ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Installation The Seqera CLI runs in your terminal on macOS, Linux, or Windows (via WSL). It connects to Seqera Platform and to the Co-Scientist backend so you can build, run, and debug Nextflow pipelines from a single interactive session. This page covers how to install, update, and uninstall the CLI, and how to switch to a development build. :::info[**Prerequisites**]{#prerequisites} You will need the following to get started: - Node.js 18 or later - macOS, Linux, or Windows with WSL - A Seqera Platform account ([sign up for free](https://cloud.seqera.io)) ::: ## Install the CLI To install the CLI with the Platform install endpoint, run: ```bash curl -fsSL https://ai.seqera.io/install | bash ``` Then confirm the CLI is on your PATH: ```bash seqera --version ``` To install the CLI globally with npm, run: ```bash npm install -g seqera ``` Then confirm the CLI is on your PATH: ```bash seqera --version ``` ### Install a development build To install the latest pre-release, use the development channel: ```bash curl -fsSL https://ai.seqera.io/install | bash -s -- --channel dev ``` To install the latest pre-release, run: ```bash npm install -g seqera@dev ``` The `@dev` tag tracks the latest pre-release CLI. Use it only to test unreleased features. Otherwise install the default tag. To point a development build at the hosted Co-Scientist backend, set: ```bash SEQERA_AI_BACKEND_URL=https://ai-api.seqera.io ``` See [Authentication](./authentication.md#point-a-development-build-at-the-hosted-co-scientist-backend) for the full environment variable reference. ## Update the CLI To update the CLI, run the install endpoint again. The install script updates the CLI in place: ```bash curl -fsSL https://ai.seqera.io/install | bash ``` To update the CLI to the latest published version, run: ```bash npm update -g seqera ``` If you use Co-Scientist as a skill for a coding agent, sync your installed skills with the new CLI version after upgrading: ```bash seqera skill check --update ``` This scans both local and global installations by default. Pass `--global` or `--local` to narrow the scope. ## Uninstall the CLI To remove the CLI from your system, run: ```bash rm ~/.config/seqera-ai/* rm ~/.seqera/bin/seqera ``` To remove the CLI from your system, run: ```bash npm uninstall -g seqera ``` ## Learn more - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Modes Co-Scientist offers three modes that control how much autonomy it has in a session. Choose the right level for each task with [Build mode](#build-mode), [Plan mode](#plan-mode), and [Goal mode](#goal-mode). ## Build mode Build mode is the default interactive mode. Co-Scientist can: - Read and search files - Execute commands - Edit or create files - Carry out workflow changes directly in your workspace Use build mode for implementation work, debugging, code generation, and file edits. ## Plan mode Plan mode is optimized for analysis and implementation planning. In plan mode, Co-Scientist focuses on: - Understanding the problem - Comparing approaches and trade-offs - Producing a step-by-step implementation plan - Reading files and searching code for context Plan mode blocks write and execution tools, including: - `execute_bash_local` - `write_file_local` - `edit_file_local` - `create_directory_local` If the assistant tries to use one of these tools, the request is rejected and the assistant is told to switch back to build mode. For example: ```text Compare whether I should add FastQC or fastp as the first QC step in this RNA-seq pipeline, including the workflow changes each option would require ``` ```text Plan the work to add GPU support to this pipeline ``` ```text Inspect this repository and outline the changes needed for Seqera Platform deployment ``` ## Switch between build mode and plan mode Toggle modes during a session with `Shift+Tab`. You can also: - Check the current mode in the composer footer. - Run `/status` to view the current mode alongside session and LSP status. - Use `/help` to see mode-aware command guidance. ## Goal mode Goal mode is a persistent workflow for longer tasks. Set a goal with: ```bash /goal ``` For example: ```text /goal migrate this pipeline to DSL2 and add nf-tests ``` ```text /goal update this workflow for AWS Batch and verify the config ``` When goal mode is active, Co-Scientist: - Keeps working toward the same objective over multiple model attempts. - Automatically continues if more work is needed. - Stops when the goal is complete or the goal attempt limit is reached. - Switches approval mode to `full` so work can continue without repeated prompts. Goal mode commands: - `/goal` - `/goal off` Run `/goal` without arguments to inspect the current goal. Run `/goal off` to disable goal mode. Co-Scientist currently gives goal mode up to **3 model attempts** before it stops and asks you to start a new goal. ## Keyboard shortcuts | Shortcut | Action | |----------|--------| | `Shift+Tab` | Toggle between build mode and plan mode. | | Ctrl+Enter | If your terminal supports it, interrupt the current response and send a queued follow-up immediately. | | `Esc` | Clear a queued follow-up or interrupt the current response. | ## Learn more - [Sessions](./sessions.md): Start, continue, resume, and exit sessions - [Skills configuration](./skills.md): Discover, create, and install skills - [Command approval](./command-approval.md): Control which commands run automatically - [Use cases](./use-cases.md): Seqera CLI use cases - [Credits](./credits.md): Co-Scientist credits and how to request more - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Code intelligence When you ask Co-Scientist to help with code in your workspace, it uses language server (LSP) context to provide: - Explanations for errors and warnings in your code. - Context-aware completions and suggestions. - Better navigation and understanding across project files. For Nextflow projects, this includes diagnostics and code intelligence for scripts and config files. ## Language support | LSP Server | Extensions | Requirements | |------------|------------|--------------| | Nextflow | `.nf`, `.config` | Java 17+ installed | | Python (Pyright) | `.py`, `.pyi` | Auto-installs | | R | `.r`, `.R`, `.rmd`, `.Rmd` | R runtime installed | LSP servers automatically start when you work with files that match these extensions. ## Workspace detection Co-Scientist detects the relevant language context from your active workspace and applies matching intelligence automatically. This means you can move between Nextflow, Python, and R files in the same project and get language-aware assistance without manual setup. See [Nextflow Language Server](https://github.com/nextflow-io/language-server) for advanced configuration details. ## Learn more - [Co-Scientist](./index.md): Co-Scientist overview - [Quickstart](./quickstart.md): Start using Co-Scientist - [Use cases](./use-cases.md): Seqera CLI use cases - [Credits](./credits.md): Co-Scientist credits and how to request more - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Projects Projects in Co-Scientist group the pipelines, datasets, and workflow runs that belong to a single piece of work, so you can view and chat about them without the noise of the rest of the workspace. Projects are not created inside Co-Scientist. They are derived from **workspace labels in Seqera Platform** whose names start with `project_`. Each matching label surfaces in Co-Scientist as a separate project scope, with the Platform label acting as the source of truth for membership. ## How projects are derived When you open a workspace in the Co-Scientist web interface: 1. Co-Scientist reads the list of workspace labels from the Seqera Platform API. 2. Any label whose name starts with `project_` becomes a project. 3. An **Entire workspace** view is always included alongside your projects so you can see every resource in the workspace. 4. Pipelines, datasets, and workflow runs are scoped to a project by matching on its `project_*` label. Because membership lives on the Platform label, adding or removing a resource from a project is the same action as applying or removing the label in Platform. ## Create a project 1. In **Seqera Platform**, open the workspace where the project should live. 2. Go to **Labels** in workspace settings and create a new label with the `project_` prefix. For example: - `project_rnaseq` - `project_variant_calling` - `project_chip_seq` 3. Apply the label to the pipelines and datasets that belong to the project. 4. Open Co-Scientist. The new project appears on the **Projects** page and in the chat project selector on the next page load. :::tip Create the label in workspace settings **before** applying it to resources. This ensures the label has a Platform-assigned ID, which Co-Scientist needs to auto-attach the label when you upload new datasets into the project. ::: ## Display names Co-Scientist strips the `project_` prefix to produce the display name shown in the web interface: | Platform label | Co-Scientist display name | |-----------------------|-------------------------| | `project_rnaseq` | Project rnaseq | | `project_wgs` | Project wgs | | `project_single_cell` | Project single_cell | Choose descriptive names after the prefix so projects are easy to identify. ## Where projects appear Once a `project_*` label exists in the workspace and is applied to at least one resource, the project is used in the following places: - **Projects page**: one row per project, plus the **Entire workspace** row. - **Project details page**: the pipelines, datasets, and workflow runs filtered to that project's label. - **Chat project selector**: scopes the resources the AI can see and act on during a chat session. - **Dataset upload**: when you upload a dataset from inside a project, the project's label is auto-attached. ## Edge cases ### A resource carries a `project_*` label that isn't in the workspace label list If a pipeline has a `project_*` label but the label has not been created in workspace settings, Co-Scientist still surfaces the project, inferred from the pipeline. In this case: - The project has no Platform-assigned label ID. - Dataset uploads into the project cannot auto-attach the label. To avoid this, always create `project_*` labels in workspace settings first, then apply them. ### No `project_*` labels in the workspace When a workspace has no `project_*` labels: - The **Projects** page shows a **No projects configured yet** empty state. - The project selector is hidden in the chat header. - The workspace view shows a header-only empty state. Ask a workspace admin to create the first `project_*` label to enable projects for the workspace. ## Learn more - [Seqera Platform labels](https://docs.seqera.io/platform-cloud/labels/overview): Create and manage workspace labels - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Credits](./credits.md): Co-Scientist credits and how to request more - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Quickstart This page walks you through your first Co-Scientist session: log in, start a session, switch between build mode and plan mode, debug a Platform run with a built-in skill, and set a long-running goal. :::info[**Prerequisites**]{#prerequisites} You will need the following to get started: - [Seqera CLI](./installation.mdx) - A Seqera Platform account ([sign up for free](https://cloud.seqera.io)) ::: ## Step 1: Log in to Seqera Platform Authenticate the CLI against your Seqera Platform account: ```bash seqera login ``` This will: 1. Open your default browser to the Seqera login page. 1. Prompt you to sign in with your Seqera Platform credentials. 1. Automatically capture the authentication token. 1. Display a success message in your terminal: ```console [Login] Starting Seqera CLI authentication... [Login] ✓ Authentication successful! [Login] ✓ Organization set: ``` :::tip See [Authentication](./authentication.md) for more information about how to log in and out, authenticate in automated environments, and manage your organization. ::: ## Step 2: Start an interactive session Launch an interactive Co-Scientist session: ```bash seqera ai ``` The Co-Scientist prompt appears, with a footer showing the active mode (**build** by default). See [Modes](./modes.md) for more information. ## Step 3: List commands and skills Show the built-in commands and available skills: ``` /help ``` :::tip Type `/` to open command autocomplete. ::: ## Step 4: Switch between build and plan modes Co-Scientist runs in two modes that control what it can do: - **Build mode** (default): Executes commands, edits files, and launches workflows - **Plan mode**: Read-only analysis and planning, for exploring options before making changes Press `Shift+Tab` to switch between modes. The active mode appears in the composer footer, and `/status` prints a full readout. Try plan mode with a comparison prompt: ``` Compare whether I should add FastQC or fastp as the first QC step in this RNA-seq pipeline, including the workflow changes each option would require ``` ## Step 5: Debug a Seqera Platform run Run the built-in debugging skill against your most recent workspace run: ``` /debug-last-run-on-seqera ``` Co-Scientist fetches your most recent workspace run, inspects logs and exit codes, and walks through likely causes and fixes. You need at least one workflow run in the workspace for this skill to find something to debug. ## Step 6: Set a long-running goal Give Co-Scientist a goal to work toward across multiple turns: ``` /goal update this pipeline for AWS Batch and add nf-tests ``` Co-Scientist works across model turns until the goal completes or the attempt limit is reached. See [Use cases](./use-cases.md) for more example prompts. ## Learn more - [Skills configuration](./skills.md): Discover, create, and install skills - [Modes](./modes.md): Build, plan, and goal modes in depth - [Use cases](./use-cases.md): Seqera CLI use cases - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## CLI Reference for the `seqera` commands used with Co-Scientist. To install the CLI, see [Installation](../installation.mdx). For the slash commands available inside a session, see [Skills](./skills-reference.md). ## seqera login Authenticate the CLI against your Seqera Platform account through a browser login. ```bash seqera login ``` ## seqera logout Sign out of the current session, revoke the authentication token, and remove locally stored credentials. ```bash seqera logout ``` ## seqera ai Start an interactive Co-Scientist session. Pass an optional initial query to begin with a prompt. ```bash seqera ai [query] [options] ``` | Option | Description | |--------|-------------| | `[query]` | Optional initial prompt to start the session with | | `-c` | Continue your most recent session | | `-s ` | Resume a specific session by ID | | `--approval-mode ` | Set the approval mode for local commands, for example `basic` or `full` (see [Command approval](../command-approval.md)) | | `--headless` | Run non-interactively and send output to stdout | | `--show-thinking` | Include thinking messages in headless output | | `--show-tools` | Include tool calls in headless output | | `--sub-agent` | Run as a subagent with structured JSONL output | See [Sessions](../sessions.md) for usage examples. ## seqera org Manage your organization selection for billing. | Command | Description | |---------|-------------| | `seqera org` | View your current organization | | `seqera org list` | List all organizations | | `seqera org switch` | Switch organization | | `seqera org clear` | Clear organization selection | ## seqera skill install Install Co-Scientist as a skill or instruction file for a coding agent. ```bash seqera skill install [options] ``` | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## seqera skill check Verify that an installed skill matches your current CLI version. ```bash seqera skill check [options] ``` | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## seqera --version Print the installed CLI version. ```bash seqera --version ``` ## Learn more - [Installation](../installation.mdx): Install, update, and configure the CLI - [Sessions](../sessions.md): Start, continue, resume, and exit sessions - [Coding agents](../coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./skills-reference.md): Built-in skills, slash commands, and session limits - [Environment variables](./environment-variables.md): Variables for authenticating and configuring the CLI --- ## Environment variables The Seqera CLI reads the following environment variables for authentication and for pointing development builds at a backend. | Variable | Description | | --- | --- | | SEQERA_ACCESS_TOKEN | Platform access token for non-interactive use. When set, the CLI skips the browser login flow and uses this token directly. | | SEQERA_AI_BACKEND_URL | Co-Scientist backend endpoint used by the CLI. | | SEQERA_AUTH_DOMAIN | Platform API base URL used for browser-based login. | | SEQERA_AUTH_CLI_CLIENT_ID | OAuth client ID for the Seqera CLI. | | TOWER_ACCESS_TOKEN | Platform personal access token used instead of browser login. | :::note `SEQERA_AUTH_DOMAIN` and `SEQERA_AUTH_CLI_CLIENT_ID` are only needed for the OAuth login flow when pointing a development build at the hosted Co-Scientist backend. See [Authentication](../authentication.md) for the full setup. ::: ## Learn more - [Authentication](../authentication.md): Log in, log out, and manage tokens - [Installation](../installation.mdx): Install, update, and configure the CLI - [CLI](./cli.md): Seqera CLI commands and options - [Skills](./skills-reference.md): Built-in skills, slash commands, and session limits --- ## Reference Look up Seqera CLI commands, environment variables, and the built-in skills and slash commands available in a Co-Scientist session. ## In this section - [CLI](./cli.md): Seqera CLI commands and options - [Environment variables](./environment-variables.md): Variables for authenticating and configuring the CLI - [Skills](./skills-reference.md): Built-in skills, slash commands, and session limits --- ## Skills This page lists the slash commands and built-in skills available in a Co-Scientist session. To learn how to discover, author, and install skills, see [Skills configuration](../skills.md). ## Slash commands Co-Scientist exposes two kinds of slash command in the `/` palette. TUI commands are handled locally by the CLI to control the session itself: | Command | Description | |---------|-------------| | `/help` | Show available commands | | `/exit` (`/quit`, `/q`) | Exit the application | | `/clear` | Clear conversation history | | `/thinking` | Toggle thinking display | | `/scroll` | Toggle auto-scroll | | `/org` | Show current organization | | `/lsp` | Show LSP server status | | `/status` | Show system status | | `/credits` | Show credit balance and usage | | `/approval` | Show or set approval mode | | `/feedback` | Open feedback form | | `/help-community` | Open community help | | `/stickers` | Get Seqera stickers | The second kind, AI commands, are backed by skills and sent to the AI backend. The built-in ones are listed below, and any skills your deployment exposes appear alongside them in `/` and `/help`. ## Built-in skills Your Co-Scientist deployment can expose built-in skills as slash commands. These appear in the `/` command palette and in `/help`. The CLI includes the following built-in skills by default: | Command | Description | |---------|-------------| | `/nextflow-config` | Generate and explain Nextflow configuration files | | `/nextflow-schema` | Generate `nextflow_schema.json` and sample sheet schema files | | `/debug-local-run` | Debug a local Nextflow pipeline run using `.nextflow.log`, work directories, and related artifacts | | `/debug-last-run-on-seqera` | Debug the last pipeline run on Seqera Platform | | `/convert-jupyter-notebook` | Convert Jupyter notebooks to Nextflow pipelines | | `/convert-python-script` | Convert Python scripts, including standalone scripts and Snakemake-style logic, to Nextflow | | `/convert-r-script` | Convert R scripts to Nextflow pipelines | | `/fix-strict-syntax` | Fix Nextflow strict syntax errors and help migrate pipelines to the v2 parser | | `/nf-aggregate` | Aggregate metrics from Nextflow runs on Seqera Platform using the `nf-aggregate` pipeline | | `/nf-data-lineage` | Explore Nextflow data lineage to trace which inputs and processes produced a result | | `/nf-pipeline-structure` | Analyze a local Nextflow pipeline structure, including processes, workflows, modules, and channel flow | | `/nf-run-history` | Analyze local Nextflow run history and summarize recent activity, progress, and recurring issues | | `/nf-schema-migration` | Migrate Nextflow pipelines from `nf-validation` to `nf-schema` v2 | | `/seqera-mcp` | Access Seqera Platform through MCP tools for structured, validated operations | | `/seqera-platform-api` | Query and manipulate Seqera Platform resources directly through the REST API | | `/seqerakit` | Write `seqerakit` YAML configuration for automating Seqera Platform setup | | `/simplify` | Review changed code for reuse, quality, and efficiency, then clean up issues found | :::note The exact built-in skills available in your environment may vary by deployment and release. Use `/help` or type `/` in the CLI to see the current list. ::: ## Payload limits To keep session payloads small, Co-Scientist caps discovered skill context at **5 KB**. The total session payload cap is **20 KB**. ## Learn more - [Installation](../installation.mdx): Install, update, and configure the CLI - [Quickstart](../quickstart.md): Run your first Co-Scientist session - [Authentication](../authentication.md): Log in, log out, and manage sessions - [Use cases](../use-cases.md): Seqera CLI use cases - [Using Co-Scientist](../configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](../coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Troubleshooting](../../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Sessions A session is one interactive conversation with Co-Scientist. Co-Scientist preserves your conversation history, so you can resume earlier sessions to continue your work. This page covers how to start, continue, and exit sessions, and how to run non-interactively. ## Start a session Launch an interactive session: ```bash seqera ai ``` Start with an initial query: ```bash seqera ai "list my pipelines" ``` Set the approval mode for local commands at launch: ```bash seqera ai --approval-mode full ``` See [Command approval](./command-approval.md) for the available modes. ## Continue or resume a session Continue your most recent session: ```bash seqera ai -c ``` Continue with a follow-up question: ```bash seqera ai -c "now run the pipeline with the test profile" ``` Resume a specific session by ID: ```bash seqera ai -s ``` ## Run in headless mode Run Co-Scientist in headless mode for scripting and automation. Output is sent to stdout instead of the interactive TUI. Run a query and pipe the output: ```bash seqera ai --headless "list my pipelines" ``` Include thinking messages in the output: ```bash seqera ai --headless --show-thinking "debug my pipeline" ``` Include tool calls in the output: ```bash seqera ai --headless --show-tools "list my workflows" ``` :::note Headless mode is also auto-detected when stdout is piped, for example `seqera ai "query" | grep "result"`. ::: ## Exit a session - Type `/exit`, `/quit`, or `/q` - Press `Ctrl+C` Your conversation history is preserved, so you can resume later with `seqera ai -c`. ## Learn more - [Modes](./modes.md): Work in build, plan, and goal modes - [Command approval](./command-approval.md): Control which commands run automatically - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits --- ## Antigravity/Gemini The `seqera skill` command installs a skill file that enables [Antigravity/Gemini](https://blog.google/technology/google-deepmind/gemini-model-thinking-updates-march-2025/) to use Co-Scientist as a subagent. Once installed, Antigravity can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. This page covers the Antigravity skill format, how to install the skill automatically or by hand, the invocation patterns Antigravity uses, and how to keep the skill in sync as you update the CLI. ## Antigravity/Gemini skill format Antigravity/Gemini discovers skills from the `.agents/skills/` directory at the repository root. Each skill is a folder containing a `SKILL.md` file with YAML frontmatter (name, description) and detailed instructions. | Agent | Format | |-------|--------| | [Antigravity/Gemini](https://blog.google/technology/google-deepmind/) | `.agents/skills/` | ## `seqera skill install` Use `seqera skill install` to add the Co-Scientist skill to Antigravity. Install it to the Antigravity skill directory, or pass another flag to choose a different location. If the installer can't write the skill, create it by hand with [Manual installation](#manual-installation). Install to the Antigravity skill directory: ```bash seqera skill install --path .agents/skills/seqera-ai-subagent/ ``` Install into the current repository root: ```bash seqera skill install --local ``` Or install to your home directory: ```bash seqera skill install --global ``` You can also auto-detect and update an existing installation: ```bash seqera skill install --detect ``` :::note If you encounter a `ENOENT: no such file or directory, scandir '/$bunfs/root/content/seqera'` error with `seqera skill install`, you can manually create the skill file. See [Manual installation](#manual-installation) below. ::: ### Usage ```bash seqera skill install [OPTIONS] ``` ### Options `seqera skill install` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## Manual installation If the automated installer does not support your agent platform, you can manually create the skill file: 1. Create the skill directory: ```bash mkdir -p .agents/skills/seqera-ai-subagent/ ``` 2. Create `.agents/skills/seqera-ai-subagent/SKILL.md` with the following content: ```markdown --- name: seqera-ai-subagent description: Invokes Co-Scientist as a domain-expert subagent for Nextflow pipeline development, nf-core module management, Seqera Platform workspace operations, and Wave container builds. --- # Co-Scientist Subagent When the user asks about Nextflow pipelines, nf-core modules, Seqera Platform, or Wave containers, invoke Co-Scientist: seqera ai --headless --approval-mode basic "" 2>&1 ``` 3. Verify the installation: ```bash seqera skill check ``` ## Invocation patterns Antigravity invokes Co-Scientist dynamically via shell commands rather than static context injection. The recommended patterns are: | Pattern | Command | Use case | |---------|---------|----------| | Headless query | `seqera ai --headless --approval-mode basic ""` | Read-only questions, analysis | | Sub-agent mode | `seqera ai --sub-agent --approval-mode basic ""` | Structured JSONL output | | Goal mode | `seqera ai --headless --approval-mode full "/goal "` | Multi-step autonomous work | | Module QA review | `seqera ai --headless --approval-mode basic "Review modules/nf-core//main.nf for correctness"` | Pre-push nf-core module validation | ## Validated use case: nf-core module QA Antigravity uses Co-Scientist as a domain-expert QA gate before pushing nf-core module PRs. In [PR #11377](https://github.com/nf-core/modules/pull/11377) (emmtyper), Co-Scientist caught that `emmtyper --version | sed` was fragile across Docker/conda environments due to Click version differences, and recommended using `python -c "import emmtyper; print(emmtyper.__version__)"` instead. ```bash seqera ai --headless --approval-mode basic \ "Review modules/nf-core/emmtyper/main.nf for topic channel, stub, and eval correctness" 2>&1 ``` This pattern complements `nf-core modules lint` by catching semantic issues that static linting misses. ## `seqera skill check` The skill file is tied to the version of the CLI that created it, so it can fall out of date when you upgrade. Use `seqera skill check` to confirm your installed skill still matches your current CLI version, and update it when it doesn't. Verify that your installed skill matches your current CLI version: ```bash seqera skill check ``` Update automatically if needed: ```bash seqera skill check --update ``` ### Usage ```bash seqera skill check [OPTIONS] ``` ### Options `seqera skill check` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Claude Code The `seqera skill` command installs a skill file that enables [Claude Code](https://claude.ai/code) to use Co-Scientist as a subagent. Once installed, Claude Code can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. This page covers how to install the skill into Claude Code and keep it in sync as you update the CLI. ## `seqera skill install` Use `seqera skill install` to add the Co-Scientist skill to Claude Code. Run it without options to launch an interactive installer that detects your setup and prompts for a location, or pass a flag to install directly to a specific path. Launch the interactive installer: ```bash seqera skill install ``` Install to the standard Claude Code location: ```bash seqera skill install --path .claude/skills/ ``` Install into the current repository root: ```bash seqera skill install --local ``` Or install to your home directory: ```bash seqera skill install --global ``` You can also auto-detect and update an existing installation: ```bash seqera skill install --detect ``` ### Usage ```bash seqera skill install [OPTIONS] ``` ### Options `seqera skill install` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## `seqera skill check` The skill file is tied to the version of the CLI that created it, so it can fall out of date when you upgrade. Use `seqera skill check` to confirm your installed skill still matches your current CLI version, and update it when it doesn't. Verify that your installed skill matches your current CLI version: ```bash seqera skill check ``` Update automatically if needed: ```bash seqera skill check --update ``` ### Usage ```bash seqera skill check [OPTIONS] ``` ### Options `seqera skill check` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Codex The `seqera skill` command installs a skill file that enables [Codex](https://openai.com/codex) to use Co-Scientist as a subagent. Once installed, Codex can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. This page covers how to install the skill into Codex and keep it in sync as you update the CLI. ## `seqera skill install` Use `seqera skill install` to add the Co-Scientist skill to Codex. Run it without options to launch an interactive installer that detects your setup and prompts for a location, or pass a flag to install directly to a specific path. Launch the interactive installer: ```bash seqera skill install ``` Install to your project `AGENTS.md` path: ```bash seqera skill install --path AGENTS.md ``` Install into the current repository root and let the CLI select the Codex format automatically: ```bash seqera skill install --local ``` Or install to your home directory: ```bash seqera skill install --global ``` You can also auto-detect and update an existing installation: ```bash seqera skill install --detect ``` ### Usage ```bash seqera skill install [OPTIONS] ``` ### Options `seqera skill install` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## `seqera skill check` The skill file is tied to the version of the CLI that created it, so it can fall out of date when you upgrade. Use `seqera skill check` to confirm your installed skill still matches your current CLI version, and update it when it doesn't. Verify that your installed skill matches your current CLI version: ```bash seqera skill check ``` Update automatically if needed: ```bash seqera skill check --update ``` ### Usage ```bash seqera skill check [OPTIONS] ``` ### Options `seqera skill check` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## GitHub Copilot The `seqera skill` command installs a skill file that enables [GitHub Copilot](https://github.com/features/copilot) to use Co-Scientist as a subagent. Once installed, GitHub Copilot can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. This page covers how to install the skill into GitHub Copilot and keep it in sync as you update the CLI. ## `seqera skill install` Use `seqera skill install` to add the Co-Scientist skill to GitHub Copilot. Run it without options to launch an interactive installer that detects your setup and prompts for a location, or pass a flag to install directly to a specific path. Launch the interactive installer: ```bash seqera skill install ``` Install to the standard Copilot instructions file: ```bash seqera skill install --path .github/copilot-instructions.md ``` Install into the current repository root: ```bash seqera skill install --local ``` Or install to your home directory: ```bash seqera skill install --global ``` You can also auto-detect and update an existing installation: ```bash seqera skill install --detect ``` ### Usage ```bash seqera skill install [OPTIONS] ``` ### Options `seqera skill install` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## `seqera skill check` The skill file is tied to the version of the CLI that created it, so it can fall out of date when you upgrade. Use `seqera skill check` to confirm your installed skill still matches your current CLI version, and update it when it doesn't. Verify that your installed skill matches your current CLI version: ```bash seqera skill check ``` Update automatically if needed: ```bash seqera skill check --update ``` ### Usage ```bash seqera skill check [OPTIONS] ``` ### Options `seqera skill check` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Other coding agents The `seqera skill` command installs a skill file that enables coding agents such as [Cursor](https://www.cursor.com/), [OpenCode](https://opencode.ai/), [Pi](https://github.com/badlogic/pi-mono), and [Windsurf](https://windsurf.com/) to use Co-Scientist as a subagent. Once installed, these agents can invoke Co-Scientist directly to manage workflows, build containers, query nf-core modules, and more without leaving your environment. This page covers the agents the CLI supports, how to install the skill into one of them, and how to keep it in sync as you update the CLI. ## Supported agents The CLI can install the skill into the following agents, each in the format that agent expects: | Agent | Format | |-------|--------| | [Cursor](https://www.cursor.com/) | `.cursor/rules/` | | [OpenCode](https://opencode.ai/) | `.opencode/` | | [Pi](https://github.com/badlogic/pi-mono) | `.pi/` | | [Windsurf](https://windsurf.com/) | `.windsurf/rules/` | ## `seqera skill install` Use `seqera skill install` to add the Co-Scientist skill to your coding agent. Run it without options to launch an interactive installer that detects your setup and prompts for a location, or pass a flag to install directly to a specific path. Launch the interactive installer: ```bash seqera skill install ``` Install to a specific agent path: ```bash seqera skill install --path ``` Install into the current repository root: ```bash seqera skill install --local ``` Or install to your home directory: ```bash seqera skill install --global ``` You can also auto-detect and update an existing installation: ```bash seqera skill install --detect ``` ### Usage ```bash seqera skill install [OPTIONS] ``` ### Options `seqera skill install` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--local` | `-l` | Install to repo root | | `--path ` | `-p` | Install to a custom path (relative or absolute) | | `--global` | `-g` | Install to home directory | | `--detect` | `-d` | Auto-detect an existing installation and update it | ## `seqera skill check` The skill file is tied to the version of the CLI that created it, so it can fall out of date when you upgrade. Use `seqera skill check` to confirm your installed skill still matches your current CLI version, and update it when it doesn't. Verify that your installed skill matches your current CLI version: ```bash seqera skill check ``` Update automatically if needed: ```bash seqera skill check --update ``` ### Usage ```bash seqera skill check [OPTIONS] ``` ### Options `seqera skill check` accepts the following options: | Option | Short | Description | |--------|-------|-------------| | `--update` | `-u` | Automatically update outdated skills | | `--global` | | Check only global installations | | `--local` | | Check only local (repository) installations | ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Skills configuration Skills are reusable instruction sets that extend Co-Scientist with domain-specific workflows, prompts, and operating guidance. Co-Scientist supports two skill workflows: - **Session skills**: `SKILL.md` files discovered from project and user skill directories and sent to the Co-Scientist backend as session context when you run `seqera ai` - **Agent integrations**: skill files installed by `seqera skill install` so other coding agents can invoke Co-Scientist as a subagent :::tip See [Skills](./reference/skills-reference.md) for a list of the available built-in skills and slash commands. ::: ## Use skills in the CLI When you start `seqera ai`, the CLI discovers available skills automatically. Backend-provided skills are also exposed as slash commands in the `/` command palette and `/help`. You can: - Type `/` to browse built-in commands and backend skills - Run `/help` to see commands and skill descriptions in the terminal - Add project-specific `SKILL.md` files so Co-Scientist starts each session with the right context ## Skill format Each skill lives in its own directory and includes a `SKILL.md` file with YAML frontmatter: ```text my-skill/ SKILL.md references/ ``` ```markdown --- name: my-skill description: Short description of what this skill does --- Detailed instructions, examples, and guidelines. ``` `name` and `description` are required. Skills missing either field are skipped. ## Discovery directories Co-Scientist searches these directories in order. The first directory to register a skill name takes precedence, and later skills with the same name are ignored. | Priority | Path | Scope | |----------|------|-------| | 1 | `/.agents/skills/` | project | | 2 | `/.seqera/skills/` | project | | 3 | `~/.agents/skills/` | user | | 4 | `~/.seqera/skills/` | user | | 5 | `~/.config/agents/skills/` | user | | 6 | `~/.config/seqera/skills/` | user | Project skills take priority over user skills, so you can override a global skill with a repository-specific version. ### Cross-agent compatibility `.agents/skills/` follows the [Agent Skills](https://agentskills.io) convention, which makes skills portable across coding agents. `.seqera/skills/` is Seqera-specific. ## Install skills into Co-Scientist You can add skills by creating the directory structure manually or by installing them from the [Agent Skills](https://agentskills.io) ecosystem: ```bash npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices ``` After adding a skill, restart `seqera ai` so the new skill is loaded into the session. ## Install Co-Scientist into coding agents Co-Scientist can install itself as a skill or instruction file so another coding agent can invoke it as a subagent. See [Coding agents](./coding-agents.md) for the supported agents and the `seqera skill install` and `seqera skill check` commands. ## Learn more - [Installation](./installation.mdx): Install, update, and configure the CLI - [Quickstart](./quickstart.md): Run your first Co-Scientist session - [Authentication](./authentication.md): Log in, log out, and manage sessions - [Use cases](./use-cases.md): Seqera CLI use cases - [Using Co-Scientist](./configuration.md): Configure modes, sessions, skills, command approval, and more - [Coding Agents](./coding-agents.md): Install Co-Scientist as a skill in your coding agent - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## Use cases Co-Scientist is an AI assistant for building, running, and managing bioinformatics workflows, available through the Seqera CLI. The sections below walk through common tasks with example prompts you can adapt to your own work: - [Develop and debug Nextflow pipelines](#develop-and-debug-nextflow-pipelines): Understand pipeline structure, generate config and schema files, debug runs, and convert scripts to Nextflow. - [Run pipelines on Seqera Platform](#run-pipelines-on-seqera-platform): Launch, monitor, and debug workflow runs in your workspace. - [Build containers with Wave](#build-containers-with-wave): Create containers from conda or pip packages without writing a Dockerfile. - [Work with data](#work-with-data): Browse data links, move files, and find reference datasets. - [Discover and run nf-core modules](#discover-and-run-nf-core-modules): Search over 1,000 nf-core modules and generate ready-to-run commands. - [Edit local project files](#edit-local-project-files): Make AI-assisted edits to files in your working directory. ## Develop and debug Nextflow pipelines Co-Scientist helps you develop, debug, and understand Nextflow pipelines with AI-powered analysis and code generation. The examples below are prompts you can adapt to your own pipeline. ### Understand your pipeline structure ``` > Show me the structure of main.nf ``` ``` > What processes are defined in this pipeline? ``` ``` > /nf-pipeline-structure ``` ### Generate configuration files ``` > /nextflow-config ``` ### Debug your pipeline ``` > /debug ``` ``` > Why is my pipeline failing? ``` ### Review local execution history ``` > /nf-run-history ``` Trace output provenance with data lineage: ``` > /nf-data-lineage ``` ### Generate schema files ``` > /nextflow-schema ``` ### Convert scripts to Nextflow ``` > /convert-python-script ``` ### Fix strict syntax ``` > /fix-strict-syntax ``` ### Migrate old schema definitions ``` > /nf-schema-migration ``` ## Run pipelines on Seqera Platform Use Seqera Platform capabilities to run and manage workflows at scale with AI assistance. The examples below are prompts you can adapt to your own workspace. ### List your workflows ``` > List my recent workflows ``` ### Launch a pipeline ``` > Launch the nf-core/rnaseq pipeline with the test profile ``` ### Debug failed runs ``` > Why did my last workflow fail? ``` ``` > Get the logs for the failed task in my last run ``` ### Debug your most recent run ``` > /debug-last-run-on-seqera ``` ## Build containers with Wave Co-Scientist can create containerized environments using Wave, without the need to write Dockerfiles. The examples below are prompts you can adapt to your own tools. ### Create a container with conda packages ``` > Create a container with samtools and bwa from bioconda ``` ### Create a container with pip packages ``` > Build a container with pandas, numpy, and scikit-learn ``` ### Get a container for a specific tool ``` > I need a container with FastQC version 0.12.1 ``` :::note Co-Scientist generates a Wave container URL that you can use directly in your Nextflow pipelines or pull with Docker. ::: ## Work with data Co-Scientist helps you manage data through Platform data links and access reference datasets. The examples below are prompts you can adapt to your own data. ### Browse data links ``` > List my data links ``` ``` > Show me the contents of my S3 data link ``` ### Download and upload files ``` > Generate a download URL for results/final_report.html ``` ``` > Upload my local results to the data link ``` ### Access reference data ``` > Find the human reference genome GRCh38 ``` ``` > Search for RNA-Seq test data ``` ## Discover and run nf-core modules Co-Scientist provides access to over 1,000 nf-core modules for common bioinformatics tasks. The examples below are prompts you can adapt to your own analysis. ### Search for modules ``` > Find nf-core modules for sequence alignment ``` ``` > What modules are available for variant calling? ``` ### Get module details ``` > Show me how to use the nf-core/bwa/mem module ``` ### Run a module ``` > Run FastQC on my FASTQ files ``` :::note Co-Scientist can generate the exact Nextflow command with the correct parameters for your data. ::: ## Edit local project files Co-Scientist can interact with files in your current working directory. The examples below are prompts you can adapt to your own project. ### Start from your project folder ```bash cd /path/to/your/project seqera ai ``` ### Ask for help with local tasks ``` > Show me the structure of main.nf ``` ``` > Add a new process to handle quality control ``` :::note Local file operations are controlled by [approval modes](./command-approval.md#approval-modes). By default, Co-Scientist asks for your approval before making changes outside your working directory or running potentially dangerous commands. ::: ## Learn more - [Modes](./modes.md): Work in build, plan, and goal modes - [Skills configuration](./skills.md): Discover, create, and install skills - [Skills](./reference/skills-reference.md): Built-in skills, slash commands, and session limits - [Command approval](./command-approval.md): Control which commands run automatically - [Code intelligence](./nextflow-lsp.md): Language-server support for Nextflow, Python, and R - [Projects](./projects.md): Organize workspace resources into projects using Platform labels - [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors --- ## AWS Batch :::tip This guide assumes you have an existing [Amazon Web Service (AWS)](https://aws.amazon.com/) account. The AWS Batch service quota for job queues is 50 per account. For more information on AWS Batch service quotas, see [AWS Batch service quotas](https://docs.aws.amazon.com/batch/latest/userguide/service_limits.html). ::: There are two ways to create a Seqera Platform compute environment for AWS Batch: - [**Automatically**](#automatic-configuration-of-batch-resources): this option lets Seqera automatically create the required AWS Batch resources in your AWS account, using an internal tool within Seqera Platform called "Forge". This removes the need to set up your AWS Batch infrastructure manually. Resources can also be automatically deleted when the compute environment is removed from Platform. - [**Manually**](#manual-configuration-of-batch-resources): this option lets Seqera use existing AWS Batch resources previously created. Both options require specific IAM permissions to function correctly, as well as access to an S3 bucket or EFS/FSx file system to store intermediate Nextflow files. ## S3 bucket creation AWS S3 (Simple Storage Service) is a type of **object storage**. To access input and output files using Seqera products like [Studios](../studios/overview) and [Data Explorer](../data/data-explorer) create one or more **S3 buckets**. An S3 bucket can also be used to store intermediate results of your Nextflow pipelines, as an alternative to using EFS or FSx file systems. :::note Using EFS or FSx as work directory is incompatible with Studios. ::: 1. Navigate to the [AWS S3 console](https://console.aws.amazon.com/s3/home). 1. In the top right of the page, select the same region where you plan to create your AWS Batch compute environment. 1. Select **Create bucket**. 1. Enter a unique name for your bucket. 1. Leave the rest of the options as default and select **Create bucket**. :::note S3 can be used by Nextflow for the storage of intermediate files. In production pipelines, this can amount to a lot of data. To reduce costs, consider using a retention policy when creating a bucket, such as automatically deleting intermediate files after 30 days. See the [AWS documentation](https://aws.amazon.com/premiumsupport/knowledge-center/s3-empty-bucket-lifecycle-rule/) for more information. ::: ## EFS or FSx file system creation [AWS Elastic File System (EFS)](https://aws.amazon.com/efs/) and [AWS FSx for Lustre](https://aws.amazon.com/fsx/lustre/) are types of **file storage** that can be used as a Nextflow work directory to store intermediate files, as an alternative to using S3 buckets. :::note Using EFS or FSx as work directory is incompatible with Studios. ::: To use EFS or FSx as your Nextflow work directory, create an EFS or FSx file system in the same region where you plan to create your AWS Batch compute environment. The creation of an EFS or FSx file system can be done automatically by Seqera when creating the AWS Batch compute environment, or manually by following the steps below. If you let Seqera create the file system automatically, it will also be deleted when the compute environment is removed from Platform, unless the "Dispose Resources" option is disabled in the advanced options. ### Creating an EFS file system To create a new EFS file system manually, visit the [EFS console](https://console.aws.amazon.com/efs/home). 1. Select **Create file system**. 1. Optionally give it a name, then select the VPC where your AWS Batch compute environment will be created. 1. Leave the rest of the options as default and select **Create file system**. ### Creating an FSx file system To create a new FSx for Lustre file system manually, visit the [FSx console](https://console.aws.amazon.com/fsx/home). 1. Select **Create file system**. 1. Select FSx for Lustre 1. Follow the prompts to configure the file system according to your requirements, then select **Next**. 1. Review the configuration and select **Create file system**. Make sure the [Lustre client](https://docs.aws.amazon.com/fsx/latest/LustreGuide/install-lustre-client.html) is available in the AMIs used by your AWS Batch compute environment to allow mounting FSx file systems. ## Required Platform IAM permissions To create and launch pipelines, explore buckets with Data Explorer or run Studio sessions with the AWS Batch compute environment, an IAM user with specific permissions must be provided. Some permissions are mandatory for the compute environment to be created and function correctly, while others are optional and used for example to provide list of values to pick from in the Platform UI. Permissions can be attached directly to an [IAM user](#iam-user-creation), or to an [IAM role](#iam-role-based-credential-creation) that the IAM user can assume when accessing AWS resources. A permissive and broad policy with all the required permissions is provided here for a quick start. However, we recommend following the principle of least privilege and only granting the necessary permissions for your use case, as shown in the following sections.
Full permissive policy (for reference) {AwsBatchFullPolicy}
[Download aws-batch-full-policy.json](./_policies/aws-batch-full-policy.json) ### AWS Batch management The first section of the policy allows Seqera to create, update and delete Batch compute environments ("CE"), job queues ("JQ") and jobs. If you are required to use manually created CEs and JQs or prefer to manage their lifecycle yourself, you can remove the permissions to manipulate CEs and JQs from the policy. The minimum permissions required are: - `batch:DescribeJobs` to report job status - `batch:DescribeJobDefinitions` to list existing job definitions - `batch:RegisterJobDefinition` to create new job definitions - `batch:CancelJob` to cancel jobs - `batch:SubmitJob` to submit jobs - `batch:TagResource` to tag jobs - `batch:TerminateJob` to terminate jobs You can use `batch:DescribeJobQueues` to list the existing job queues in a drop-down but it's not required if you're specifying manually created job queues. However, it is required when you let Seqera create and manage job queues automatically (using the Forge tool). In this case, the `batch:DescribeComputeEnvironments` permission must also be added. You can also restrict permissions based on resource tags. These are defined by users when they [set up a pipeline in Platform](https://docs.seqera.io/platform-enterprise/resource-labels/overview). ```json { "Sid": "BatchEnvironmentListing", "Effect": "Allow", "Action": [ "batch:DescribeJobDefinitions", "batch:DescribeJobs" ], "Resource": "*" }, { "Sid": "BatchJobsManagement", "Effect": "Allow", "Action": [ "batch:CancelJob", "batch:RegisterJobDefinition", "batch:SubmitJob", "batch:TagResource", "batch:TerminateJob" ], "Resource": [ "arn:aws:batch:::job-queue/MyCustomJQ", "arn:aws:batch:::job-definition/*", "arn:aws:batch:::job/*" ], "Condition": { "StringEqualsIfExists": { "aws:ResourceTag/MyCustomTag": "MyCustomValue" } } } ``` :::warning Restricting the `batch` actions using resource tags requires that you set the appropriate tags on each Seqera pipeline when configuring it in Platform. Forgetting to set the tag will cause the pipeline to fail to run. ::: The job definition and job name resources cannot be restricted to specific names, as Seqera creates job definitions and jobs with dynamic names. Therefore, the wildcard `*` must be used in the name of these resources. In addition, `batch:SubmitJob` requires permission on both job definitions and job queues, so make sure to include both ARNs in the `Resource` array. If you prefer to let Seqera manage Batch resources for you, you can still restrict the permissions to specific resources in your account ID and region; you can also restrict permissions based on Resource tag, as shown with the `Condition`s in the example above. :::note The quick start policy is expecting CE and JQ names automatically created by Seqera to start with the `TowerForge-` prefix, which is the default prefix used by Platform Cloud resources and can't be customized. ::: ### Launch template management Seqera requires the ability to create and manage EC2 launch templates using optimized AMIs identified via AWS Systems Manager (SSM). :::note AWS does not support restricting IAM permissions on EC2 launch templates based on specific resource names or tags. As a result, permission to operate on any resource `*` must be granted. ::: ### Pass role to Batch The `iam:PassRole` permission allows Seqera to pass [execution IAM roles](https://docs.aws.amazon.com/batch/latest/userguide/execution-IAM-role.html#create-execution-role) to AWS Batch to run Nextflow pipelines. Permissions can be restricted to only allow passing the manually created roles or the roles created by Seqera automatically with the default prefix `TowerForge-` to the AWS Batch and EC2 services, in a specific account: ```json { "Sid": "PassRolesToBatch", "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam:::role/TowerForge-*", "Condition": { "StringEquals": { "iam:PassedToService": [ "batch.amazonaws.com", "ec2.amazonaws.com" ] } } } ``` ### CloudWatch logs access Seqera requires access to CloudWatch logs to display relevant log data in the web interface. The policy can be scoped down to limit access to the [specific log group](#advanced-options) defined on the compute environment in a specific account and region: ```json { "Sid": "CloudWatchLogsAccess", "Effect": "Allow", "Action": [ "logs:Describe*", "logs:FilterLogEvents", "logs:Get*", "logs:List*", "logs:StartQuery", "logs:StopQuery", "logs:TestMetricFilter" ], "Resource": "arn:aws:logs:::log-group:/aws/batch/job/*" } ``` ### S3 access (optional) Seqera automatically attempts to fetch a list of S3 buckets available in the AWS account connected to Platform, to provide them in a drop-down to be used as Nextflow working directory, and make the compute environment creation smoother. This feature is optional, and users can type the bucket name manually when setting up a compute environment. To allow Seqera to fetch the list of buckets in the account, the `s3:ListAllMyBuckets` action can be added, and it must have the `Resource` field set to `*`, as shown in the generic policy at the beginning of this document. The `s3:ListAllMyBuckets` action also allows Data Explorer to auto-discover the data repositories accessible to your workspace credentials. Seqera offers several products to manipulate data on AWS S3 buckets, such as [Studios](../studios/overview) and [Data Explorer](../data/data-explorer); if these features are not used the related permissions can be omitted. The IAM policy can be scoped down to only allow limited read/write permissions in certain S3 buckets used by Studios/Data Explorer. For each bucket you want to browse, upload to, or download from with Data Explorer, grant `s3:GetObject` and `s3:PutObject` on the bucket objects, and `s3:ListBucket`, `s3:GetBucketLocation`, `s3:GetBucketPolicy`, and `s3:GetBucketAcl` on the bucket itself. In addition, the policy must include permission to check the region and list the content of the S3 bucket used as Nextflow work directory. We also recommend granting the `s3:GetObject` permission on the work directory path to fetch Nextflow log files. :::note If you opted to create a separate S3 bucket only for Nextflow work directories, there is no need for the IAM user to have read/write access to it. If Seqera is allowed to manage resources (using Batch Forge) the IAM roles automatically created will have the necessary permissions. If you set up the compute environment manually, you can create the required IAM roles with the necessary permissions as detailed in the [manual AWS Batch setup documentation](../enterprise/advanced-topics/manual-aws-batch-setup). ::: ```json { "Sid": "S3CheckBucketWorkDirectory", "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::example-bucket-used-as-work-directory" ] }, { "Sid": "S3ReadOnlyNextflowLogFiles", "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::example-bucket-used-as-work-directory/path/to/work/directory/*" ] }, { "Sid": "S3ReadWriteBucketsForStudiosDataExplorer", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectTagging", "s3:GetBucketLocation", "s3:GetBucketPolicy", "s3:GetBucketAcl", "s3:ListBucket", "s3:PutObject", "s3:PutObjectTagging", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::example-bucket-read-write-studios", "arn:aws:s3:::example-bucket-read-write-studios/*", "arn:aws:s3:::example-bucket-read-write-data-explorer", "arn:aws:s3:::example-bucket-read-write-data-explorer/*" ] } ``` :::note `s3:GetBucketLocation` allows Data Explorer to resolve each bucket's region. `s3:GetBucketPolicy` and `s3:GetBucketAcl` allow it to inspect each bucket's access configuration when it lists and connects to data repositories. If you prefer not to enumerate individual actions, the `s3:Get*` and `s3:List*` wildcards shown in the full permissive policy above also cover these actions. ::: ### IAM roles for AWS Batch (optional) Seqera can automatically create the IAM roles needed to interact with AWS Batch and other AWS services. You can opt out of this behavior by creating the required IAM roles manually and providing their ARNs during compute environment creation in Platform: refer to the [documentation](../enterprise/advanced-topics/manual-aws-batch-setup) for more details on how to manually set up IAM roles. To allow Seqera to create IAM roles but restrict it to your specific account and the default IAM role prefix, use the following statement: ```json { "Sid": "IAMRoleAndProfileManagement", "Effect": "Allow", "Action": [ "iam:AddRoleToInstanceProfile", "iam:AttachRolePolicy", "iam:CreateInstanceProfile", "iam:CreateRole", "iam:DeleteInstanceProfile", "iam:DeleteRole", "iam:DeleteRolePolicy", "iam:DetachRolePolicy", "iam:GetRole", "iam:ListAttachedRolePolicies", "iam:ListRolePolicies", "iam:PutRolePolicy", "iam:RemoveRoleFromInstanceProfile", "iam:TagInstanceProfile", "iam:TagRole" ], "Resource": [ "arn:aws:iam:::role/TowerForge-*" "arn:aws:iam:::instance-profile/TowerForge-*" ] } ``` :::note The quick start policy is expecting role names automatically created by Seqera to start with the `TowerForge-` prefix, which is the default prefix used by Platform Cloud resources and can't be customized. ::: ### AWS Systems Manager (optional) Seqera Platform can interact with AWS Systems Manager (SSM) to [identify ECS Optimized AMIs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/retrieve-ecs-optimized_AMI.html) for pipeline execution. This permission is optional, meaning that a [custom AMI ID](#advanced-options) can be provided at compute environment creation, removing the need for this permission. ### EC2 describe permissions (optional) Seqera can interact with EC2 to retrieve information about existing AWS resources in your account, including VPCs, subnets, and security groups. This data is used to populate drop-downs in the Platform UI when creating new compute environments. While these permissions are optional, they are recommended to enhance the user experience. Without these permissions, resource ARNs need to be manually entered in the interface by the user. :::note AWS does not support restricting IAM permissions on EC2 Describe actions based on specific resource names or tags. As a result, permission to operate on any resource `*` must be granted. ::: ### FSx file systems (optional) Seqera can manage [AWS FSx file systems](https://aws.amazon.com/fsx/), if needed by the pipelines. This section of the policy is optional and can be omitted if FSx file systems are not used by your pipelines. The describe actions cannot be restricted to specific resources, so permission to operate on any resource `*` must be granted. The management actions can be restricted to specific resources, like in the example below. ```json { "Sid": "FSxDescribe", "Effect": "Allow", "Action": [ "fsx:DescribeFileSystems" ], "Resource": "*" }, { "Sid": "FSxManagement", "Effect": "Allow", "Action": [ "fsx:CreateFileSystem", "fsx:DeleteFileSystem", "fsx:TagResource" ], "Resource": "arn:aws:fsx:::file-system/MyManualFSx" } ``` ### EFS file systems (optional) Seqera can manage [AWS EFS file systems](https://aws.amazon.com/efs/), if needed by the pipelines. This section of the policy is optional and can be omitted if EFS file systems are not used by your pipelines. The describe actions cannot be restricted to specific resources, so permission to operate on any resource `*` must be granted. The management actions can be restricted to specific resources, like in the example below. ```json { "Sid": "EFSDescribe", "Effect": "Allow", "Action": [ "elasticfilesystem:DescribeFileSystems", "elasticfilesystem:DescribeMountTargets" ], "Resource": "*" }, { "Sid": "EFSManagement", "Effect": "Allow", "Action": [ "elasticfilesystem:CreateFileSystem", "elasticfilesystem:DeleteFileSystem", "elasticfilesystem:CreateMountTarget", "elasticfilesystem:DeleteMountTarget", "elasticfilesystem:UpdateFileSystem", "elasticfilesystem:PutLifecycleConfiguration", "elasticfilesystem:TagResource" ], "Resource": "arn:aws:elasticfilesystem:::file-system/MyManualEFS" } ``` ### Pipeline secrets (optional) Seqera can synchronize [pipeline secrets](../secrets/overview) defined on the Platform workspace with AWS Secrets Manager, which requires additional permissions on the IAM user. If you do not plan to use pipeline secrets, you can omit this section of the policy. The listing of secrets cannot be restricted, but the management actions can be restricted to only allow managing secrets in a specific account and region, which must be the same region where the pipeline runs. Note that Seqera only creates secrets with the `tower-` prefix. ```json { "Sid": "PipelineSecretsListing", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" }, { "Sid": "PipelineSecretsManagementCanBeRestricted", "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:DeleteSecret", "secretsmanager:CreateSecret" ], "Resource": "arn:aws:secretsmanager:::secret:tower-*" } ``` #### Additional steps required to use secrets in a pipeline To successfully use pipeline secrets, the IAM roles manually created must follow the steps detailed in the [documentation](../secrets/overview#aws-secrets-manager-integration). ### Userdata script error detection (optional) Platform can retrieve the EC2 instance console output to detect errors in the userdata script that bootstraps the VM during instance startup. If the userdata script fails, Platform surfaces the failure as a warning on the workflow. Without this permission, userdata script failures are not detected and no warning is shown. ```json { "Sid": "OptionalUserdataCheck", "Effect": "Allow", "Action": [ "ec2:GetConsoleOutput" ], "Resource": "*" } ``` ### Data lineage (optional) If you enable [data lineage](../data/data-lineage) in your workspace, add the following permissions to your Platform integration credentials to create the queue infrastructure and bucket notifications used by the lineage service: ```json { "Sid": "LineageIntegrationSQS", "Effect": "Allow", "Action": [ "sqs:CreateQueue", "sqs:GetQueueAttributes", "sqs:SetQueueAttributes", "sqs:GetQueueUrl", "sqs:ReceiveMessage", "sqs:DeleteMessage" ], "Resource": "arn:aws:sqs:::seqera-lineage-*" }, { "Sid": "LineageIntegrationS3", "Effect": "Allow", "Action": [ "s3:CreateBucket", "s3:GetBucketNotification", "s3:PutBucketNotification", "s3:GetBucketLocation" ], "Resource": "arn:aws:s3:::seqera-lineage-*" } ``` If you manage your own EC2 instance role or head job role (rather than letting Seqera create them with Batch Forge), see [Manual AWS Batch configuration](../enterprise/advanced-topics/manual-aws-batch-setup#create-an-ec2-instance-role) for additional S3 permissions to add to those roles. ## Create the IAM policy The policy above must be created in the AWS account where the AWS Batch resources need to be created. 1. Open the [AWS IAM console](https://console.aws.amazon.com/iam) in the account where you want to create the AWS Batch resources. 1. From the left navigation menu, select **Policies** under **Access management**. 1. Select **Create policy**. 1. On the **Policy editor** section, select the **JSON** tab. 1. Following the instructions detailed in the [IAM permissions breakdown section](#required-platform-iam-permissions) replace the default text in the policy editor area under the **JSON** tab with a policy adapted to your use case, then select **Next**. 1. Enter a name and description for the policy on the **Review and create** page, then select **Create policy**. ## IAM user creation For key-based credentials only, Seqera requires an Identity and Access Management (IAM) User to create and manage AWS Batch resources in your AWS account. We recommend creating a separate IAM policy rather an IAM User inline policy, as the latter only allows 2048 characters, which may not be sufficient for all the required permissions. In certain scenarios, for example when multiple users need to access the same AWS account and provision AWS Batch resources, an IAM role with the required permissions can be created instead, and the IAM user can assume that role when accessing AWS resources, as detailed in the [IAM role creation (optional)](#iam-role-based-credential-creation) section. For Cloud deployments, Seqera Cloud is the user that will manage resources with the permissions you give it, managed through a trust policy. Depending whether you choose to let Seqera automatically create the required AWS Batch resources in your account, or prefer to set them up manually, the IAM user must have specific permissions as detailed in the [Required Platform IAM permissions](#required-platform-iam-permissions) section. Alternatively, you can create an IAM role with the required permissions and allow the IAM user to assume that role when accessing AWS resources, as detailed in the [IAM role creation (optional)](#iam-role-based-credential-creation) section. ## AWS credential options AWS credentials can be configured in two ways: - **Key-based credentials**: Access key and secret key with direct IAM permissions. If you provide a role ARN in **Assume role**, the **Generate External ID** switch is displayed and External ID generation is optional. - **Role-based credentials (recommended)**: Use role assumption only (no static keys). Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. External ID is generated automatically when you save. Use the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. This field is available for both key-based and role-based credentials. It is optional for key-based credentials and required for role-based credentials. Existing credentials created before March 2026 continue to work without changes. ### Create an IAM user (key-based) 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Users** in the left navigation menu, then select **Create User** at the top right of the page. 1. Enter a name for your user (e.g., _seqera_) and select **Next**. 1. Under **Permission options**, select **Attach policies directly**, then search for and select the policy created above, and select **Next**. * Optionally, if you want to use an ARN and External ID with key based access, add the following to the user's Permission policy. This will allow the IAM User to assume a role in order to manage batch resources ```json { "Sid": "AssumeRoleToManageBatchResources", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam:::role/", "Condition": { "StringEquals": { "sts:ExternalId": "" } } } ``` 1. On the last page, review the user details and select **Create user**. The user has now been created. The most up-to-date instructions for creating an IAM user can be found in the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). ### Obtain IAM user credentials (key-based) To get the credentials needed to connect Seqera to your AWS account, follow these steps: 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Users** in the left navigation menu, then select the newly created user from the users table. 1. Select the **Security credentials** tab, then select **Create access key** under the **Access keys** section. 1. In the **Use case** dialog that appears, select **Command line interface (CLI)**, then tick the confirmation checkbox at the bottom to acknowledge that you want to proceed creating an access key, and select **Next**. 1. Optionally provide a description for the access key, like the reason for creating it, then select **Create access key**. 1. Save the **Access key** and **Secret access key** in a secure location as you will need to provide them when creating credentials in Seqera. ## IAM role-based credential creation Rather than attaching permissions directly to the IAM user, you can create an IAM role with the required permissions and allow the Seqera Cloud to assume that role when accessing AWS resources. This is useful when multiple third parties access the same AWS account: this way the actual permissions to operate on the resources are only granted to a single centralized role. 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Roles** in the left navigation menu, then select **Create role** at the top right of the page. 1. Select **Custom trust policy** as the trusted entity type in the AWS Console. Allow the Seqera Cloud access role `arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole` in your trust policy as shown below, then select **Next**. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole" }, "Action": "sts:TagSession" } ] } ``` 1. On the **Permissions** page, search for and select the policy created in the [Create the IAM policy](#create-the-iam-policy) section, then select **Next**. 1. Give the role a name and optionally a description, review the details of the role, optionally provide tags to help you identify the role, then select **Create role**. :::note The External ID is generated by Seqera when you save your credentials. Complete the following steps to finalize the trust policy: 1. In Seqera, create new AWS credentials, select Role mode, paste the role ARN, and save. Seqera generates and displays a unique External ID. 2. Return to the IAM role's trust policy in AWS and replace the `` placeholder with the generated value. ::: ## Automatic configuration of Batch resources Seqera automates the configuration of an [AWS Batch](https://aws.amazon.com/batch/) compute environment and the queues required for deploying Nextflow pipelines. :::caution AWS Batch creates resources that you may be charged for in your AWS account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: ### AWS Batch Seqera automates the configuration of an [AWS Batch](https://aws.amazon.com/batch/) compute environment and the queues required to deploy Nextflow pipelines. After your IAM User or Role and S3 bucket have been set up, create a new **AWS Batch** compute environment in Seqera. #### Create a Seqera AWS Batch compute environment Seqera will create the head and compute [job queues](https://docs.aws.amazon.com/batch/latest/userguide/job_queues.html) and their respective [compute environments](https://docs.aws.amazon.com/batch/latest/userguide/compute_environments.html) where jobs will be executed. The job queues are configured with [job state limit actions](https://docs.aws.amazon.com/batch/latest/APIReference/API_JobStateTimeLimitAction.html) to automatically purge jobs that cannot be scheduled on any node type available for the compute environment. Depending on the provided configuration in the UI, Seqera might also create IAM roles for Nextflow head job execution, CloudWatch log groups, EFS or FSx filesystems, etc. 1. Select **Compute environments** from the navigation menu of the Seqera Workspace where you want to setup the CE. 1. Select **Add compute environment**. 1. Enter a descriptive name for this environment, e.g., _AWS Batch Spot (eu-west-1)_. 1. Select **AWS Batch** as the target platform. 1. From the **Credentials** drop-down, select existing AWS credentials, or select **+** to add new credentials. If you're using existing credentials, skip to step 9. :::note You can create multiple credentials in your Seqera environment. See [Credentials](../credentials/overview). ::: 1. Enter a name, e.g., _AWS Credentials_. 1. Under **AWS credential mode**, select **Keys** or **Role**. 1. For **Keys** mode: - Add the **Access key** and **Secret key** you [previously obtained](#obtain-iam-user-credentials-key-based). - Optionally paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - If you paste a role ARN in **Assume role**, the **Generate External ID** switch is displayed. Generating an External ID is optional in **Keys** mode. - If **Generate External ID** is selected, an External ID is automatically generated and shown after you save the credential. 1. For **Role** mode: - Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - External ID is generated automatically when you save the credential. :::note When using AWS keys without an assumed role, the associated AWS user must have been granted permissions to operate on the cloud resources directly. When an assumed role is provided, the IAM user keys are only used to retrieve temporary credentials impersonating the role specified: this could be useful when e.g. multiple IAM users are used to access the same AWS account, and the actual permissions to operate on the resources are only granted to the role. ::: 1. Select a **Region**, e.g., _eu-west-1 - Europe (Ireland)_. This region must match the location of the S3 bucket or EFS/FSx file system you plan to use as work directory. 1. In the **Pipeline work directory** field type or select from the drop-down the S3 bucket [previously created](#s3-bucket-creation), e.g., `s3://seqera-bucket`. The work directory can be customized to specify a folder inside the bucket where Nextflow intermediate files will be stored, e.g., `s3://seqera-bucket/nextflow-workdir`. The bucket must be located in the same region chosen in the previous step. :::note When you specify an S3 bucket as your work directory, this bucket is used for the Nextflow [cloud cache](https://docs.seqera.io/nextflow/cache-and-resume#cache-stores) by default. Seqera adds a `cloudcache` block to the Nextflow configuration file for all runs executed with this compute environment. This block includes the path to a `cloudcache` folder in your work directory, e.g., `s3://seqera-bucket/cloudcache/.cache`. You can specify an alternative cache location with the **Nextflow config file** field on the pipeline [launch](../launch/launchpad#launch-pipelines) form. ::: Similarly you can specify a path in an EFS or FSx file system as your work directory. When using EFS or FSx, you'll need to scroll down to "EFS file system" or "FSx for Lustre" sections to specify either an existing file system ID or let Seqera create a new one for you automatically. Read the notes in steps 23 and 24 below on how to setup EFS or FSx. :::warning Using an EFS or FSx file system as your work directory is currently incompatible with [Studios](../studios/overview), and will result in errors with checkpoints and mounted data. Use an S3 bucket as your work directory when using Studios. ::: 1. Select **Enable Wave containers** to facilitate access to private container repositories and provision containers in your pipelines using the Wave containers service. See [Wave containers](https://docs.seqera.io/nextflow/wave) for more information. 1. Select **Enable Fusion v2** to allow access to your S3-hosted data via the [Fusion v2](https://docs.seqera.io/fusion) virtual distributed file system. This speeds up most data operations. The Fusion v2 file system requires Wave containers to be enabled. See [Fusion file system](../supported_software/fusion/overview) for configuration details.
Use Fusion v2 file system :::note The compute recommendations below are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. ::: We recommend using Fusion with AWS NVMe instances (fast instance storage) as this delivers the fastest performance when compared to environments using only AWS EBS (Elastic Block Store). 1. Use Seqera Platform version 23.1 or later. 1. Use an S3 bucket as the pipeline work directory. 1. Enable **Wave containers**, **Fusion v2**, and **fast instance storage**. 1. Select the **Batch Forge** config mode. 1. Fast instance storage requires an EC2 instance type that uses NVMe disks. Specify NVMe-based instance types in **Instance types** under **Advanced options**. If left unspecified, Platform selects instances from AWS NVMe-based instance type families. See [Instance store temporary block storage for EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html) for more information. :::note When enabling fast instance storage, do not select the `optimal` instance type families (c4, m4, r4) for your compute environment as these are not NVMe-based instances. Specify AWS NVMe-based instance types, or leave the **Instance types** field empty for Platform to select NVMe instances for you. ::: :::tip We recommend selecting 8xlarge or above for large and long-lived production pipelines: - A local temp storage disk of at least 200 GB and a random read speed of 1000 MBps or more. To work with files larger than 100 GB, increase temp storage accordingly (400 GB or more). - Dedicated networking ensures a guaranteed network speed service level compared with "burstable" instances. See [Instance network bandwidth](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-network-bandwidth.html) for more information. ::: When using Fusion v2 without fast instance storage, the following EBS settings are applied to optimize file system performance: - EBS boot disk size is increased to 100 GB - EBS boot disk type GP3 is selected - EBS boot disk throughput is increased to 325 MB/s Extensive benchmarking of Fusion v2 has demonstrated that the increased cost associated with these settings are generally outweighed by the costs saved due to decreased run time.
1. Select **Enable Fusion Snapshots (beta)** to enable Fusion to automatically restore jobs that are interrupted when an AWS Spot instance reclamation occurs. Requires Fusion v2. See [Fusion Snapshots](https://docs.seqera.io/fusion/guide/snapshots) for more information. 1. Set the **Config mode** to **Batch Forge** to allow Seqera Platform to manage AWS Batch compute environments using the Forge tool. 1. Select a **Provisioning model**. To minimize compute costs select **Spot**. You can specify an allocation strategy and instance types under [**Advanced options**](#advanced-options). If advanced options are omitted, Seqera Platform 23.2 and later versions default to `BEST_FIT_PROGRESSIVE` for On-Demand and `SPOT_PRICE_CAPACITY_OPTIMIZED` for Spot compute environments. :::note You can create a compute environment that launches either Spot or On-Demand instances. Spot instances can cost as little as 20% of On-Demand instances, and with Nextflow's ability to automatically relaunch failed tasks, Spot is almost always the recommended provisioning model. Note, however, that when choosing Spot instances, Seqera will also create a dedicated queue for running the main Nextflow job using a single On-Demand instance to prevent any execution interruptions. From Nextflow version 24.10, the default Spot reclamation retry setting changed to `0` on AWS and Google. By default, no internal retries are attempted on these platforms. Spot reclamations now lead to an immediate failure, exposed to Nextflow in the same way as other generic failures (returning for example, `exit code 1` on AWS). Nextflow will treat these failures like any other job failure unless you actively configure a retry strategy. For more information, see [Spot instance failures and retries](../troubleshooting_and_faqs/nextflow#spot-instance-failures-and-retries). ::: 1. Enter the **Max CPUs**, e.g., `64`. This is the maximum number of combined CPUs (the sum of all instances' CPUs) AWS Batch will provision at any time. 1. Select **EBS Auto scale (deprecated)** to allow the EC2 virtual machines to dynamically expand the amount of available disk space during task execution. This feature is deprecated, and is not compatible with Fusion v2. :::note When you run large AWS Batch clusters (hundreds of compute nodes or more), EC2 API rate limits may cause the deletion of unattached EBS volumes to fail. You should delete volumes that remain active after Nextflow jobs have completed to avoid additional costs. Monitor your AWS account for any orphaned EBS volumes via the EC2 console, or with a Lambda function. See [here](https://aws.amazon.com/blogs/mt/controlling-your-aws-costs-by-deleting-unused-amazon-ebs-volumes/) for more information. ::: 1. With the optional **Enable Fusion mounts (deprecated)** feature enabled, S3 buckets specified in **Pipeline work directory** and **Allowed S3 Buckets** are mounted as file system volumes in the EC2 instances carrying out the Batch job execution. These buckets can then be accessed at `/fusion/s3/`. For example, if the bucket name is `s3://imputation-gp2`, your pipeline will access it using the file system path `/fusion/s3/imputation-gp2`. **Note:** This feature has been deprecated. Consider using Fusion v2 (see above) for enhanced performance and stability. :::note You do not need to modify your pipeline or files to take advantage of this feature. Nextflow will automatically recognize and replace any reference to files prefixed with `s3://` with the corresponding Fusion mount paths. ::: 1. Select **Enable Fargate for head job** to run the Nextflow head job with the [AWS Fargate](https://aws.amazon.com/fargate/) container service and speed up pipeline launch. Fargate is a serverless compute engine that enables users to run containers without the need to provision servers or clusters in advance. AWS takes a few minutes to spin up an EC2 instance, whereas jobs can be launched with Fargate in under a minute (depending on container size). We recommend Fargate for most pipeline deployments, but EC2 is more suitable for environments that use GPU instances, custom AMIs, or that require more than 16 vCPUs. If you specify a custom AMI ID in the [Advanced options](#advanced-options) below, this will not be applied to the Fargate-enabled head job. See [here](https://docs.aws.amazon.com/batch/latest/userguide/fargate.html#when-to-use-fargate) for more information on Fargate's limitations. :::note Fargate requires the Fusion v2 file system and a **Spot** provisioning model. Fargate is not compatible with EFS and FSx file systems. ::: 1. Select **Enable GPUs** if you intend to run GPU-dependent workflows in the compute environment. See [GPU usage](./overview#aws-batch) for more information. :::note Seqera only supports NVIDIA GPUs. Select instances with NVIDIA GPUs for your GPU-dependent processes. ::: 1. Select **Use Graviton CPU architecture** to execute on Graviton-based EC2 instances (i.e., ARM64 CPU architecture). When enabled, `m6g`, `r6g`, and `c6g` instance types are used by default for compute jobs, but 3rd-generation Graviton [instances](https://www.amazonaws.cn/en/ec2/graviton/) are also supported. You can specify your own **Instance types** under [**Advanced options**](#advanced-options). :::note Graviton requires Fargate, Wave containers, and Fusion v2 file system to be enabled. This feature is not compatible with GPU-based architecture. ::: 1. Enter any additional **Allowed S3 buckets** that your workflows require to read input data or write output data. The **Pipeline work directory** bucket above is added by default to the list of **Allowed S3 buckets**. 1. To use an **EFS** file system in your pipeline, you can either select **Use existing EFS file system** and specify an existing EFS instance, or select **Create new EFS file system** to create one. To use the EFS file system as the work directory of the compute environment specify `/work` in the **Pipeline work directory** field (step 10 of this guide). - To use an existing EFS file system, enter the **EFS file system id** and **EFS mount path**. This is the path where the EFS volume is accessible to the compute environment. For simplicity, we recommend that you use `/mnt/efs` as the EFS mount path. - To create a new EFS file system, enter the **EFS mount path**. We advise that you specify `/mnt/efs` as the EFS mount path. - EFS file systems created by Batch Forge are automatically tagged in AWS with `Name=TowerForge-`, with `` being the compute environment ID. Any manually-added resource label with the key `Name` (capital N) will override the automatically-assigned `TowerForge-` label. - A custom EC2 security group needs to be configured to allow the compute environment to access the EFS file system. * Visit the [AWS Console for Security groups](https://console.aws.amazon.com/ec2/home?#SecurityGroups) and switch to the region where your workload will run. * Select **Create security group**. * Enter a relevant name like `seqera-efs-access-sg` and description, e.g., _EFS access for Seqera Batch compute environment_. * Empty both **Inbound rules** and **Outbound rules** sections by deleting default rules. * Optionally add **Tags** to the security group, then select **Create security group**. * After creating the security group, select it from the security groups list, then select the **Inbound rules** tab and select **Edit inbound rules**. * Select **Add rule** and configure the new rule as follows: - **Type**: `NFS` - **Source**: `Custom` and enter the security group ID that you're editing (you can search for it by name, e.g., `seqera-efs-access-sg`). This allows resources associated with the same security group to communicate with each other. * Select **Save rules** to finalize the inbound rule configuration. * Repeat the same steps to add an outbound rule to allow all outbound traffic: set type `All traffic` and destination `Anywhere-IPv4`/`Anywhere-IPv6`. * See the [AWS documentation about EFS security groups](https://docs.aws.amazon.com/efs/latest/ug/network-access.html) for more information. * The Security group then needs to be defined in the **Advanced options** below to allow the compute environment to access the EFS file system. :::warning EFS file systems cannot be used as work directory for [Studios](../studios/overview), but can be mounted and used by applications running in Studios. ::: 1. To use a **FSx for Lustre** file system in your pipeline, you can either select **Use existing FSx file system** and specify an existing FSx instance, or select **Create new FSx file system** to create one. To use the FSx file system as your work directory, specify `/work` in the **Pipeline work directory** field (step 10 of this guide). - To use an existing FSx file system, enter the **FSx DNS name** and **FSx mount path**. The FSx mount path is the path where the FSx volume is accessible to the compute environment. For simplicity, we recommend that you use `/mnt/fsx` as the FSx mount path. - To create a new FSx file system, enter the **FSx size** (in GB) and the **FSx mount path**. We advise that you specify `/mnt/fsx` as the FSx mount path. - FSx file systems created by Batch Forge are automatically tagged in AWS with `Name=TowerForge-`, with `` being the compute environment ID. Any manually-added resource label with the key `Name` (capital N) will override the automatically-assigned `TowerForge-` label. - A custom EC2 security group needs to be configured to allow the compute environment to access the FSx file system. * Visit the [AWS Console for Security groups](https://console.aws.amazon.com/ec2/home?#SecurityGroups) and switch to the region where your workload will run. * Select **Create security group**. * Enter a relevant name like `seqera-fsx-access-sg` and description, e.g., _FSx access for Seqera Batch compute environment_. * Empty both **Inbound rules** and **Outbound rules** sections by deleting default rules. * Optionally add **Tags** to the security group, then select **Create security group**. * After creating the security group, select it from the security groups list, then select the **Inbound rules** tab and select **Edit inbound rules**. * Select **Add rule** and configure the new rule as follows: - **Type**: `Custom TCP` - **Port range**: `988` - **Source**: `Custom` and enter the security group ID that you're editing (you can search for it by name, e.g., `seqera-fsx-access-sg`). This allows resources associated with the same security group to communicate with each other. * Repeat the step to add another rule with: - **Type**: `Custom TCP` - **Port range**: `1018-1023` - **Source**: `Custom`, same as above. * Select **Save rules** to finalize the inbound rule configuration. * Repeat the same steps to add an outbound rule to allow all outbound traffic: set type `All traffic` and destination `Anywhere-IPv4`/`Anywhere-IPv6`. * See the [AWS documentation about FSx security groups](https://docs.aws.amazon.com/fsx/latest/LustreGuide/limit-access-security-groups.html) for more information. * The Security group then needs to be defined in the **Advanced options** below to allow the compute environment to access the FSx file system. - You may need to install the `lustre` client in the AMI used by your compute environment to access FSx file systems. See [Installing the Lustre client](https://docs.aws.amazon.com/fsx/latest/LustreGuide/install-lustre-client.html) for more information. :::warning FSx file systems cannot be used as work directory for [Studios](../studios/overview), but can be mounted and used by applications running in Studios. ::: 1. Select **Dispose resources** to automatically delete all AWS resources created by Seqera Platform when you delete the compute environment, including EFS/FSx file systems. 1. Apply [**Resource labels**](../resource-labels/overview) to the cloud resources produced by this compute environment. Workspace default resource labels are prefilled. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options described in the next section, as needed. 1. Select **Create** to finalize the compute environment setup. It will take a few seconds for all the AWS resources to be created before you are ready to launch pipelines. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your AWS Batch compute environment. ::: ### Advanced options Seqera Platform compute environments for AWS Batch include advanced options to configure instance types, resource allocation, custom networking, and CloudWatch and ECS agent integration. #### Seqera AWS Batch advanced options - Specify the **Allocation strategy** and indicate any preferred **Instance types**. AWS applies quotas for the number of running and requested [Spot](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-limits.html) and [On-Demand](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-on-demand-instances.html#ec2-on-demand-instances-limits) instances per account. AWS will allocate instances from up to 20 instance types, based on those requested for the compute environment. AWS excludes the largest instances when you request more than 20 instance types. :::note If these advanced options are omitted, allocation strategy defaults are `BEST_FIT_PROGRESSIVE` for On-Demand and `SPOT_PRICE_CAPACITY_OPTIMIZED` for Spot compute environments. ::: :::caution Platform CLI (known as `tw`) v0.8 and earlier do not support the `SPOT_PRICE_CAPACITY_OPTIMIZED` allocation strategy in AWS Batch. You cannot currently use CLI to create or otherwise interact with AWS Batch Spot compute environments that use this allocation strategy. ::: - Configure a custom networking setup using the **VPC ID**, **Subnets**, and **Security groups** fields. * If not defined, the default VPC, subnets, and security groups for the selected region will be used. * When using EFS or FSx file systems, select the security group previously created to allow access to the file system. The VPC ID the security group belongs to needs to match the VPC ID defined for the Seqera Batch compute environment. - You can specify a custom **AMI ID**. :::note From version 24.2, Seqera supports Amazon Linux 2023 ECS-optimized AMIs, in addition to previously supported Amazon Linux-2 AMIs. AWS-recommended Amazon Linux 2023 AMI names start with `al2023-`. To learn more about approved versions of the Amazon ECS-optimized AMIs or creating a custom AMI, see [this AWS guide](https://docs.aws.amazon.com/batch/latest/userguide/compute_resource_AMIs.html#batch-ami-spec). If a custom AMI is specified and the **Enable GPU** option is also selected, the custom AMI will be used instead of the AWS-recommended GPU-optimized AMI. ::: - If you need to debug the EC2 instance provisioned by AWS Batch, specify a **Key pair** to log in to the instance via SSH. - You can set **Min CPUs** to be greater than `0`, in which case some EC2 instances will remain active. An advantage of this is that pipeline executions will initialize faster. :::note Setting Min CPUs to a value greater than 0 will keep the required compute instances active, even when your pipelines are not running. This will result in additional AWS charges. ::: - Use **Head job CPUs** and **Head job memory** to specify the hardware resources allocated for the Nextflow head job. The default head job memory allocation is 4096 MiB. :::warning Setting head job values will also limit the size of any Studio session that can be created in the compute environment. ::: - Use **Head job role** and **Compute job role** to grant fine-grained IAM permissions to the **Head job** and **Compute jobs**. - Add an execution role ARN to the **Batch execution role** field to grant permissions to make API calls on your behalf to the ECS container used by Batch. This is required if the pipeline launched with this compute environment needs access to the secrets stored in this workspace. This field can be ignored if you are not using secrets. - Specify an EBS block size (in GB) in the **EBS auto-expandable block size** field to control the initial size of the EBS auto-expandable volume. New blocks of this size are added when the volume begins to run out of free space. This feature is deprecated, and is not compatible with Fusion v2. - Enter the **Boot disk size** (in GB) to specify the size of the boot disk in the VMs created by this compute environment. - If you're using **Spot** instances, you can also specify the **Cost percentage**, which is the maximum allowed price of a **Spot** instance as a percentage of the **On-Demand** price for that instance type. Spot instances will not be launched until the current Spot price is below the specified cost percentage. - Use **AWS CLI tool path** to specify the location of the `aws` CLI. - Specify a **CloudWatch Log group** for the `awslogs` driver to stream the logs entry to an existing Log group in Cloudwatch. - Specify a custom **ECS agent configuration** for the ECS agent parameters used by AWS Batch. This is appended to the `/etc/ecs/ecs.config` file in each cluster node. :::note Altering this file may result in a malfunctioning Batch Forge compute environment. See [Amazon ECS container agent configuration](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html) to learn more about the available parameters. ::: ## Manual configuration of Batch resources This section is for users with a pre-configured AWS environment: follow the [AWS Batch queue and compute environment creation instructions](../enterprise/advanced-topics/manual-aws-batch-setup.mdx) to set up the required AWS Batch resources in your account. A [S3 bucket](#s3-bucket-creation) or EFS/FSx file system is required to store Nextflow intermediate files when using Seqera with AWS Batch. Refer to the [IAM user creation](#iam-user-creation) section to ensure that your IAM user has the necessary permissions to run pipelines in Seqera Platform. Remove any permissions that are not required for your use case. ### Seqera manual compute environment With your AWS environment and resources set up and your user permissions configured, create an AWS Batch compute environment in Seqera. :::caution AWS Batch creates resources that you may be charged for in your AWS account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: 1. Select **Compute environments** from the navigation menu of the Seqera Workspace where you want to setup the CE. 1. Select **Add compute environment**. 1. Enter a descriptive name for this environment, e.g., _AWS Batch Spot (eu-west-1)_. 1. Select **AWS Batch** as the target platform. 1. From the **Credentials** drop-down, select existing AWS credentials, or select **+** to add new credentials. If you're using existing credentials, skip to step 9. :::note You can create multiple credentials in your Seqera environment. See [Credentials](../credentials/overview). ::: 1. Enter a name, e.g., _AWS Credentials_. 1. Under **AWS credential mode**, select **Keys** or **Role**. 1. For **Keys** mode: - Add the **Access key** and **Secret key** you [previously obtained](#obtain-iam-user-credentials-key-based). - Optionally paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - If you paste a role ARN in **Assume role**, the **Generate External ID** switch is displayed. Generating an External ID is optional in **Keys** mode. - If **Generate External ID** is selected, an External ID is automatically generated and shown after you save the credential. 1. For **Role** mode: - Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - External ID is generated automatically when you save the credential. :::note When using AWS keys without an assumed role, the associated AWS user must have been granted permissions to operate on the cloud resources directly. When an assumed role is provided, the IAM user keys are only used to retrieve temporary credentials impersonating the role specified: this could be useful when e.g. multiple IAM users are used to access the same AWS account, and the actual permissions to operate on the resources are only granted to the role. ::: 1. Select a **Region**, e.g., _eu-west-1 - Europe (Ireland)_. This region must match the region where your S3 bucket or EFS/FSx work directory is located to avoid high data transfer costs. 1. Enter or select from the drop-down the S3 bucket [previously created](#s3-bucket-creation) in the **Pipeline work directory** field, e.g., `s3://seqera-bucket`. This bucket must be in the same region chosen in the previous step to avoid incurring high data transfer costs. The work directory can be customized to specify a folder inside the bucket, e.g., `s3://seqera-bucket/nextflow-workdir`. :::note When you specify an S3 bucket as your work directory, this bucket is used for the Nextflow [cloud cache](https://docs.seqera.io/nextflow/cache-and-resume#cache-stores) by default. Seqera adds a `cloudcache` block to the Nextflow configuration file for all runs executed with this compute environment. This block includes the path to a `cloudcache` folder in your work directory, e.g., `s3://seqera-bucket/cloudcache/.cache`. You can specify an alternative cache location with the **Nextflow config file** field on the pipeline [launch](../launch/launchpad#launch-pipelines) form. ::: Similarly you can specify a path in an EFS or FSx file system as your work directory. When using EFS or FSx, you'll need to scroll down to "EFS file system" or "FSx for Lustre" sections to specify either an existing file system ID or let Seqera create a new one for you automatically. Read the notes in steps 23 and 24 below on how to setup EFS or FSx. :::warning Using an EFS or FSx file system as your work directory is currently incompatible with [Studios](../studios/overview), and will result in errors with checkpoints and mounted data. Use an S3 bucket as your work directory when using Studios. ::: 1. Select **Enable Wave containers** to facilitate access to private container repositories and provision containers in your pipelines using the Wave containers service. See [Wave containers](https://docs.seqera.io/nextflow/wave) for more information. 1. Select **Enable Fusion v2** to allow access to your S3-hosted data via the [Fusion v2](https://docs.seqera.io/fusion) virtual distributed file system. This speeds up most data operations. The Fusion v2 file system requires Wave containers to be enabled. See [Fusion file system](../supported_software/fusion/overview) for configuration details.
Use Fusion v2 file system :::note The compute recommendations below are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. ::: We recommend using Fusion with AWS NVMe instances (fast instance storage) as this delivers the fastest performance when compared to environments using only AWS EBS (Elastic Block Store). 1. Use Seqera Platform version 23.1 or later. 1. Use an S3 bucket as the pipeline work directory. 1. Enable **Wave containers**, **Fusion v2**, and **fast instance storage**. 1. Select the **Batch Forge** config mode. 1. Fast instance storage requires an EC2 instance type that uses NVMe disks. Specify NVMe-based instance types in **Instance types** under **Advanced options**. If left unspecified, Platform selects instances from AWS NVMe-based instance type families. See [Instance store temporary block storage for EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html) for more information. :::note When enabling fast instance storage, do not select the `optimal` instance type families (c4, m4, r4) for your compute environment as these are not NVMe-based instances. Specify AWS NVMe-based instance types, or leave the **Instance types** field empty for Platform to select NVMe instances for you. ::: :::tip We recommend selecting 8xlarge or above for large and long-lived production pipelines: - A local temp storage disk of at least 200 GB and a random read speed of 1000 MBps or more. To work with files larger than 100 GB, increase temp storage accordingly (400 GB or more). - Dedicated networking ensures a guaranteed network speed service level compared with "burstable" instances. See [Instance network bandwidth](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-network-bandwidth.html) for more information. ::: When using Fusion v2 without fast instance storage, the following EBS settings are applied to optimize file system performance: - EBS boot disk size is increased to 100 GB - EBS boot disk type GP3 is selected - EBS boot disk throughput is increased to 325 MB/s Extensive benchmarking of Fusion v2 has demonstrated that the increased cost associated with these settings are generally outweighed by the costs saved due to decreased run time.
1. Select **Enable Fusion Snapshots (beta)** to enable Fusion to automatically restore jobs that are interrupted when an AWS Spot instance reclamation occurs. Requires Fusion v2. See [Fusion Snapshots](https://docs.seqera.io/fusion/guide/snapshots) for more information. 1. Set the **Config mode** to **Manual**. 1. Enter the **Head queue** created following the [instructions](../enterprise/advanced-topics/manual-aws-batch-setup.mdx), which is the name of the AWS Batch queue that the Nextflow main job will run. 1. Enter the **Compute queue**, which is the name of the AWS Batch queue where tasks will be submitted. 1. Apply [**Resource labels**](../resource-labels/overview) to the cloud resources produced by this compute environment. Workspace default resource labels are prefilled. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options described in the next section, as needed. 1. Select **Create** to finalize the compute environment setup. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your AWS Batch compute environment. ::: ### Advanced options Seqera compute environments for AWS Batch include advanced options to configure resource allocation, execution roles, custom AWS CLI tool paths, and CloudWatch integration. - Configure a custom networking setup using the **VPC ID**, **Subnets**, and **Security groups** fields. * If not defined, the default VPC, subnets, and security groups for the selected region will be used. * When using EFS or FSx file systems, select the security group previously created to allow access to the file system. The VPC ID the security group belongs to needs to match the VPC ID defined for the Seqera Batch compute environment. - Use **Head job CPUs** and **Head job memory** to specify the hardware resources allocated for the Nextflow head job. The default head job memory allocation is 4096 MiB. - Use **Head job role** and **Compute job role** to grant fine-grained IAM permissions to the head job and compute jobs, - Add an execution role ARN to the **Batch execution role** field to grant permissions to make API calls on your behalf to the ECS container used by Batch. This is required if the pipeline launched with this compute environment needs access to the secrets stored in this workspace. This field can be ignored if you are not using secrets. - Use **AWS CLI tool path** to specify the location of the `aws` CLI. - Specify a **CloudWatch Log group** for the `awslogs` driver to stream the logs entry to an existing Log group in Cloudwatch. :::caution Seqera is designed to terminate compute resources when a Nextflow pipeline completes or is canceled. However, due to external factors — including user-defined workflow logic, transient cloud faults, or abnormal pipeline exits — residual resources may persist. While Seqera provides visibility to detect and resolve these states, customers are responsible for final resource cleanup and ensuring compute environments operate according to Platform expectations. From Nextflow v24.10+, compute jobs are identifiable by Seqera workflow ID. If you search your AWS console/CLI/API for jobs prefixed by a given workflow ID, you can check the status and perform additional cleanup in edge case scenarios. ::: --- ## AWS Cloud Many of the current implementations of compute environments for cloud providers rely on the use of batch services such as AWS Batch, Azure Batch, and Google Batch for the execution and management of submitted jobs, including pipelines and Studio session environments. Batch services are suitable for large-scale workloads, but they add management complexity. In practical terms, the currently used batch services result in some limitations: - **Long launch delay**: When you launch a pipeline or Studio in a batch compute environment, there's a delay of several minutes before the pipeline or Studio session environment is in a running state. This is caused by the batch services that need to provision the associated compute service to run a single job. - **Complex setup**: Standard batch services require complex identity management policies and configuration of multiple services including compute environments, job queues, job definitions, etc. - **Allocation constraints**: AWS Batch and other cloud batch services have strict resource quotas. For example, a hard limit of 50 job queues per AWS account per region. This means that no new compute environment can be created when this quota limit is reached. The AWS Cloud compute environment addresses these pain points with: - **Faster startup time**: Nextflow pipelines reach a `Running` status and Studio sessions connect in under a minute (a 4x improvement compared to classic AWS Batch compute environments). - **Simplified configuration**: Fewer configurable options, with opinionated defaults, provide the best Nextflow pipeline and Studio session execution environment, with both Wave and Fusion enabled. - **Fewer AWS dependencies**: Only one IAM role in AWS is required. IAM roles are subject to a 1000 soft limit per AWS account. - **Spot instances**: Studios can be launched on a Spot instance. This type of compute environment is best suited to run Studios and small to medium-sized pipelines. It offers more predictable compute pricing, given the fixed instance types. It spins up a standalone EC2 instance and executes a Nextflow pipeline or Studio session with a local executor on the EC2 machine. At the end of the execution, the instance is terminated. :::caution Limitations The Nextflow pipeline will run entirely on a single EC2 instance. If the instance does not have sufficient resources, the pipeline execution will fail. For this reason, the number of tasks Nextflow can execute in parallel is limited by the number of cores of the instance type selected. If you need more computing resources, you must create a new compute environment with a larger instance type. This makes the compute environment less suited for larger, more complex pipelines. ::: ## Supported regions The following regions are currently supported: - `af-south-1` - `ap-east-1` - `ap-northeast-1` - `ap-northeast-2` - `ap-northeast-3` - `ap-south-1` - `ap-southeast-1` - `ap-southeast-2` - `ap-southeast-3` - `ca-central-1` - `eu-central-1` - `eu-north-1` - `eu-south-1` - `eu-west-1` - `eu-west-2` - `eu-west-3` - `me-south-1` - `sa-east-1` - `us-east-1` - `us-east-2` - `us-west-1` - `us-west-2` ## Seqera Intelligent Compute :::info[Private preview] Seqera Intelligent Compute is in private preview. [Contact us](https://seqera.io/intelligent-compute/) to request access. ::: Seqera Intelligent Compute is a next-generation compute and scheduling service that runs large-scale Nextflow pipelines on a Seqera-managed Amazon ECS cluster, scaling beyond a single instance while preserving the fast startup of the AWS Cloud compute environment When you enable Seqera Intelligent Compute, Seqera provisions and manages all ECS infrastructure on your behalf, including clusters, capacity providers, task definitions, IAM roles, and (optionally) Auto Scaling Groups for spot and on-demand capacity. All managed resources use the `seqera-sched-` prefix and are torn down automatically when no longer needed. If you enable Seqera Intelligent Compute, you must attach the additional permissions described in [Seqera Intelligent Compute permissions](#seqera-intelligent-compute-permissions). For full setup instructions, see [Intelligent Compute](./intelligent-compute). ## Managed Amazon Machine Image (AMI) The AWS Cloud compute environment uses a public AMI maintained by Seqera, and the pipeline launch procedure assumes that some basic tooling is already present in the image itself. If you want to provide your own AMI, it must include at least the following: - Docker engine, configured to run at startup. - CloudWatch agent. - The ability to shut down with the `shutdown` command. If this is missing, EC2 instances will keep running and accumulate additional costs. ### Release cadence and software updates The AMI is based on the [Amazon Linux 2023 image](https://docs.aws.amazon.com/linux/al2023/ug/what-is-amazon-linux.html). System package versions are pinned for each specific Amazon Linux 2023 version. Seqera subscribes to the [AWS SNS topic](https://docs.aws.amazon.com/linux/al2023/ug/receive-update-notification.html) to receive Amazon Linux 2023 update notifications. When updates are available, this triggers a new Seqera AMI release built on the latest image, which includes system package updates and security patches. ## Setup To use the AWS Cloud compute environment, grant Seqera Platform access to your AWS account. Create an IAM policy with the permissions Platform needs, then attach it to either an IAM user (for long-lived access keys) or an IAM role (for assumed-role credentials) depending on which credential type suits your security model. ### Required Platform IAM permissions To create and launch pipelines, explore buckets with Data Explorer or run Studio sessions with the AWS Cloud compute environment, an IAM user with specific permissions must be provided. Some permissions are mandatory for the compute environment to be created and function correctly, while others are optional and used for example to provide list of values to pick from in the Platform UI. Permissions can be attached directly to an [IAM user](#iam-user-creation), or to an [IAM role](#iam-role-creation-optional) that the IAM user can assume when accessing AWS resources. A permissive and broad policy with all the required permissions is provided here for a quick start. However, follow the principle of least privilege and only grant the necessary permissions for your use case, as shown in the following sections.
Full permissive policy (for reference) {AwsCloudFullPolicy}
[Download aws-cloud-full-policy.json](./_policies/aws-cloud-full-policy.json) #### Compute environment creation The following permissions are required to provision resources in the AWS account. Only IAM roles that will be assumed by the EC2 instance must be provisioned: ```json { "Sid": "AwsCloudCreate", "Effect": "Allow", "Action": [ "iam:CreateRole", "iam:AddRoleToInstanceProfile", "iam:CreateInstanceProfile", "iam:AttachRolePolicy", "iam:PutRolePolicy", "iam:TagRole", "iam:TagInstanceProfile" ], "Resource": [ "arn:aws:iam::*:role/TowerForge-*", "arn:aws:iam::*:instance-profile/TowerForge-*" ] }, { "Sid": "AwsCloudCreatePassRole", "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": "arn:aws:iam::*:role/TowerForge-*" } ``` #### Compute environment validation The following permissions are required to validate the compute environment at creation time. Seqera validates the input provided and that the resource ARNs exist in the target AWS account: ```json { "Sid": "AwsCloudValidate", "Effect": "Allow", "Action": [ "ec2:DescribeInstanceTypes", "ec2:DescribeImages", "ec2:DescribeSubnets", "ec2:DescribeSecurityGroups" ], "Resource": "*" } ``` #### Pipeline and Studio session management The following permissions are required to launch pipelines, run Studio sessions, fetch live execution logs from CloudWatch, download logs from S3, and stop the execution: ```json { "Sid": "AwsCloudLaunchEC2", "Effect": "Allow", "Action": [ "ec2:CreateTags", "ec2:DeleteTags", "ec2:DescribeInstances", "ec2:RunInstances", "ec2:TerminateInstances" ], "Resource": "*" }, { "Sid": "AwsCloudLaunchLogs", "Effect": "Allow", "Action": [ "logs:GetLogEvents" ], "Resource": "arn:aws:logs:*:*:log-group:*:log-stream:*" }, { "Sid": "AwsCloudLaunchS3", "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": "arn:aws:s3:::/WORKDIR/*" } ``` #### Compute environment termination and resource disposal The following permissions are required to remove resources created by Seqera when the compute environment is deleted: ```json { "Sid": "AwsCloudDelete", "Effect": "Allow", "Action": [ "iam:GetRole", "iam:ListAttachedRolePolicies", "iam:ListRolePolicies", "iam:DeleteRole", "iam:DeleteInstanceProfile", "iam:RemoveRoleFromInstanceProfile", "iam:DetachRolePolicy", "iam:DeleteRolePolicy" ], "Resource": [ "arn:aws:iam::*:role/TowerForge-*", "arn:aws:iam::*:instance-profile/TowerForge-*" ] } ``` #### Optional permissions The following permissions enable Seqera to populate values for drop-down fields. If missing, the input fields will not be auto-populated but can still be manually entered. Though optional, these permissions are recommended for a smoother and less error-prone user experience. The `s3:ListAllMyBuckets` action also allows Data Explorer to auto-discover the data repositories accessible to your workspace credentials: ```json { "Sid": "AwsCloudRead", "Effect": "Allow", "Action": [ "ec2:DescribeInstanceTypes", "ec2:DescribeKeyPairs", "ec2:DescribeVpcs", "ec2:DescribeImages", "ec2:DescribeSubnets", "ec2:DescribeSecurityGroups", "s3:ListAllMyBuckets" ], "Resource": "*" } ``` #### Userdata script error detection (optional) Platform can retrieve the EC2 instance console output to detect errors in the userdata script that bootstraps the VM during instance startup. If the userdata script fails, Platform surfaces the failure as a warning on the workflow. Without this permission, userdata script failures are not detected and no warning is shown. ```json { "Sid": "AwsCloudUserdataCheck", "Effect": "Allow", "Action": [ "ec2:GetConsoleOutput" ], "Resource": "*" } ``` #### Data lineage (optional) If you enable [data lineage](../data/data-lineage) in your workspace, add the following permissions to your Platform integration credentials to create the queue infrastructure and bucket notifications used by the lineage service: ```json { "Sid": "LineageIntegrationSQS", "Effect": "Allow", "Action": [ "sqs:CreateQueue", "sqs:GetQueueAttributes", "sqs:SetQueueAttributes", "sqs:GetQueueUrl", "sqs:ReceiveMessage", "sqs:DeleteMessage" ], "Resource": "arn:aws:sqs:::seqera-lineage-*" }, { "Sid": "LineageIntegrationS3", "Effect": "Allow", "Action": [ "s3:CreateBucket", "s3:GetBucketNotification", "s3:PutBucketNotification", "s3:GetBucketLocation" ], "Resource": "arn:aws:s3:::seqera-lineage-*" } ``` If you manage your own EC2 instance role (rather than letting Seqera create it automatically), see [Custom instance profile](#custom-instance-profile) for the minimum permissions to attach. #### Seqera Intelligent Compute permissions :::info[Private preview] Seqera Intelligent Compute is in private preview. [Contact us](https://seqera.io/intelligent-compute/) to request access. ::: If you've enabled [Seqera Intelligent Compute](#seqera-intelligent-compute), see [Intelligent Compute IAM permissions](./intelligent-compute#iam-permissions) for the full list of required policies. ### Create the IAM policy The policy above must be created in the AWS account where the AWS Cloud resources need to be created. 1. Open the [AWS IAM console](https://console.aws.amazon.com/iam) in the account where you want to create the AWS Batch resources. 1. From the left navigation menu, select **Policies** under **Access management**. 1. Select **Create policy**. 1. On the **Policy editor** section, select the **JSON** tab. 1. Following the instructions detailed in the [IAM permissions breakdown section](#required-platform-iam-permissions) replace the default text in the policy editor area under the **JSON** tab with a policy adapted to your use case, then select **Next**. 1. Enter a name and description for the policy on the **Review and create** page, then select **Create policy**. If you are also enabling Seqera Intelligent Compute, see [Intelligent Compute IAM permissions](./intelligent-compute#iam-permissions) for the additional policies required. ### AWS credential options Before creating an IAM user or role, decide how Seqera will authenticate to your AWS account. AWS credentials can be configured in two ways: - **Key-based credentials**: Access key and secret key with direct IAM permissions. If you provide a role ARN in **Assume role**, the **Generate External ID** switch is displayed and External ID generation is optional. - **Role-based credentials (recommended)**: Use role assumption only (no static keys). Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. External ID is generated automatically when you save. Use the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. This field is available for both key-based and role-based credentials. It is optional for key-based credentials and required for role-based credentials. Existing credentials created before March 2026 continue to work without changes. The next two sections cover the AWS-side setup for each option: - For **key-based credentials**, follow [IAM user creation](#iam-user-creation) to create a user and obtain access keys. - For **role-based credentials**, follow both [IAM user creation](#iam-user-creation) (for the assuming principal) and [IAM role creation (optional)](#iam-role-creation-optional) to create the role Seqera will assume. #### IAM user creation Seqera requires an Identity and Access Management (IAM) User to create and manage AWS Batch resources in your AWS account. We recommend creating a separate IAM policy rather than an IAM User inline policy, as the latter only allows 2048 characters, which may not be sufficient for all the required permissions. In certain scenarios, for example when multiple users need to access the same AWS account and provision AWS Batch resources, an IAM role with the required permissions can be created instead, and the IAM user can assume that role when accessing AWS resources, as detailed in the [IAM role creation (optional)](#iam-role-creation-optional) section. Depending whether you choose to let Seqera automatically create the required AWS Batch resources in your account, or prefer to set them up manually, the IAM user must have specific permissions as detailed in the [Required Platform IAM permissions](#required-platform-iam-permissions) section. Alternatively, you can create an IAM role with the required permissions and allow the IAM user to assume that role when accessing AWS resources, as detailed in the [IAM role creation (optional)](#iam-role-creation-optional) section. ##### Create an IAM user 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Users** in the left navigation menu, then select **Create User** at the top right of the page. 1. Enter a name for your user (e.g., _seqera_) and select **Next**. 1. Under **Permission options**, select **Attach policies directly**, then search for and select the policy created above, and select **Next**. * If you prefer to make the IAM user assume a role to manage AWS resources (see the [IAM role creation (optional)](#iam-role-creation-optional) section), create a policy with the following content (edit the AWS principal with the ARN of the role created) and attach it to the IAM user: ```json { "Sid": "AssumeRoleToManageBatchResources", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam:::role/", "Condition": { "StringEquals": { "sts:ExternalId": "" } } } ``` 1. On the last page, review the user details and select **Create user**. The user has now been created. The most up-to-date instructions for creating an IAM user can be found in the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). ##### Obtain IAM user credentials 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Users** in the left navigation menu, then select the newly created user from the users table. 1. Select the **Security credentials** tab, then select **Create access key** under the **Access keys** section. 1. In the **Use case** dialog that appears, select **Command line interface (CLI)**, then tick the confirmation checkbox at the bottom to acknowledge that you want to proceed creating an access key, and select **Next**. 1. Optionally provide a description for the access key, like the reason for creating it, then select **Create access key**. 1. Save the **Access key** and **Secret access key** in a secure location as you will need to provide them when creating credentials in Seqera. #### IAM role creation (optional) Rather than attaching permissions directly to the IAM user, you can create an IAM role with the required permissions and allow the IAM user to assume that role when accessing AWS resources. This is useful when multiple IAM users are used to access the same AWS account. This way the permissions to operate on the resources are only granted to a single centralized role. ##### Create an IAM role 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Roles** in the left navigation menu, then select **Create role** at the top right of the page. 1. Select **Custom trust policy** as the type of trusted entity, provide the following policy and edit the AWS principal with the ARN of the IAM user created in the [IAM user creation](#iam-user-creation) section, then select **Next**. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam:::user/" ] }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } } ] } ``` 1. On the **Permissions** page, search for and select the policy created in the [IAM user creation](#iam-user-creation) section, then select **Next**. 1. Give the role a name and optionally a description, review the details of the role, optionally provide tags to help you identify the role, then select **Create role**. Multiple users can be specified in the trust policy by adding more ARNs to the `Principal` section. :::note Seqera Platform generates the `External ID` value during AWS credential creation. For role-based credentials, use this exact value in your IAM trust policy (`sts:ExternalId`). ::: ##### Role-based trust policy example (Seqera Cloud) For role-based AWS credentials in Seqera Cloud, allow the Seqera Cloud access role `arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole` in your trust policy and enforce the `External ID` generated during credential creation: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole" }, "Action": "sts:TagSession" } ] } ``` ## Advanced options - **Pipeline work directory**: The S3 path where Nextflow stores intermediate pipeline files. The S3 bucket must be in the same region as the compute environment. Platform rejects the compute environment at creation time if the bucket region does not match. - **Instance Type**: The EC2 instance type used by the compute environment. Choosing the instance type will directly allocate the CPU and memory available for computation. See [EC2 instance types](https://aws.amazon.com/ec2/instance-types/) for a comprehensive list of instance types and their resource limitations. - **Graviton architecture**: Enable the use of Graviton instances. AWS Graviton processors, based on the ARM64 architecture, tend to offer a better performance-to-price ratio, however, the tooling used by your pipelines must be compatible with ARM architecture. - **AMI ID**: The ID of the AMI that will be used to launch the EC2 instance. Use Seqera-maintained AMIs for best performance. - **Key pair**: The [EC2 key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) to enable SSH connectivity to the running instance. If unspecified, no SSH key will be present in the running EC2 instance. - **VPC ID**: The ID of the VPC where the EC2 instance will be launched. If unspecified, the default VPC will be used. - **Subnets**: The list of VPC subnets where the EC2 instance will run. If unspecified, all the subnets of the VPC will be used. - **Security groups**: The security groups the EC2 instance will be a part of. If unspecified, no security groups will be used. - **Instance Profile**: The ARN of the `InstanceProfile` used by the EC2 instance to assume a role while running. If unspecified, Seqera will provision one with enough permissions to run. See [Custom instance profile](#custom-instance-profile) for the minimum permissions required if you provide your own. - **Boot disk size**: The size of the EBS boot disk for the EC2 instance. If undefined, a default 50 GB `gp3` volume will be used. ### Custom instance profile When you specify a custom **Instance Profile** ARN in Advanced options, the IAM role attached to that instance profile must include the following minimum permissions. These mirror what Seqera provisions automatically when no instance profile is specified. #### Trust policy The role must be assumable by the EC2 service: ```json { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRole", "Principal": { "Service": "ec2.amazonaws.com" } } } ``` #### AWS managed policies Attach the following AWS managed policies to the role: | Policy | Purpose | |--------|---------| | `arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy` | Push metrics and logs to CloudWatch | | `arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess` | Read-only access to S3 (required by Fusion and Nextflow) | | `arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly` | Pull container images from private ECR repositories | #### Inline policies In addition to the managed policies, attach the following inline policies: **S3 read/write** — grants full object access on the compute environment work directory bucket. Add one statement per bucket if you configure additional buckets under **Allow buckets**: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ListObjectsInBucket", "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": "arn:aws:s3:::" }, { "Sid": "AllObjectActions", "Effect": "Allow", "Action": "s3:*Object", "Resource": "arn:aws:s3:::/*" }, { "Sid": "AllowObjectTagging", "Effect": "Allow", "Action": ["s3:PutObjectTagging", "s3:GetObjectTagging"], "Resource": "arn:aws:s3:::/*" } ] } ``` **Secrets Manager** — grants access to the pipeline secrets Seqera stores in AWS Secrets Manager under the `tower-` prefix. Seqera creates each referenced secret when a pipeline launches and deletes it on completion: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "secretsmanager:CreateSecret", "secretsmanager:DeleteSecret" ], "Resource": ["arn:aws:secretsmanager::*:secret:tower-*"] }, { "Effect": "Allow", "Action": ["secretsmanager:ListSecrets"], "Resource": ["*"] } ] } ``` **KMS for S3** — required if any of the S3 buckets used by the compute environment are encrypted with a customer-managed KMS key (SSE-KMS): ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "KmsS3Read", "Effect": "Allow", "Action": ["kms:Decrypt", "kms:DescribeKey"], "Resource": "arn:aws:kms:*:*:key/*", "Condition": { "StringLike": { "kms:ViaService": "s3.*.amazonaws.com" } } }, { "Sid": "KmsS3Write", "Effect": "Allow", "Action": ["kms:Encrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*"], "Resource": "arn:aws:kms:*:*:key/*", "Condition": { "StringLike": { "kms:ViaService": "s3.*.amazonaws.com" } } } ] } ``` :::note If your AWS account enforces EBS volume encryption at the account level (either via account default encryption settings or an SCP that requires `encrypted=true` on `RunInstances`), the EC2 instance will use a KMS key to encrypt its boot volume. In this case, the instance role must also have `kms:Decrypt`, `kms:GenerateDataKey`, `kms:CreateGrant`, and `kms:DescribeKey` permissions on the relevant KMS key — these are not included in the KMS for S3 policy above, which is scoped to S3 only. Contact your AWS administrator to identify the correct KMS key ARN and add permissions accordingly. ::: When you use a custom instance profile, note that Seqera will not create or manage the IAM role — you are responsible for keeping it up to date as requirements change. --- ## AWS Spot interruption management In AWS Batch environments that use Spot instances, tasks can be interrupted when instances are reclaimed. This is a normal part of how Spot instances operate. The frequency of interruptions can be highly variable, based on factors including the wider demand for AWS services. AWS offers insight into the frequency of Spot reclamations with their **instance-advisor** service, which you can find [here](https://aws.amazon.com/ec2/spot/instance-advisor/). In Seqera Platform, Spot reclamations may appear through log messages like `Host EC2 (instance i-0282b396e52b4c95d) terminated`. These events often result in non-specific exit codes, such as `143` (indicating `SIGTERM`), or sometimes no exit code at all (`-`), depending on the sequence in which the underlying AWS components are shut down. If you're seeing unexpected task failures with one or more of these features, especially with no obvious application error, it's worth reviewing your Spot configuration and retry strategy. This guide outlines best practices for mitigating the impact of Spot interruptions and ensuring critical tasks can retry or recover reliably. ## Recommended mitigations ### Use an On-Demand compute environment For workflows with a significant proportion of long-running processes, the costs of, and mitigations necessary for working with Spot may outweigh the benefits. You may find it simpler and cheaper to run those workloads in On-Demand compute environments. ### Move long-running tasks to On-Demand Tasks with long runtimes are particularly vulnerable to Spot termination. If you don’t already have one, first create an On-Demand compute environment in Seqera Platform. Then, in Platform, you can explicitly assign critical or long-duration tasks to On-Demand queues and leave other tasks to run in a Spot queue by default: ```groovy process { withName: 'run_bcl2fastq' { queue = 'TowerForge-MyOnDemandQueue' } } ``` To find the queue name, open the **Compute Environments** tab in Seqera Platform, and open the relevant compute environment. Scroll down to the **Manual Config Attributes** section to view key configuration details, including queue names. Look for the queue name prefixed with `TowerForge-` if it was created by Forge. ### Use retry strategies for Spot Interruptions #### Handle retries in Nextflow by setting `errorStrategy` and `maxRetries` A retry strategy at the Nextflow level is more appropriate when run times are low and retries are likely to succeed. This can be configured as follows: ```bash process { errorStrategy = 'retry' maxRetries = 3 } ``` This retry strategy in the above example configuration will all types of job failures. Currently, it is not possible to configure retries at the Nextflow level specifically for reclamations because Spot reclamations do not produce diagnostic exit codes. Note that, given the escalating costs of repeated retries, an On-Demand queue is likely a more cost-effective option than very large numbers of retries. If you still see failures after applying a configuration like this, solutions involving On-Demand queues are likely to be more effective at limiting costs and runtimes. #### Handle retries in AWS by setting `aws.batch.maxSpotAttempts` If all processes in your workflow have runtimes short enough to feasibly complete before reclamation, you can consider configuring automatic retries in case of interruption: ```groovy aws.batch.maxSpotAttempts = 3 ``` This is a global setting (not configurable per process) that, in this example, allows a job to retry up to three times on a new Spot instance if the original instance is reclaimed. Retries happen automatically within AWS and restart the task from the beginning. You won't see any evidence of the retries within Platform. From the perspective of both Nextflow and the Platform, only a single attempt is considered to have occurred. The task will be resubmitted to AWS as necessary, subject to the `maxRetries` configuration defined for the workflow. The total number of retries will be `maxRetries` * `aws.batch.maxSpotAttempts`. For a long-running process being pre-empted repeatedly, this can represent very significant costs in time and compute. :::note Starting with Nextflow version 24.08.0-edge, the default value for this setting has been changed to `0` to help avoid unexpected expenses, and you should be careful when activating this setting. ::: ### Implement Spot-to-On-Demand fallback logic If you prefer to optimize for cost but ensure task reliability, consider a hybrid fallback pattern: ```bash process { withName: 'run_bcl2fastq' { errorStrategy = 'retry' maxRetries = 2 queue = { task.attempt > 1 ? 'TowerForge-MyOnDemandQueue' : 'TowerForge-MySpotQueue' } } } ``` With the hybrid setup, the first attempt of a task is sent to the Spot queue, while any retries are directed to the On-Demand queue, where they won't be preempted. This helps avoid repeated preemption of longer-running tasks and can serve as a useful default strategy. However, longer-running jobs should still be submitted directly to an On-Demand queue whenever possible, to avoid the unnecessary cost of the initial preemption. ### Consider enabling Fusion Snapshots (preview feature) Fusion Snapshots can help mitigate interruption risk by checkpointing the task state before termination. This is currently in preview and best suited for compute-intensive or long-running tasks. If you're interested in testing this feature, reach out to our support team at https://support.seqera.io and we will be happy to assist you. --- ## Azure Batch :::note This guide assumes you already have an Azure account with a valid Azure Subscription. For details, visit [Azure Free Account][az-create-account]. Ensure you have sufficient permissions to create resource groups, an Azure Storage account, and an Azure Batch account. ::: ## Azure concepts #### Regions Azure regions are specific geographic locations around the world where Microsoft has established data centers to host its cloud services. Each Azure region is a collection of data centers that provide users with high availability, fault tolerance, and low latency for cloud services. Each region offers a wide range of Azure services that can be chosen to optimize performance, ensure data residency compliance, and meet regulatory requirements. Azure regions also enable redundancy and disaster recovery options by allowing resources to be replicated across different regions, enhancing the resilience of applications and data. #### Resource groups An Azure resource group is a logical container that holds related Azure resources such as virtual machines, storage accounts, databases, and more. A resource group serves as a management boundary to organize, deploy, monitor, and manage the resources within it as a single entity. Resources in a resource group share the same lifecycle, meaning they can be deployed, updated, and deleted together. This also enables easier access control, monitoring, and cost management, making resource groups a foundational element in organizing and managing cloud infrastructure in Azure. #### Accounts Azure uses accounts for each service. For example, an [Azure Storage account][az-learn-storage] will house a collection of blob containers, file shares, queues, and tables. An Azure subscription can have multiple Azure Storage and Azure Batch accounts - however, a Platform compute environment can only use one of each. Multiple Platform compute environments can be created to use separate credentials, Azure Storage accounts, and Azure Batch accounts. #### Service principals An Azure service principal is an identity created specifically for applications, hosted services, or automated tools to access Azure resources. It acts like a user identity with a defined set of permissions, enabling resources authenticated through the service principal to perform actions within the Azure account. Seqera can utilize an Azure service principal to authenticate and access Azure Batch for job execution and Azure Storage for data management. ## Create Azure resources ### Resource group Create a resource group to link your Azure Batch and Azure Storage account: :::note A resource group can be created while creating an Azure Storage account or Azure Batch account. ::: 1. Log in to your Azure account, go to the [Create Resource group][az-create-rg] page, and select **Create new resource group**. 1. Enter a name for the resource group, such as _seqeracompute_. 1. Choose the preferred region. 1. Select **Review and Create** to proceed. 1. Select **Create**. ### Storage account After creating a resource group, set up an [Azure Storage account][az-learn-storage]: 1. Log in to your Azure account, go to the [Create storage account][az-create-storage] page, and select **Create a storage account**. :::note If you haven't created a resource group, you can do so now. ::: 1. Enter a name for the storage account, such as _seqeracomputestorage_. 1. Choose the preferred region. This must be the same region as the Batch account. 1. Platform supports all performance or redundancy settings — select the most appropriate settings for your use case. 1. Select **Next: Advanced**. 1. Enable _storage account key access_. 1. Select **Next: Networking**. - Enable public access from all networks. You can enable public access from selected virtual networks and IP addresses, but you will be unable to use Forge to create compute resources. Disabling public access is not supported. 1. Select **Data protection**. - Configure appropriate settings. All settings are supported by the platform. 1. Select **Encryption**. - Only Microsoft-managed keys (MMK) are supported. 1. In **tags**, add any required tags for the storage account. 1. Select **Review and Create**. 1. Select **Create** to create the Azure Storage account. - You will need at least one Blob Storage container to act as a working directory for Nextflow. 1. Go to your new storage account and select **+ Container** to create a new Blob Storage container. A new container dialog will open. Enter a suitable name, such as _seqeracomputestorage-container_. 1. Go to the **Access Keys** section of your new storage account (_seqeracomputestorage_ in this example). 1. Store the access keys for your Azure Storage account, to be used when you create a Seqera compute environment. :::caution Blob container storage credentials are associated with the Batch pool configuration. Avoid changing these credentials in your Seqera instance after you have created the compute environment. ::: ### Batch account After you have created a resource group and Storage account, create a [Batch account][az-learn-batch]: 1. Log in to your Azure account and select **Create a batch account** on [this page][az-create-batch]. 1. Select the existing resource group or create a new one. 1. Enter a name for the Batch account, such as _seqeracomputebatch_. 1. Choose the preferred region. This must be the same region as the Storage account. 1. Select **Advanced**. 1. For **Pool allocation mode**, select **Batch service**. 1. For **Authentication mode**, select _Shared Key_. 1. Select **Networking**. Ensure networking access is sufficient for Platform and any additional required resources. 1. Add any **Tags** to the Batch account, if needed. 1. Select **Review and Create**. 1. Select **Create**. 1. Go to your new Batch account, then select **Access Keys**. 1. Store the access keys for your Azure Batch account, to be used when you create a Seqera compute environment. :::caution A newly-created Azure Batch account may not be entitled to create virtual machines without making a service request to Azure. See [Azure Batch service quotas and limits][az-batch-quotas] for more information. ::: 1. Select the **+ Quotas** tab of the Azure Batch account to check and increase existing quotas if necessary. 1. Select **+ Request quota increase** and add the quantity of resources you require. Here is a brief guideline: - **Active jobs and schedules**: Each Nextflow process will require an active Azure Batch job per pipeline while running, so increase this number to a high level. See [here][az-learn-jobs] to learn more about jobs in Azure Batch. - **Pools**: Each platform compute environment requires at least one Azure Batch pool. Batch Forge creates two pools by default (one for the head job and one for compute tasks). Each pool is composed of multiple machines of one virtual machine size. :::note To use separate pools for head and compute nodes, see [this FAQ entry](../troubleshooting_and_faqs/azure_troubleshooting). ::: - **Batch accounts per region per subscription**: Set this to the number of Azure Batch accounts per region per subscription. Only one is required. - **Total Dedicated vCPUs per VM series**: See the Azure documentation for [virtual machine sizes][az-vm-sizes] to help determine the machine size you need. We recommend the latest version of the ED series available in your region as a cost-effective and appropriately-sized machine for running Nextflow. However, you will need to select alternative machine series that have additional requirements, such as those with additional GPUs or faster storage. Increase the quota by the number of required concurrent CPUs. In Azure, machines are charged per cpu minute so there is no additional cost for a higher number. ### Credentials There are two types of Azure credentials available: access keys and Entra service principals. Access keys are simple to use but have several limitations: - Access keys are long-lived. - Access keys provide full access to the Azure Storage and Azure Batch accounts. - Azure allows only two access keys per account, making them a single point of failure. - Access keys do not support VNet/subnet configuration. Entra service principals are accounts which can be granted access to Azure Batch and Azure Storage resources: - Service principals enable role-based access control with more precise permissions. - Service principals map to a many-to-many relationship with Azure Batch and Azure Storage accounts. - Some Azure Batch features, such as VNet/subnet configuration, are only available when using Microsoft Entra. Both credential types support Batch Forge and Manual compute environment modes. :::note The two Azure credential types use different authentication methods. You can add more than one credential to a workspace, but Platform compute environments use only one credential at any given time. While separate credentials can be used by separate compute environments concurrently, they are not cross-compatible — access granted by one credential will not be shared with the other. ::: #### Access keys To create an access key: 1. Navigate to the Azure Portal and sign in. 1. Locate the Azure Batch account and select **Keys** under **Account management**. The Primary and Secondary keys are listed here. Copy one of the keys and save it in a secure location for later use. 1. Locate the Azure Storage account and, under the **Security and Networking** section, select **Access keys**. Key1 and Key2 options are listed here. Copy one of them and save it in a secure location for later use. 1. In your Platform workspace **Credentials** tab, select the **Add credentials** button and complete the following fields: - Enter a **Name** for the credentials - **Provider**: Azure - Select the **Shared key** tab - Add the **Batch account** and **Blob Storage account** names and access keys to the relevant fields. 1. Delete the copied keys from their temporary location after they have been added to a credential in Platform. #### Entra service principal and managed identity To use Entra for authentication, you must create a service principal and managed identity. Seqera uses the service principal to authenticate to Azure Batch and Azure Storage. It submits a Nextflow task as the head process to run Nextflow, which authenticates to Azure Batch and Storage using the managed identity attached to the node pool. Therefore, you must create both an Entra service principal and a managed identity: 1. Add the service principal details as credentials in Seqera Platform. 2. Assign the managed identity to each Azure Batch node pool with the relevant permissions. 3. When using Batch Forge, provide the managed identity resource ID for each managed identity. Seqera Platform assigns the identity to each pool during creation. :::note Entra service principal credentials support both Batch Forge and Manual compute environments. Some features, such as VNet/subnet configuration and managed identities, require Entra credentials. When using Entra credentials, a managed identity is recommended for best security practices, but is not mandatory. ::: ##### Service principal See [Create a service principal][az-create-sp] for more details. To create an Entra service principal: 1. In the Azure Portal, navigate to **Microsoft Entra ID**. Under **App registrations**, select **New registration**. 1. Provide a name for the application. The application will automatically have a service principal associated with it. 1. Assign roles to the service principal: 1. Go to the Azure Storage account. Under **Access Control (IAM)**, select **Add role assignment**. 1. Select the **Storage Blob Data Contributor** role. 1. Select **Members**, then **Select Members**. Search for your newly created service principal and assign the role. 1. Repeat the same process for the Azure Batch account, using the **Azure Batch Data Contributor** role. This role is sufficient for pool creation and is narrower than the general **Azure Batch Account Contributor** role (which additionally grants Batch-account create/delete and shared-key regeneration — neither needed by Forge). 1. If you create a managed identity (recommended), also assign the **Managed Identity Operator** role to the service principal on each managed identity. Without this role, Seqera cannot attach the managed identity to a Batch pool. 1. If you plan to deploy Batch pools into a private VNet (by specifying a Subnet ID when creating the compute environment), also assign the **Network Contributor** role (or a custom role granting `Microsoft.Network/virtualNetworks/subnets/join/action`) to the service principal on the VNet. Only the service principal needs VNet permissions (the head and pool managed identities do not). 1. Platform will need credentials to authenticate as the service principal: 1. Navigate back to the app registration. On the **Overview** page, save the **Application (client) ID** value for use in Platform. 1. Select **Certificates & secrets**, then **New client secret**. A new secret is created containing a value and secret ID. Save both values securely for use in Platform. 1. In your Platform workspace **Credentials** tab, select the **Add credentials** button and complete the following fields: - Enter a **Name** for the credentials - **Provider**: Azure - Select the **Entra** tab - Complete the remaining fields: **Batch account name**, **Blob Storage account name**, **Tenant ID** (Directory (tenant) ID in Azure), **Client ID** (Application (client) ID in Azure), **Client secret** (Client secret value in Azure). 1. Delete the ID and secret values from their temporary location after they have been added to a credential in Platform. ##### Managed identity :::info To use managed identities, Seqera requires Nextflow version 24.06.0-edge or later. ::: Nextflow can authenticate to Azure services using a managed identity. This method offers enhanced security compared to access keys, but it must run on Azure infrastructure and requires Entra service principal credentials. Pool creation with a managed identity attached uses the Azure Batch management plane, which only accepts Entra (AAD) tokens, so shared-key credentials cannot create pools with managed identities. When you use a compute environment with a managed identity attached to the Azure Batch pool, Nextflow uses this managed identity for authentication. Seqera still uses the Entra service principal to submit the initial Nextflow task; that task then proceeds with the managed identity for subsequent authentication. 1. In Azure, create a user-assigned managed identity. See [Manage user-assigned managed identities](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities) for detailed steps. Take note of both the **client ID** and the **resource ID** of the managed identity when you create it. 1. Assign the following roles to the managed identity: - **Storage Blob Data Contributor** on the Azure Storage account, so the pool VMs can read inputs and write outputs. - **AcrPull** on any Azure Container Registry the pipeline pulls images from. Without this role, container pulls fail when the pool VM authenticates via the managed identity. See [Required role assignments](https://docs.seqera.io/nextflow/azure#required-role-assignments) for more information. 1. Associate the user-assigned managed identity with the Azure Batch pool. See [Set up managed identity in your Batch pool](https://learn.microsoft.com/en-us/troubleshoot/azure/hpc/batch/use-managed-identities-azure-batch-account-pool#set-up-managed-identity-in-your-batch-pool) for more information. :::note When you use separate head and worker pools, you can assign a different managed identity to each pool. Typically, the head managed identity needs broader Batch and storage permissions, while the worker managed identity only needs storage and `AcrPull` access. ::: 1. When you set up the Seqera compute environment, provide the managed identity details in the specified fields. The form has four managed identity fields — a **client ID** and a **resource ID** for both the head pool and the worker pool: - **Resource IDs** are the full ARM paths of the managed identities (e.g., `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}`). Seqera passes these to Azure Batch at pool-create time to attach the managed identity to the head pool and worker pool VMs respectively. Resource IDs are required when using Batch Forge. - **Client IDs** are passed to Nextflow, Fusion, and AzCopy on the pool VMs. The Azure Instance Metadata Service uses the client ID to mint a token for the correct managed identity. A VM can have multiple managed identities attached, so the consumer must specify which one to use. You can use the same managed identity for both head and worker pools by entering the same values in both pairs of fields, but separate identities are recommended so that worker RBAC can stay narrower than head RBAC. The four fields work for both single-pool and dual-pool topologies: - **Single-pool** (head pool only): both managed identities are attached to the same VMs. The client IDs disambiguate which managed identity each consumer authenticates as. - **Dual-pool** (separate head and worker pools): each pool has only its own managed identity attached, so disambiguation is implicit at the VM level. The client IDs are still required so that consumers know which managed identity is theirs. When you submit a pipeline to this compute environment, Nextflow authenticates using the managed identity associated with the Azure Batch node it runs on, rather than relying on access keys. :::caution If a managed identity is misconfigured (for example, invalid client ID or missing RBAC roles), the pipeline fails with an explicit error. Seqera will not silently fall back to access key authentication. ::: ## Add Seqera compute environment There are two ways to create an Azure Batch compute environment in Seqera Platform: - [**Batch Forge**](#batch-forge): Automatically creates Azure Batch resources. - [**Manual**](#manual): For using existing Azure Batch resources. ### VM size considerations Azure Batch requires you to select an appropriate VM size for your compute environment. There are a number of considerations when selecting VM sizes — See [Sizes for virtual machines in Azure][az-vm-sizes] for more information. 1. **Family**: The first letter of the VM size name indicates the machine family. For example, `Standard_E16d_v5` is a member of the E family. - *A*: Economical machines, low power machines. - *B*: Burstable machines which use credits for cost allocation. - *D*: General purpose machines suitable for most applications. - *DC*: D machines with additional confidential compute capabilities. - *E*: The same as D but with more memory. These are generally the best machines for bioinformatics workloads. - *EC*: The same as E but with additional confidential compute capabilities. - *F*: Compute optimized machines which come with a faster CPU compared to D-series machines. - *M*: Memory optimized machines which come with extremely large and fast memory layers, typically more than is needed for bioinformatics workloads. - *L*: Storage optimized machines which come with large locally attached NVMe storage drives. Note that these need to be configured before you can use them with Azure Batch. - *N*: Accelerated computing machines which come with FPGAs, GPUs, or custom ASICs. - *H*: High performance machines which come with the fastest processors and memory. In general, we recommend using the E family of machines for bioinformatics workloads since these are cost-effective, widely available, and sufficiently fast. 1. **vCPUs**: The machine's number of vCPUs. This is the main factor in determining the speed of the machine. 1. **features**: Additional machine features. For example, some machines come with a local SSD. - d: A local storage disk. Azure Batch can use this disk automatically instead of the operating system disk. - s: The VM supports a [premium storage account][az-premium-storage]. - a: AMD CPUs instead of Intel. - p: ARM-based CPUs, such as Azure Cobalt. - l: Reduced memory with a large cost reduction. 1. **Version**: The version of the VM size. This is the generation of the machine. Typically, more recent is better but availability can vary between regions. In the Azure Portal on the page for your Azure Batch account, request an appropriate quota for your desired VM size. See [Azure Batch service quotas and limits][az-batch-quotas] for more information. ### Batch Forge :::caution Batch Forge automatically creates resources that you may be charged for in your Azure account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: Create a Batch Forge Azure Batch compute environment: 1. In a workspace, select **Compute Environments > New Environment**. 1. Enter a descriptive name, such as _Azure Batch (east-us)_. 1. Select **Azure Batch** as the target platform. 1. Choose existing Azure credentials or add a new credential. :::note Both access keys and Entra service principal credentials are supported for Batch Forge. Some features, such as VNet/subnet configuration, require Entra credentials. ::: 1. Add the **Batch account** and **Blob Storage** account names and access keys. 1. Select a **Region**, such as _eastus_. 1. In the **Work directory** field, enter the Azure blob container created previously. For example, `az://seqeracomputestorage-container/work`. :::note When you specify a Blob Storage bucket as your work directory, this bucket is used for the Nextflow [cloud cache](https://docs.seqera.io/nextflow/cache-and-resume#cache-stores) by default. You can specify an alternative cache location with the **Nextflow config file** field on the pipeline [launch](../launch/launchpad#launch-pipelines) form. ::: 1. Select **Enable Wave containers** to facilitate access to private container repositories and provision containers in your pipelines using the Wave containers service. See [Wave containers][wave-docs] for more information. 1. Select **Enable Fusion v2** to allow access to your Azure Blob Storage data via the [Fusion v2][fusion-docs] virtual distributed file system. This speeds up most data operations. The Fusion v2 file system requires Wave containers to be enabled. See [Fusion file system](../supported_software/fusion/overview) for configuration details.
Use Fusion v2 :::note The compute recommendations below are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. ::: Azure virtual machines include fast SSDs and require no additional storage configuration for Fusion. For optimal performance, use VMs with sufficient local storage to support Fusion's streaming data throughput. 1. Use Seqera Platform version 23.1 or later. 1. Use an Azure Blob storage container as the work directory. 1. Enable **Wave containers** and **Fusion v2**. 1. Select the **Batch Forge** config mode. 1. Specify suitable VM sizes under **VMs type**. A `Standard_E16d_v5` VM or larger is recommended for production use. :::tip We recommend selecting machine types with a local temp storage disk of at least 200 GB and a random read speed of 1000 MBps or more for large and long-lived production pipelines. To work with files larger than 100 GB, increase temp storage accordingly (400 GB or more). The suffix `d` after the core number (e.g., `Standard_E16*d*_v5`) denotes a VM with a local temp disk. Select instances with Standard SSDs — Fusion does not support Azure network-attached storage (Premium SSDv2, Ultra Disk, etc.). Larger local storage increases Fusion's throughput and reduces the chance of overloading the machine. See [Sizes for virtual machines in Azure](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/overview) for more information. :::
1. (Optional) Enter a **Subnet ID** to connect the Batch pool nodes to a private Azure VNet. Enter the full Azure ARM subnet resource ID in the following format: ``` /subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Network/virtualNetworks/{vnetName}/subnets/{subnetName} ``` :::note VNet/subnet configuration requires Entra credentials. This field is only available when Entra credentials are selected. If no subnet ID is provided, default networking is used. The service principal must have the **Network Contributor** role (or `Microsoft.Network/virtualNetworks/subnets/join/action`) on the VNet, otherwise pool creation fails. ::: 1. Set the **Config mode** to **Batch Forge**. 1. Enter the default **VMs type** for compute tasks, depending on your quota limits set previously. The default is _Standard_D4_v3_. 1. Enter the **VMs count**. If autoscaling is enabled (default), this is the maximum number of VMs the compute pool will scale up to. If autoscaling is disabled, this is the fixed number of virtual machines in the compute pool. 1. (Optional) Configure **Head job resources** to control the VM type and resources allocated to the Nextflow head job: - **Head VM type**: The VM size for the head node pool. If not specified, the same VM type as the compute pool is used. - **Head job CPUs**: The number of CPUs allocated to the Nextflow head job. - **Head job memory**: The amount of memory allocated to the Nextflow head job. 1. Enable **Autoscale** to scale the compute pool up and down automatically, based on the number of pipeline tasks. The number of VMs will vary from **0** to **VMs count**. 1. Enable **Dispose resources** for Seqera to automatically delete the Batch pools if the compute environment is deleted on the platform. :::info Batch Forge creates separate Azure Batch pools for the Nextflow head job and compute tasks by default (named `tower-pool-{envId}-head` and `tower-pool-{envId}-worker`). This prevents the head node from competing for resources with compute tasks and allows independent sizing of each pool. ::: 1. Select or create [**Container registry credentials**](../credentials/azure_registry_credentials) to authenticate a registry (used by the [Wave containers](https://docs.seqera.io/nextflow/wave) service). It is recommended to use an [Azure Container registry](https://azure.microsoft.com/en-gb/products/container-registry) within the same region for maximum performance. 1. Apply [**Resource labels**](../resource-labels/overview). This will populate the **Metadata** fields of the Azure Batch pools and jobs. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options you need: - Use **Max wallclock time** to set the maximum duration a job can run. The default is 7 days. Accepts human-readable duration syntax (e.g., `7d`, `12h`, `1d6h30m`). The maximum allowed by Azure Batch is 180 days. Existing compute environments without this setting use Nextflow's default of 30 days. - **Job cleanup toggles** control how Nextflow process jobs are managed on completion. Active jobs consume the quota of your Azure Batch account. Three independent toggles are available: | Toggle | Default | Description | |--------|---------|-------------| | **Delete jobs on completion** | Off | Permanently deletes all jobs and their tasks from Azure Batch when the workflow finishes. | | **Delete tasks on completion** | On | Deletes individual tasks from jobs when they complete successfully. Failed tasks are preserved for debugging. | | **Terminate jobs on completion** | On | Sets jobs to terminate when all their tasks complete. Jobs remain in "completed" state but are no longer active. | Existing compute environments retain their current cleanup behavior. - Use **Token duration** to control the duration of the SAS token generated by Nextflow. This must be as long as the longest period of time the pipeline will run. 1. Select **Add** to finalize the compute environment setup. It will take a few seconds for all the resources to be created before the compute environment is ready to launch pipelines. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your Azure Batch compute environment. ::: ### Manual You can configure Seqera Platform to use a pre-existing Azure Batch pool. This allows the use of more advanced Azure Batch features, such as custom VM images and private networking. See [Azure Batch security best practices][az-batch-best-practices] for more information. :::caution Your Seqera compute environment uses resources that you may be charged for in your Azure account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: #### Create a Nextflow-compatible Azure Batch pool If not described below, use the default settings: 1. **Account**: You must have an existing Azure Batch account. Ideally, you should already have tested whether you can run an Azure Batch task within this account. Any type of account is compatible. 1. **Quota**: You must check you have sufficient quota for the number of pools, jobs, and vCPUs per series. See [Azure Batch service quotas and limits][az-batch-quotas] for more information. 1. On the Azure Batch page of the Azure Portal, select **Pools** and then **+ Add**. 1. **Name**: Enter a **Pool ID** and **Display Name**. This ID will be used by Seqera and Nextflow. 1. **Identity**: Select **User assigned** to use a managed identity for the pool. Select **Add** for the user-assigned managed identity and select the managed identity with the correct permissions to the Azure Storage and Batch accounts. 1. **Operating System**: You can use any Linux-based image here, but it is recommended to use it with a Microsoft Azure Batch-provided image. Note that there are two generations of Azure Virtual Machine images, and certain VM series are only available in one generation. See [Azure Virtual Machine series][az-vm-gen] for more information. For default settings, select the following: - **Publisher**: `microsoft-dsvm` - **Offer**: `ubuntu-hpc` - **Sku**: `2204` - **Security type**: `standard` 1. **OS disk storage account type**: Certain VM series only support a specific Storage account type. See [Azure managed disk types][az-disk-type] and [Azure Virtual Machine series][az-vm-gen] for more information. In general, a VM series with the suffix *s* supports a *Premium LRS* Storage account type. For example, a `standard_e16ds_v5` supports `Premium_LRS` but a `standard_e16d_v5` does not. Premium LRS offers the best performance. 1. **OS disk size**: The size of the OS disk in GB. This must be sufficient to hold every Docker container the VM will run, plus any logging or further files. If you are not using a machine with attached storage, you must increase this disk size to accommodate task files (see VM type below). If you are using a machine with attached storage, this setting can be left at the OS default size. 1. **Container configuration**: Container configuration must be turned on. Do this by switching it from **None** to **Custom**. The type is **Docker compatible** which should be the only available option. This will enable the VM to use Docker images and is sufficient. However, you can add further options: - Under **Container image names** you can add containers for the VM to grab at startup time. Add a list of fully qualified Docker URIs, such as `quay.io/seqeralabs/nf-launcher:j17-23.04.2`. - Under **Container registries**, you can add any container registries that require additional authentication. Select **Container registries**, then **Add**. Here, you can add a registry username, password, and registry server. If you attached the managed identity earlier, select this as an authentication method so you don't have to enter a username and password. 1. **VM size**: This is the size of the VM. See [Sizes for virtual machines in Azure][az-vm-sizes] for more information. 1. **Scale**: Azure Node pools can be fixed in size or autoscale based on a formula. Autoscaling is recommended to enable scaling your resources down to zero when not in use. Select **Auto scale** and change the **AutoScale evaluation interval** to 5 minutes - this is the minimum period between evaluations of the autoscale formula. For **Formula**, you can use any valid formula — See [Create a formula to automatically scale compute nodes in a Batch pool][az-batch-autoscale] for more information. This is the default autoscaling formula, with a maximum of 8 VMs: ``` // Get pool lifetime since creation. lifespan = time() - time("2024-10-30T00:00:00.880011Z"); interval = TimeInterval_Minute * 5; // Compute the target nodes based on pending tasks. // $PendingTasks == The sum of $ActiveTasks and $RunningTasks $samples = $PendingTasks.GetSamplePercent(interval); $tasks = $samples < 70 ? max(0, $PendingTasks.GetSample(1)) : max( $PendingTasks.GetSample(1), avg($PendingTasks.GetSample(interval))); $targetVMs = $tasks > 0 ? $tasks : max(0, $TargetDedicatedNodes/2); targetPoolSize = max(0, min($targetVMs, 8)); // For first interval, deploy 1 node, for other intervals scale up/down as per tasks. $TargetDedicatedNodes = lifespan < interval ? 1 : targetPoolSize; $NodeDeallocationOption = taskcompletion; ``` 1. **Start task**: This is the task that will run on each VM when it joins the pool. This can be used to install additional software on the VM. When using Batch Forge, this is used to install `azcopy` for staging files onto and off of the node. Select **Enabled** and add the following command line to install `azcopy`: ```shell bash -c "chmod +x azcopy && mkdir $AZ_BATCH_NODE_SHARED_DIR/bin/ && cp azcopy $AZ_BATCH_NODE_SHARED_DIR/bin/" ``` Select **Resource files** then select **Http url**. For the **URL**, add `https://nf-xpack.seqera.io/azcopy/linux_amd64_10.8.0/azcopy` and for **File path** enter `azcopy`. Every other setting can be left default. :::note When not using Fusion, every node **must** have `azcopy` installed. ::: 1. **Task Slots**: Set task slots to the machine's number of vCPUs. For example, select `4` for a `Standard_D4_v3` VM size. 1. **Task scheduling policy**: This can be set to `Pack` or `Spread`. `Pack` will attempt to schedule tasks from the same job on the same VM, while `Spread` will attempt to distribute tasks evenly across VMs. 1. **Virtual Network**: If you are using a virtual network, you can select it here. Be sure to select the correct virtual network and subnet. The VMs require: - Access to container registries (such as quay.io and docker.io) to pull containers. - Access to Azure Storage to copy data using `azcopy`. - Access to any remote files required by the pipeline, such as AWS S3 storage. - Communication with the head node that runs Nextflow and Seqera to relay logs and information. Note that overly-restrictive networking may prevent pipelines from running successfully. 1. **Mount configuration**: Nextflow *only* supports Azure File Shares. Select `Azure Files Share`, then add: - **Source**: URL in format `https://${accountName}.file.core.windows.net/${fileShareName}` - **Relative mount path**: Path where the file share will be mounted on the VM - **Storage account name** and **Storage account key** (managed identity is not supported) Leave the node pool to start and create a single Azure VM. Monitor the VM to ensure it starts correctly. If any errors occur, check and correct them - you may need to create a new Azure node pool if issues persist. The following settings can be modified after creating a pool: - Autoscale formula - Start task - Application packages - Node communication - Metadata #### Create a manual Seqera Azure Batch compute environment 1. In a workspace, select **Compute Environments**, then **Add compute environment**. 1. Enter a descriptive name for this environment, such as _Azure Batch (east-us)_. 1. For **Provider**, select **Azure Batch**. 1. Select your existing Azure credentials (access keys or Entra service principal) or select **+** to add new credentials. :::note Both access keys and Entra service principal credentials are supported. Some features, such as VNet/subnet configuration, require Entra credentials. To use Entra with a managed identity, see [Managed identity](#managed-identity) below. ::: 1. Select a **Region**, such as _eastus (East US)_. 1. In the **Work directory** field, add the Azure blob container created previously. For example, `az://seqeracomputestorage-container/work`. :::note When you specify a Blob Storage bucket as your work directory, this bucket is used for the Nextflow [cloud cache](https://docs.seqera.io/nextflow/cache-and-resume#cache-stores) by default. You can specify an alternative cache location with the **Nextflow config file** field on the pipeline [launch](../launch/launchpad#launch-pipelines) form. ::: 1. Select **Enable Wave containers** to facilitate access to private container repositories and provision containers in your pipelines using the Wave containers service. See [Wave containers][wave-docs] for more information. 1. Select **Enable Fusion v2** to allow access to your Azure Blob Storage data via the [Fusion v2][fusion-docs] virtual distributed file system. This speeds up most data operations. The Fusion v2 file system requires Wave containers to be enabled. See [Fusion file system](../supported_software/fusion/overview) for configuration details.
Use Fusion v2 :::note The compute recommendations below are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. ::: Azure virtual machines include fast SSDs and require no additional storage configuration for Fusion. For optimal performance, use VMs with sufficient local storage to support Fusion's streaming data throughput. 1. Use Seqera Platform version 23.1 or later. 1. Use an Azure Blob storage container as the work directory. 1. Enable **Wave containers** and **Fusion v2**. 1. Specify suitable VM sizes under **VMs type**. A `Standard_E16d_v5` VM or larger is recommended for production use. :::tip We recommend selecting machine types with a local temp storage disk of at least 200 GB and a random read speed of 1000 MBps or more for large and long-lived production pipelines. To work with files larger than 100 GB, increase temp storage accordingly (400 GB or more). The suffix `d` after the core number (e.g., `Standard_E16*d*_v5`) denotes a VM with a local temp disk. Select instances with Standard SSDs — Fusion does not support Azure network-attached storage (Premium SSDv2, Ultra Disk, etc.). Larger local storage increases Fusion's throughput and reduces the chance of overloading the machine. See [Sizes for virtual machines in Azure](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/overview) for more information. :::
1. Set the **Config mode** to **Manual**. 1. Enter the **Compute Pool name**. This is the name of the Azure Batch pool you created previously in the Azure Batch account. :::note The default Azure Batch implementation uses a single pool for head and compute nodes. To use separate pools for head and compute nodes, see [this FAQ entry](../troubleshooting_and_faqs/azure_troubleshooting). ::: 1. Enter a user-assigned **Managed identity client ID**, if one is attached to your Azure Batch pool. See [Managed Identity](#managed-identity) below. 1. Apply [**Resource labels**](../resource-labels/overview). This will populate the **Metadata** fields of the Azure Batch pool. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any necessary advanced options: - Use **Jobs cleanup policy** to control how Nextflow process jobs are deleted on completion. Active jobs consume the quota of the Azure Batch account. By default, jobs are terminated by Nextflow and removed from the quota when all tasks successfully complete. If set to _Always_, all jobs are deleted by Nextflow after pipeline completion. If set to _Never_, jobs are never deleted. If set to _On success_, successful tasks are removed but failed tasks will be left for debugging purposes. - Use **Token duration** to control the duration of the SAS token generated by Nextflow. This must be as long as the longest period of time the pipeline will run. 1. Select **Add** to complete the compute environment setup. The creation of resources will take a few seconds, after which you can launch pipelines. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your Azure Batch compute environment. ::: [az-data-residency]: https://azure.microsoft.com/en-gb/explore/global-infrastructure/data-residency/#select-geography [az-batch-quotas]: https://docs.microsoft.com/en-us/azure/batch/batch-quota-limit#view-batch-quotas [az-batch-best-practices]: https://learn.microsoft.com/en-us/azure/batch/security-best-practices [az-vm-sizes]: https://learn.microsoft.com/en-us/azure/virtual-machines/sizes [az-create-account]: https://azure.microsoft.com/en-us/free/ [az-create-sp]: https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal [az-learn-rg]: https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal#create-resource-groups [az-create-batch]: https://portal.azure.com/#create/Microsoft.BatchAccount [az-learn-storage]: https://learn.microsoft.com/en-us/azure/storage/common/storage-account-overview [az-learn-batch]: https://learn.microsoft.com/en-us/training/modules/create-batch-account-using-azure-portal/ [az-learn-jobs]: https://learn.microsoft.com/en-us/azure/batch/jobs-and-tasks [az-create-rg]: https://portal.azure.com/#create/Microsoft.ResourceGroup [az-create-storage]: https://portal.azure.com/#create/Microsoft.StorageAccount-ARM [az-premium-storage]: https://learn.microsoft.com/en-us/azure/virtual-machines/premium-storage-performance [az-vm-gen]: https://learn.microsoft.com/en-us/azure/virtual-machines/generation-2 [az-disk-type]: https://learn.microsoft.com/en-us/azure/virtual-machines/disks-types [az-batch-autoscale]: https://learn.microsoft.com/en-us/azure/batch/batch-automatic-scaling [az-file-shares]: https://docs.seqera.io/nextflow/azure#azure-file-shares [az-vm-sizes]: https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/overview [wave-docs]: https://docs.seqera.io/wave [fusion-docs]: https://docs.seqera.io/fusion --- ## Azure Cloud :::note This compute environment type is currently in public preview. Please consult this guide for the latest information on recommended configuration and limitations. This guide assumes you already have an Azure account with a valid Azure subscription. ::: Many of the current implementations of compute environments for cloud providers rely on the use of batch services such as AWS Batch, Azure Batch, and Google Batch for the execution and management of submitted jobs, including pipelines and Studio session environments. Batch services are suitable for large-scale workloads, but they add management complexity. In practical terms, the currently used batch services result in some limitations: - **Complex setup**: Azure Batch compute environments require users to independently configure their own Batch accounts. - **Long-lived credentials**: Azure Batch uses access keys to authenticate with Batch and Storage accounts. These credentials are long-lived, and Azure has hard limits on the number of access keys that can be created per resource type. - **Quotas**: Azure Batch accounts have limits for jobs, pools, and compute resources. If these limits are exceeded, no additional pipelines can run until the existing resources are removed. The Azure Cloud compute environment addresses these pain points with: - **Simplified configuration**: Fewer configurable options, with opinionated defaults, provide the best Nextflow pipeline and Studio session execution environment, with both [Wave](https://docs.seqera.io/wave) and [Fusion](https://docs.seqera.io/fusion) enabled. - **More secure credentials**: Authenticate exclusively via [Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/what-is-entra). This provides enhanced security by default, with automatic configuration for the user. This type of compute environment is best suited to run Studios and small to medium-sized pipelines. It offers more predictable compute pricing, given the fixed instance types. It spins up a standalone virtual machine and executes a Nextflow pipeline or Studio session with a local executor on the virtual machine. At the end of the execution, the instance is terminated. ## Limitations - The Nextflow pipeline will run entirely on a single virtual machine. If the instance does not have sufficient resources, the pipeline execution will fail. For this reason, the number of tasks Nextflow can execute in parallel is limited by the number of cores of the instance type selected. If you need more computing resources, you must create a new compute environment with a larger instance type. This makes the compute environment less suited for larger, more complex pipelines. - There is a considerable delay before streaming logs can be queried. This means that if your pipeline completes in under a minute, you might not see streaming logs during the execution. ## Created resources Seqera will create the following resources in Azure when creating the compute environment: - One Azure resource group: The container for all other created resources. - One Azure managed identity: The Entra identity connected to the Virtual Machine, enabling Nextflow to authenticate to Azure services. - One Azure role: The role attached to the managed identity, which grants the necessary permissions. - One log analytics workspace: Used to collect and query execution logs. - One data collection rule: To route execution logs to the appropriate Log Analytics table. - One data collection endpoint: The endpoint that receives logs, tied to the data collection rule. - One virtual network: The network in which virtual machines are launched. This resource is only created when no existing virtual network is specified in **Advanced options**. When you provide your own VNet, Platform uses it directly and no network resources are provisioned. When virtual machines are launched, other resources are provisioned for each machine and tied to the machine lifecycle: - One network interface - One OS disk While the workflow is running, logs are streamed to the `Nextflow_log_CL` table in the Log Analytics workspace for the compute environment. You can query logs for your specific workflow ID with this expression: ``` Nextflow_log_CL | where workflowId == "" ``` The table retains logs for 7 days. Nextflow uploads log files to Azure Storage for long-term storage. ## Networking Azure Cloud compute environments use a private-only networking model: - **No public IP**: VMs are launched without a public IP address. All connectivity between Platform and the VM is routed via private networking. If you specify an existing VNet, ensure it has outbound connectivity to Azure services (Storage, Entra ID, Log Analytics) and to Platform. - **Entra ID only**: Azure Cloud credentials require Microsoft Entra ID (client ID and client secret). Storage account key–based credentials are not supported. This applies to both Forge-provisioned and existing virtual networks. ## Requirements ### Platform credentials To create and launch pipelines or Studio sessions with Azure Cloud compute environments, you must attach Seqera credentials with an Entra client ID/client secret pair. These credentials must also include your Azure subscription ID and Storage account configuration. See [Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) and [Add and manage application credentials in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret) for more information. ### Required permissions For granular control over the permissions granted to Seqera, use [Azure custom roles](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles) and [assign](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal) them to the service principal. The full role JSON definition is: ```json { "properties": { "roleName": "seqera-azure-cloud", "description": "Role assumed by Seqera Platform to create Azure Cloud compute environments", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Compute/virtualMachines/read", "Microsoft.Compute/virtualMachines/write", "Microsoft.Compute/virtualMachines/delete", "Microsoft.Compute/virtualMachines/deallocate/action", "Microsoft.Compute/virtualMachines/attachDetachDataDisks/action", "Microsoft.Resources/subscriptions/resourceGroups/write", "Microsoft.Resources/subscriptions/resourceGroups/read", "Microsoft.Resources/subscriptions/resourceGroups/delete", "Microsoft.Network/virtualNetworks/read", "Microsoft.Network/virtualNetworks/write", "Microsoft.Network/virtualNetworks/delete", "Microsoft.Network/virtualNetworks/subnets/read", "Microsoft.Network/virtualNetworks/subnets/write", "Microsoft.Network/virtualNetworks/subnets/delete", "Microsoft.Network/virtualNetworks/subnets/join/action", "Microsoft.Network/networkInterfaces/delete", "Microsoft.Network/networkInterfaces/write", "Microsoft.Network/networkInterfaces/read", "Microsoft.Network/networkInterfaces/join/action", "Microsoft.ManagedIdentity/userAssignedIdentities/read", "Microsoft.ManagedIdentity/userAssignedIdentities/write", "Microsoft.ManagedIdentity/userAssignedIdentities/delete", "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action", "Microsoft.Authorization/roleAssignments/read", "Microsoft.Authorization/roleAssignments/write", "Microsoft.Authorization/roleAssignments/delete", "Microsoft.Authorization/roleDefinitions/read", "Microsoft.Authorization/roleDefinitions/write", "Microsoft.Authorization/roleDefinitions/delete", "Microsoft.Insights/DataCollectionRules/Read", "Microsoft.Insights/DataCollectionRules/Write", "Microsoft.Insights/DataCollectionRules/Delete", "Microsoft.Insights/DataCollectionEndpoints/Write", "Microsoft.Insights/DataCollectionEndpoints/Delete", "Microsoft.OperationalInsights/workspaces/write", "Microsoft.OperationalInsights/workspaces/read", "Microsoft.OperationalInsights/workspaces/delete", "Microsoft.OperationalInsights/workspaces/sharedkeys/action", "Microsoft.OperationalInsights/workspaces/tables/read", "Microsoft.OperationalInsights/workspaces/tables/write", "Microsoft.OperationalInsights/workspaces/tables/delete", "Microsoft.OperationalInsights/workspaces/query/read", "Microsoft.OperationalInsights/workspaces/query/Tables.Custom/read", "Microsoft.Compute/virtualMachines/retrieveBootDiagnosticsData/action", "Microsoft.Storage/storageAccounts/blobServices/containers/read", "Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action" ], "notActions": [], "dataActions": [ "Microsoft.Insights/Telemetry/Write", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/read", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/write", "Microsoft.OperationalInsights/workspaces/tables/data/read" ], "notDataActions": [] } ] } } ``` See [Start from JSON](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles-portal#start-from-json) to create this custom role in the Azure Portal. This role definition can be applied as-is for convenience, or it can be broken down into smaller roles. The purpose for each permission is outlined in the following sections. #### Compute environment creation The following permissions are required to provision resources in the Azure account when first creating the compute environment. - If you specify an existing virtual network: - `Microsoft.Network/virtualNetworks/write` and `Microsoft.Network/virtualNetworks/subnets/write` can be omitted from this role, as Platform skips network provisioning and never writes to your VNet or its subnets. - `Microsoft.Network/virtualNetworks/delete` and `Microsoft.Network/virtualNetworks/subnets/delete` become optional. ```json { "properties": { "roleName": "seqera-azure-cloud-create", "description": "Role assumed by Seqera Platform to create Azure Cloud compute environments", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Resources/subscriptions/resourceGroups/read", "Microsoft.Resources/subscriptions/resourceGroups/write", "Microsoft.Storage/storageAccounts/blobServices/containers/read", "Microsoft.Network/virtualNetworks/read", "Microsoft.Network/virtualNetworks/write", "Microsoft.Network/virtualNetworks/subnets/read", "Microsoft.Network/virtualNetworks/subnets/write", "Microsoft.ManagedIdentity/userAssignedIdentities/read", "Microsoft.ManagedIdentity/userAssignedIdentities/write", "Microsoft.Authorization/roleAssignments/read", "Microsoft.Authorization/roleAssignments/write", "Microsoft.Authorization/roleDefinitions/read", "Microsoft.Authorization/roleDefinitions/write", "Microsoft.Insights/DataCollectionRules/Read", "Microsoft.Insights/DataCollectionRules/Write", "Microsoft.Insights/DataCollectionEndpoints/Write", "Microsoft.OperationalInsights/workspaces/read", "Microsoft.OperationalInsights/workspaces/write", "Microsoft.OperationalInsights/workspaces/tables/write" ], "notActions": [], "dataActions": [], "notDataActions": [] } ] } } ``` #### Pipeline and Studio launch The following permissions are required to launch pipelines and Studios: ```json { "properties": { "roleName": "seqera-azure-cloud-launch", "description": "Role assumed by Seqera Platform to launch Studios and pipelines on Azure Cloud compute environments", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Compute/virtualMachines/read", "Microsoft.Compute/virtualMachines/write", "Microsoft.Compute/virtualMachines/delete", "Microsoft.Compute/virtualMachines/deallocate/action", "Microsoft.Compute/virtualMachines/attachDetachDataDisks/action", "Microsoft.Network/networkInterfaces/read", "Microsoft.Network/networkInterfaces/write", "Microsoft.Network/networkInterfaces/join/action", "Microsoft.Network/virtualNetworks/subnets/join/action", "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action", "Microsoft.Insights/DataCollectionRules/Write", "Microsoft.Insights/DataCollectionEndpoints/Write" ], "notActions": [], "dataActions": [ "Microsoft.Insights/Telemetry/Write" ], "notDataActions": [] } ] } } ``` #### Live stream log fetching The following permissions are required to fetch logs for the pipeline execution while the task is running: ``` json { "properties": { "roleName": "seqera-azure-cloud-logs", "description": "Role to be assumed by Seqera Platform to read live-streamed logs for Azure Cloud compute environments", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.OperationalInsights/workspaces/query/read", "Microsoft.OperationalInsights/workspaces/query/Tables.Custom/read" ], "notActions": [], "dataActions": [ "Microsoft.OperationalInsights/workspaces/tables/data/read" ], "notDataActions": [] } ] } } ``` #### Userdata script error detection (optional) Platform can retrieve the serial console output of the Azure VM to detect errors in the userdata script that bootstraps the VM during instance startup. If the userdata script fails, Platform surfaces the failure as a warning on the workflow. Without this permission, userdata script failures are not detected and no warning is shown. This requires [boot diagnostics](https://learn.microsoft.com/en-us/azure/virtual-machines/boot-diagnostics) to be enabled on the VM and the following permission on the service principal: ```json { "properties": { "roleName": "seqera-azure-cloud-userdata-check", "description": "Role to retrieve boot diagnostics for pre-run script error detection", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Compute/virtualMachines/retrieveBootDiagnosticsData/action" ], "notActions": [], "dataActions": [], "notDataActions": [] } ] } } ``` #### Data-links The following permissions are required to work with [Data Explorer](../data/data-explorer) data-links on Azure: ```json { "properties": { "roleName": "seqera-azure-cloud-data-links", "description": "Role assumed by Seqera Platform to access data-links in Azure Cloud compute environments", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Storage/storageAccounts/blobServices/containers/read", "Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action" ], "notActions": [], "dataActions": [ "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/read", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/write" ], "notDataActions": [] } ] } } ``` #### Compute environment termination and resource disposal The following permissions are required to delete the resources created for the compute environment: ```json { "properties": { "roleName": "seqera-azure-cloud-dispose", "description": "Role assumed by Seqera Platform to delete Azure Cloud compute environment resources", "assignableScopes": [ "/subscriptions/" ], "permissions": [ { "actions": [ "Microsoft.Resources/subscriptions/resourceGroups/delete", "Microsoft.Network/virtualNetworks/delete", "Microsoft.Network/virtualNetworks/subnets/delete", "Microsoft.Network/networkInterfaces/delete", "Microsoft.ManagedIdentity/userAssignedIdentities/delete", "Microsoft.Authorization/roleAssignments/delete", "Microsoft.Authorization/roleDefinitions/delete", "Microsoft.Insights/DataCollectionRules/Delete", "Microsoft.Insights/DataCollectionEndpoints/Delete", "Microsoft.OperationalInsights/workspaces/delete", "Microsoft.OperationalInsights/workspaces/tables/delete" ], "notActions": [], "dataActions": [], "notDataActions": [] } ] } } ``` ## Add Azure Cloud credentials ### Create a custom role in Microsoft Entra First, you must create a custom role with the permissions required for Seqera to manage Azure resources. 1. Save the relevant permissions from the preceding sections to a local JSON file. Replace `` in the `assignableScopes` field of each permission with your Azure subscription ID. 1. In the Azure Portal, go to **Subscriptions** and select your subscription. 1. To create a custom role, select **Access control (IAM)**, then **Add** in the **Create a custom role** section. 1. Provide the following details: - **Custom role name**: e.g., `seqera-azure-cloud` - **Description**: e.g., `Role for Seqera Platform to manage Azure Cloud compute environments` - **Baseline permissions**: Select **Start from JSON** - **File**: Select the local JSON file you saved earlier. 1. Select **Next** and review the permissions to ensure all have been included correctly. 1. Select **Next** and confirm that the assignable scope is your subscription ID. 1. Select **Next**. If you found errors in the previous step, you can edit the JSON file here. 1. Select **Next** and then **Create** to save the role. ### Register an application in Microsoft Entra ID Create an application for Seqera to use for authentication: 1. In the Azure Portal, go to **App registrations** and select **New registration**. 1. Give the app a descriptive name, such as `SeqeraPlatformApp`. 1. Select `Single tenant` for the supported account types. 1. Create a client secret for the application. Seqera will use this value to authenticate to Azure, so keep it secret and store it securely. 1. Under **Certificates & secrets**, select **New client secret** and give it a description such as `SeqeraPlatformSecret`. Set the expiration to a duration that matches your security policy. Select **Add**. After registration, you'll be taken to the application overview page. Copy and save the following values: - **Application (client) ID**: This is your Client ID - **Directory (tenant) ID**: This is your Tenant ID ### Assign the custom role to the service principal Grant the service principal the necessary permissions by assigning the custom role. 1. In the Azure Portal, navigate to **Subscriptions** and select your subscription. Then select **Access control (IAM)** and **Add role assignment** in the **Grant access to this resource** section. 1. Select the **Privileged administrator roles** tab and select the role you created earlier, then select **Next**. 1. Choose **Select members** and search for the application name (`SeqeraPlatformApp`). Then choose **Select**, then **Next**. 1. Select **Review + assign**, **Review**, and then **Assign**. 1. Under **What user can do**, select **Allow user to assign all roles except privileged administrator roles Owner, UAA, RBAC (Recommended)**, then select **Next**. 1. Check the final details and select **Review + assign**. ### Configure Seqera Platform credentials Add the service principal credentials to Seqera: 1. Sign in to your Seqera workspace and navigate to the **Credentials** tab. 1. Select **Add credentials**, select **Azure** as the provider, and select the **Cloud** tab for Microsoft Entra ID authentication. 1. Enter the details of the credentials you saved earlier: - **Name**: Provide a descriptive name, such as `AzureCloudCredentials` - **Subscription ID**: Your Azure subscription ID - **Tenant ID**: Your Directory (tenant) ID from the [Register an application in Microsoft Entra ID](#register-an-application-in-microsoft-entra-id) instructions - **Client ID**: Your Application (client) ID from the [Register an application in Microsoft Entra ID](#register-an-application-in-microsoft-entra-id) instructions - **Client secret**: Your client secret value from the [Register an application in Microsoft Entra ID](#register-an-application-in-microsoft-entra-id) instructions - **Blob Storage account name**: Your Azure Storage account name 1. Review the details, then select **Add** to save the credentials. ### Create a compute environment Create a compute environment in Seqera using the credentials: 1. In your Seqera workspace, navigate to the **Compute Environments** tab and select **Add Compute Environment**. 1. Select **Azure Cloud** as the target platform. 1. From the **Credentials** drop-down, select the credentials you created previously. 1. Enter a name for the compute environment. 1. Enter or select a **Location** for the compute environment. 1. Select the **Work directory** as the Azure blob container you plan to use as the Nextflow working directory. The container must be in the same **Location** as selected in the previous step. 1. (Optional) Under **Advanced options**, specify an **Instance Type**. If left blank, the default virtual machine used is a `Standard_D2ds_v4`. 1. Select **Create** to save the compute environment. ## Advanced options - (Optional) **Subscription ID**: The ID of the subscription where resources must be deployed. If not specified, the subscription ID of the credentials is used. - **Instance Type**: The virtual machine type used by the compute environment. Choosing the instance type will directly allocate the CPU and memory available for computation. See [virtual machine sizes](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/overview) for a comprehensive list of instance types and their resource limitations. - **Virtual network**: An existing Azure virtual network (VNet) in the configured location. The drop-down is populated with VNets discovered in your Azure account for the selected location. When specified, Platform uses this network for all VMs launched in this compute environment and skips network provisioning. Leave blank to let Platform provision a dedicated VNet automatically. :::note The VNet must exist in the same location as the compute environment. Specifying a VNet that does not exist in the location, or a subnet that does not belong to the selected VNet, causes compute environment creation to fail. ::: - **Subnets**: One or more subnet names within the selected VNet. VMs are placed in the first listed subnet at launch time. Leave blank to use the first available subnet on the VNet. This field has no effect when no VNet is specified. Any [network security groups (NSGs)](https://learn.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview) attached to the selected subnet are applied to VMs launched in this compute environment. --- ## Amazon EKS [Amazon EKS](https://aws.amazon.com/eks/) provides managed Kubernetes clusters that enable the execution of containerized workloads at scale. Seqera Platform offers native support for Amazon EKS clusters as Compute Environments for Nextflow pipelines. ## Requirements - Seqera Platform needs an IAM User to obtain details about the EKS cluster, and to fetch log files from the S3 bucket, if one is used as work directory. This user must have the permissions detailed in the [Required Platform IAM permissions](#required-platform-iam-permissions) section. Optionally, permissions can instead be granted to an IAM role that the IAM user can assume when accessing AWS resources. - To use Fusion (recommended) to access data hosted on S3, including writing files to the Nextflow work directory, you need an IAM role that allows the EKS Service Account that Seqera pods use to interact with AWS resources. Refer to section [Configure EKS Service Account IAM role for Fusion v2](#configure-eks-service-account-iam-role-for-fusion-v2) for details. Create a separate IAM role from the optional one assumed by the IAM user to separate the permissions needed by the EKS Service Account from those needed by the IAM user. If you plan to use legacy storage instead of Fusion, you can skip this step. :::tip Seqera Platform assumes an EKS cluster already exists. Follow the [cluster preparation](./k8s) instructions to create the resources required by Seqera. Some administrative privileges are also needed to allow the IAM User to access the cluster, as detailed in the [EKS access](#allow-an-iam-user-or-role-access-to-eks) section. ::: Once you meet all the prerequisites, configure an [Amazon EKS Compute Environment](#amazon-eks-compute-environment) in Seqera. ## Required Platform IAM permissions Seqera Platform requires an IAM user with specific permissions to launch pipelines, explore buckets with Data Explorer, and run Studio sessions on the AWS EKS compute environment. Some permissions are mandatory for the compute environment to function correctly, while others are optional and enable features like populating drop-down lists in the Platform UI. Attach permissions directly to an [IAM user](#iam-user-creation), or to an [IAM role](#iam-role-creation-optional) that the IAM user can assume. A permissive and broad policy with all the required permissions is provided here for a quick start. However, we recommend following the principle of least privilege and only granting the necessary permissions for your use case, as shown in the following sections.
Full permissive policy (for reference) {EksFullPolicy}
[Download eks-full-policy.json](./_policies/eks-full-policy.json) ### EKS cluster access Seqera needs permissions to list EKS clusters in the selected region and to describe the selected cluster to retrieve its connection details. The `eks:ListClusters` action cannot be restricted to specific resources, but the `eks:DescribeCluster` action can be restricted to the specific cluster used as compute environment. ```json { "Sid": "EKSClusterListing", "Effect": "Allow", "Action": [ "eks:ListClusters" ], "Resource": "*" }, { "Sid": "EKSClusterDescription", "Effect": "Allow", "Action": [ "eks:DescribeCluster" ], "Resource": "arn:aws:eks:::cluster/" } ``` No other permissions are required for the IAM user to launch pipelines on the EKS compute environment, as the Service Account created in the [cluster preparation](./k8s) phase performs the actual management of pods and resources, which the IAM user can access via EKS authentication, detailed [in the EKS access section below](#allow-an-iam-user-or-role-access-to-eks). ### S3 access (optional) Seqera automatically attempts to fetch a list of S3 buckets available in the AWS account connected to Platform, to provide them in a drop-down to be used as Nextflow working directory, and make the compute environment creation smoother. This feature is optional, and users can type the bucket name manually when setting up a compute environment. To allow Seqera to fetch the list of buckets in the account, the `s3:ListAllMyBuckets` action can be added, and it must have the `Resource` field set to `*`. The `s3:ListAllMyBuckets` action also allows Data Explorer to auto-discover the data repositories accessible to your workspace credentials. Seqera offers several products to manipulate data on AWS S3 buckets, such as [Studios](../studios/overview) and [Data Explorer](../data/data-explorer); if these features are not needed the related permissions can be omitted. The IAM policy can be scoped down to only allow limited read/write permissions in certain S3 buckets used by Studios/Data Explorer. For each bucket you want to browse, upload to, or download from with Data Explorer, grant `s3:GetObject` and `s3:PutObject` on the bucket objects, and `s3:ListBucket`, `s3:GetBucketLocation`, `s3:GetBucketPolicy`, and `s3:GetBucketAcl` on the bucket itself. In addition, the policy must include permission to check the region and list the content of the S3 bucket used as Nextflow work directory. We also recommend granting the `s3:GetObject` permission on the work directory path to fetch Nextflow log files. :::note If you opted to create a separate S3 bucket only for Nextflow work directories, the IAM user or the Role it assumes only need read access to it. The IAM role used by the EKS Service Account (detailed in the [separate section](#configure-eks-service-account-iam-role-for-fusion-v2)) must have full read/write access to the work directory bucket to allow Fusion to operate correctly. ::: ```json { "Sid": "S3CheckBucketWorkDirectory", "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::example-bucket-used-as-work-directory" ] }, { "Sid": "S3ReadOnlyNextflowLogFiles", "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::example-bucket-used-as-work-directory/path/to/work/directory/*" ] }, { "Sid": "S3ReadWriteBucketsForStudiosDataExplorer", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectTagging", "s3:GetBucketLocation", "s3:GetBucketPolicy", "s3:GetBucketAcl", "s3:ListBucket", "s3:PutObject", "s3:PutObjectTagging", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::example-bucket-read-write-studios", "arn:aws:s3:::example-bucket-read-write-studios/*", "arn:aws:s3:::example-bucket-read-write-data-explorer", "arn:aws:s3:::example-bucket-read-write-data-explorer/*" ] } ``` :::note `s3:GetBucketLocation` allows Data Explorer to resolve each bucket's region. `s3:GetBucketPolicy` and `s3:GetBucketAcl` allow it to inspect each bucket's access configuration when it lists and connects to data repositories. If you prefer not to enumerate individual actions, the `s3:Get*` and `s3:List*` wildcards shown in the full permissive policy also cover these actions. ::: ## Create the IAM policy The policy above must be created in the AWS account where the EKS and S3 resources are located. 1. Open the [AWS IAM console](https://console.aws.amazon.com/iam). 1. From the left navigation menu, select **Policies** under **Access management**. 1. Select **Create policy**. 1. On the **Policy editor** section, select the **JSON** tab. 1. Following the instructions detailed in the [IAM permissions breakdown section](#required-platform-iam-permissions) replace the default text in the policy editor area under the **JSON** tab with a policy adapted to your use case, then select **Next**. 1. Enter a name and description for the policy on the **Review and create** page, then select **Create policy**. ## IAM user creation Seqera requires an Identity and Access Management (IAM) User to describe EKS clusters and S3 buckets in your AWS account. We recommend creating a separate IAM policy rather an IAM User inline policy, as the latter only allows 2048 characters, which may not be sufficient for all the required permissions. In certain scenarios, for example when multiple users need to access the same AWS account, an IAM role with the required permissions can be created instead, and the IAM user allowed to assume the role, as detailed in the [IAM role creation (optional)](#iam-role-creation-optional) section. ### Create an IAM user 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Users** in the left navigation menu, then select **Create User** at the top right of the page. 1. Enter a name for your user (e.g., _seqera_) and select **Next**. 1. Under **Permission options**, select **Attach policies directly**, then search for and select the policy created above, and select **Next**. * If you instead prefer to make the IAM user assume a role to manage AWS resources (see the [IAM role creation (optional)](#iam-role-creation-optional) section), create a policy with the following content (edit the AWS principal with the ARN of the role created) and attach it to the IAM user: ```json { "Sid": "AssumeRole", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam:::role/", "Condition": { "StringEquals": { "sts:ExternalId": "" } } } ``` 1. On the last page, review the user details and select **Create user**. The user has now been created. For more details see the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). ### Obtain IAM user credentials To get the credentials needed to connect Seqera to your AWS account, follow these steps: 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Users** in the left navigation menu, then select the newly created user from the users table. 1. Select the **Security credentials** tab, then select **Create access key** under the **Access keys** section. 1. In the **Use case** dialog that appears, select **Command line interface (CLI)**, then tick the confirmation checkbox at the bottom to acknowledge that you want to proceed creating an access key, and select **Next**. 1. Optionally provide a description for the access key, like the reason for creating it, then select **Create access key**. 1. Save the **Access key** and **Secret access key** in a secure location as they are needed when configuring credentials in Seqera. ## IAM role creation (optional) Rather than attaching permissions directly to the IAM user, you can create an IAM role with the required permissions and allow the IAM user to assume that role when accessing AWS resources. This is useful when multiple IAM users are used to access the same AWS account: this way the actual permissions to operate on the resources are only granted to a single centralized role. 1. From the [AWS IAM console](https://console.aws.amazon.com/iam), select **Roles** in the left navigation menu, then select **Create role** at the top right of the page. 1. Select **Custom trust policy** as the type of trusted entity, provide the following policy and edit the AWS principal with the ARN of the IAM user created in the [IAM user creation](#iam-user-creation) section, then select **Next**. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam:::user/" ] }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } }, { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam:::user/" ] }, "Action": "sts:TagSession" } ] } ``` 1. On the **Permissions** page, search for and select the policy created in the [IAM user creation](#iam-user-creation) section, then select **Next**. 1. Give the role a name and optionally a description, review the details of the role, optionally provide tags to help you identify the role, then select **Create role**. Multiple users can be specified in the trust policy by adding more ARNs to the `Principal` section. :::note Seqera Platform generates the `External ID` value during AWS credential creation. For role-based credentials, use this exact value in your IAM trust policy (`sts:ExternalId`). ::: ### Role-based trust policy example (Seqera Cloud) For role-based AWS credentials in Seqera Cloud, allow the Seqera Cloud access role `arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole` in your trust policy and enforce the `External ID` generated during credential creation: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::161471496260:role/SeqeraPlatformCloudAccessRole" }, "Action": "sts:TagSession" } ] } ``` ## AWS credential options AWS credentials can be configured in two ways: - **Key-based credentials**: Access key and secret key with direct IAM permissions. If you provide a role ARN in **Assume role**, the **Generate External ID** switch is displayed and External ID generation is optional. - **Role-based credentials (recommended)**: Use role assumption only (no static keys). Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. External ID is generated automatically when you save. Use the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. This field is available for both key-based and role-based credentials. It is optional for key-based credentials and required for role-based credentials. Existing credentials created before March 2026 continue to work without changes. ## Configure EKS Service Account IAM role for Fusion v2 To use [Fusion v2](https://docs.seqera.io/fusion) in your Amazon EKS compute environment, an AWS S3 bucket must be used as work directory and both the head and compute Service Accounts (if separate) must have access to the S3 bucket specified as the work directory. If you do not plan to use Fusion in favor of legacy storage, you can skip this section. 1. Create an IAM role with the following permissions: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::" ] }, { "Action": [ "s3:GetObject", "s3:PutObject", "s3:PutObjectTagging", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::/*" ], "Effect": "Allow" } ] } ``` Replace `` with the bucket name used as work directory. 1. The IAM role must also have a trust relationship with the Kubernetes service account (or accounts) that Seqera uses to manage the EKS cluster, which is `tower-launcher-sa` in the default configuration.: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "oidc.eks..amazonaws.com/id/:aud": "sts.amazonaws.com", "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount::" } } } ] } ``` Replace ``, ``, ``, ``, `` with the corresponding values. 1. Annotate the Kubernetes Service Account with the IAM role: ```shell kubectl annotate serviceaccount --namespace eks.amazonaws.com/role-arn=arn:aws:iam:::role/ ``` Replace `` (by default `tower-launcher-sa`, as created in the [cluster preparation guide](./k8s)), ``, and `` with the corresponding values previously defined. This will allow pods using that service account to assume the IAM role and access the S3 bucket specified as work directory. See the [AWS documentation](https://docs.aws.amazon.com/eks/latest/userguide/associate-service-account-role.html) for further details. ## Allow an IAM User or Role access to EKS Configure the EKS cluster to allow the IAM user (or the IAM role it assumes) to access the cluster and manage pods. 1. Retrieve from the [AWS IAM console](https://console.aws.amazon.com/iam) the ARN of the [IAM User](#iam-user-creation) or [IAM Role](#iam-role-creation-optional) previously created. :::note The AWS credentials for the IAM user will be used in the Seqera compute environment configuration. ::: 1. Modify the EKS aws-auth ConfigMap to allow the IAM User to access the cluster and manage pods. This step may require cluster administrator privileges: ```bash kubectl edit configmap -n kube-system aws-auth ``` 1. In the editor that opens, edit the `mapUsers` section to add the following entry, replacing `` with the user ARN retrieved from the AWS IAM console: ```yaml mapUsers: | - userarn: username: tower-launcher-user groups: - tower-launcher-role ``` Alternatively, an IAM role can be allowed to authenticate to the cluster: in this case, the role ARN must be specified in the **Assume role** field when configuring the Seqera compute environment (step 9 in the [Amazon EKS compute environment](#amazon-eks-compute-environment) section), the role must have a trust relationship with the Seqera IAM user, and the role `` must be added to the `mapRoles` section of the EKS auth configuration instead: ```yaml mapRoles: | - rolearn: username: tower-launcher-role groups: - tower-launcher-role ``` See the [AWS documentation](https://docs.aws.amazon.com/eks/latest/userguide/auth-configmap.html) for more details on modifying the aws-auth ConfigMap of an EKS cluster. ## Amazon EKS compute environment :::caution Your compute environment uses resources that you may be charged for in your AWS account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: Once all prerequisites are met, create a Seqera EKS compute environment: 1. Select **Compute environments** from the navigation menu of the Seqera Workspace where you want to setup the CE. 1. Enter a descriptive name for this environment, e.g., `Amazon EKS (eu-west-1)`. 1. Select **Amazon EKS** as the target platform. 1. Under **Storage**, select either **Fusion storage** (recommended) or **Legacy storage**. The [Fusion v2](https://docs.seqera.io/fusion) virtual distributed file system allows access to your AWS S3-hosted data (`s3://` URLs). This eliminates the need to configure a shared file system in your Kubernetes cluster. See [Configure EKS Service Account IAM role for Fusion v2](#configure-eks-service-account-iam-role-for-fusion-v2) below. 1. From the **Credentials** drop-down, select existing AWS credentials, or select **+** to add new credentials. If you're using existing credentials, skip to step 9. The user must have the IAM permissions required to describe and list EKS clusters, per Service Account role requirements. :::note You can create multiple credentials in your Seqera environment. See [Credentials](../credentials/overview). ::: 1. Enter a name, e.g., `EKS Credentials`. 1. Under **AWS credential mode**, select **Keys** or **Role**. 1. For **Keys** mode: - Add the **Access key** and **Secret key** obtained from the AWS IAM console. - Optionally paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - If you paste a role ARN in **Assume role**, the **Generate External ID** switch is displayed. Generating an External ID is optional in **Keys** mode. - If **Generate External ID** is selected, an External ID is automatically generated and shown after you save the credential. 1. For **Role** mode: - Paste the IAM role ARN which Seqera must use for accessing your AWS resources in **Assume role**. - External ID is generated automatically when you save the credential. :::note When using AWS keys without an assumed role, the associated AWS user must have been granted permissions to operate on the cloud resources directly. When an assumed role is provided, the IAM user keys are only used to retrieve temporary credentials impersonating the role specified: this could be useful when e.g. multiple IAM users are used to access the same AWS account, and the actual permissions to operate on the resources are only granted to the role. ::: 1. Select a **Region**, e.g., `eu-west-1 - Europe (Ireland)`. If using Fusion v2, this region must match the location of the S3 bucket you plan to use as work directory. 1. Select a **Cluster name** from the list of available EKS clusters in the selected region. 1. Specify the **Namespace** created in the [cluster preparation](./k8s) instructions, `tower-nf` by default. 1. Specify the **Head service account** created in the [cluster preparation](./k8s) instructions, `tower-launcher-sa` by default. :::note If you enable Fusion v2 (**Fusion storage** in step 4 above), the head service account must have access to the S3 storage bucket specified as your work directory. In the [Advanced options](#amazon-eks-advanced-options) below, a service account for compute jobs need to also be specified to allow pods to interact with AWS. ::: 1. Define the **Work directory** used as the working directory by Nextflow pipelines. If using Fusion v2, this must be an S3 bucket (e.g., `s3://my-bucket/work-dir`). If using Legacy storage, this must the name of a Persistent Volume Claim (PVC) created in the [cluster preparation](./k8s) instructions, e.g., `tower-scratch`. 1. Apply [**Resource labels**](../resource-labels/overview) to the cloud resources produced by this compute environment. Workspace default resource labels are prefilled. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. Here's an example configuration to require the compute pods to be scheduled on specific nodes: ```groovy k8s { pod = [ [ nodeSelector: 'myNodeSelector=my-nodes-for-k8s-as-compute' ], [ toleration: [ key: 'myNodeSelector', operator: 'Equal', value: 'my-nodes-for-k8s-as-compute', effect: 'NoSchedule' ] ] ] } ``` :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options described in the next section, as needed. ### Amazon EKS advanced options Amazon EKS compute environments include advanced options for storage and work directory paths, resource allocation, and pod customization. - The **Storage mount path** is the file system path where Seqera mounts the Storage claim (default: `/scratch`). - The **Work directory** is the file system path that Nextflow pipelines use as a working directory. This must be the storage mount path (default) or a subdirectory of it. - The **Compute service account** is the service account that Nextflow uses to submit tasks (default: the `default` account in the given namespace). :::note If you enable Fusion v2 (**Fusion storage** in step 4 above), the compute service account must have access to the S3 storage bucket specified as your work directory. This can be the same Service Account used by the Head jobs (`tower-launcher-sa`, created in the [cluster preparation](./k8s) guide), or a separate Service Account with more granular permissions. ::: - The **Pod cleanup policy** determines when to delete terminated pods. - Use **Custom head pod specs** to provide custom options for the Nextflow workflow pod (e.g., `nodeSelector`, `affinity`, etc). For example: ```yaml spec: nodeSelector: disktype: ssd ``` - Use **Head job CPUs** and **Head job memory** to specify resource requirements of the Nextflow workflow pods. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your Amazon EKS compute environment. ::: --- ## Google Kubernetes Engine [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) is a managed Kubernetes cluster that allows the execution of containerized workloads in Google Cloud at scale. Seqera Platform offers native support for GKE clusters to streamline the deployment of Nextflow pipelines. ## Requirements See [here](../compute-envs/google-cloud-batch#configure-google-cloud) for instructions to set up your Google Cloud account and other services (such as Cloud storage). You must have a GKE cluster up and running. Follow the [cluster preparation](../compute-envs/k8s#cluster-preparation) instructions to create the resources required by Seqera. In addition to the generic Kubernetes instructions, you must make a number of modifications specific to GKE. ### Service account role You must grant cluster access to the service account used by the Seqera compute environment. To do this, update the [service account _RoleBinding_](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control#rolebinding): ```yaml cat << EOF | kubectl apply -f - --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: tower-launcher-userbind subjects: - kind: User name: apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: tower-launcher-role apiGroup: rbac.authorization.k8s.io --- EOF ``` Replace `` with the corresponding service account, e.g., `test-account@test-project-123456.google.com.iam.gserviceaccount.com`. See [Role-based access control](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control) for more information. ## Seqera compute environment :::caution Your Seqera compute environment uses resources that you may be charged for in your Google Cloud account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: After you've prepared your Kubernetes cluster and granted cluster access to your service account, create a Seqera GKE compute environment: 1. In a Seqera workspace, select **Compute environments > New environment**. 1. Enter a descriptive name for this environment, e.g., _Google Kubernetes Engine (europe-west1)_. 1. From the **Provider** drop-down, select **Google Kubernetes Engine**. 1. Under **Storage**, select either **Fusion storage** (recommended) or **Legacy storage**. The [Fusion v2](https://docs.seqera.io/fusion) virtual distributed file system allows access to your Google Cloud-hosted data (`gs://` URLs). This eliminates the need to configure a shared file system in your Kubernetes cluster. See [Fusion v2](#fusion-v2) below. 1. From the **Credentials** drop-down, select existing GKE credentials, or select **+** to add new credentials. If you choose to use existing credentials, skip to step 8. 1. Enter a name for the credentials, e.g., _GKE Credentials_. 1. Enter the **Service account key** for your Google service account. :::tip You can create multiple credentials in your Seqera environment. See [Credentials](../credentials/overview). ::: 1. Select the **Location** of your GKE cluster. :::caution GKE clusters can be either regional or zonal. For example, `us-west1` identifies the United States West-Coast _region_, which has three _zones_: `us-west1-a`, `us-west1-b`, and `us-west1-c`. Seqera Platform's auto-completion only shows regions. You should manually edit this field if you're using a zonal GKE cluster. ::: 1. Select or enter the **Cluster name** of your GKE cluster. 1. Specify the **Namespace** created in the [cluster preparation](../compute-envs/k8s#cluster-preparation) instructions. This is _tower-nf_ by default. 1. Specify the **Head service account** created in the [cluster preparation](../compute-envs/k8s#cluster-preparation) instructions. This is _tower-launcher-sa_ by default. :::note If you enable Fusion v2 (**Fusion storage** in step 4 above), the head service account must have access to the Google Cloud storage bucket specified as your work directory. ::: 1. Specify the **Storage claim** created in the [cluster preparation](../compute-envs/k8s#cluster-preparation) instructions. This serves as a scratch filesystem for Nextflow pipelines. The storage claim is called _tower-scratch_ in the provided examples. :::note The **Storage claim** isn't needed when Fusion v2 is enabled. ::: 1. Apply [**Resource labels**](../resource-labels/overview) to the cloud resources consumed by this compute environment. Workspace default resource labels are prefilled. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options described in the next section, as needed. 1. Select **Create** to finalize the compute environment setup. ### Advanced options Seqera Platform compute environments for GKE include advanced options for storage and work directory paths, resource allocation, and pod customization. - The **Storage mount path** is the file system path where the Storage claim is mounted (default: `/scratch`). - The **Work directory** is the file system path used as a working directory by Nextflow pipelines. It must be the storage mount path (default) or a subdirectory of it. - The **Compute service account** is the service account used by Nextflow to submit tasks (default: the `default` account in the given namespace). - The **Pod cleanup policy** determines when to delete terminated pods. - Use **Custom head pod specs** to provide custom options for the Nextflow workflow pod (`nodeSelector`, `affinity`, etc). For example: ```yaml spec: nodeSelector: disktype: ssd ``` - Use **Custom service pod specs** to provide custom options for the compute environment pod. See above for an example. - Use **Head job CPUs** and **Head job memory** to specify the hardware resources allocated for the Nextflow workflow pod. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your GKE compute environment. ::: ### Fusion v2 To use [Fusion v2](https://docs.seqera.io/fusion) in your Seqera GKE compute environment: 1. Use Seqera Platform version 23.1 or later. 1. Use an S3 bucket as the work directory. 1. Both the head service and compute service accounts must have access to the Google Cloud storage bucket specified as the work directory.
Configure IAM to use Fusion v2 1. Ensure the **Workload Identity** feature is enabled for the cluster: - **Enable Workload Identity** in the cluster **Security** settings. - **Enable GKE Metadata Server** in the node group **Security** settings. 1. Allow the IAM service account access to your Google storage bucket: ```shell gcloud storage buckets add-iam-policy-binding gs:// --role roles/storage.objectAdmin --member serviceAccount:@.iam.gserviceaccount.com ``` The role must have at least `storage.objects.create`, `storage.objects.get`, and `storage.objects.list` permissions. 1. Allow the Kubernetes service account to impersonate the IAM service account: ```shell gcloud iam service-accounts add-iam-policy-binding @.iam.gserviceaccount.com --role roles/iam.workloadIdentityUser --member "serviceAccount:.svc.id.goog[/]" ``` 1. Annotate the Kubernetes service account with the email address of the IAM service account: ```shell kubectl annotate serviceaccount --namespace iam.gke.io/gcp-service-account=@.iam.gserviceaccount.com ``` See the [GKE documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#authenticating_to) for further details.
--- ## Google Cloud Batch :::note This guide assumes you have an existing Google Cloud account. Sign up for a free account [here](https://cloud.google.com/). Seqera Platform provides integration to Google Cloud via the [Batch API](https://cloud.google.com/batch/docs/reference/rest). ::: The guide is split into two parts: 1. How to configure your Google Cloud account to use the Batch API. 2. How to create a Google Cloud Batch compute environment in Seqera. ## Configure Google Cloud ### Create a project Go to the [Google Project Selector page](https://console.cloud.google.com/projectselector2) and select an existing project, or select **Create project**. Enter a name for your new project, e.g., _tower-nf_. If you are part of an organization, the location will default to your organization. ### Enable billing See [here](https://cloud.google.com/billing/docs/how-to/modify-project) to enable billing in your Google Cloud account. ### Enable APIs See [here](https://console.cloud.google.com/flows/enableapi?apiid=batch.googleapis.com%2Ccompute.googleapis.com%2Cstorage-api.googleapis.com) to enable the following APIs for your project: - Batch API - Compute Engine API - Cloud Storage API Select your project from the drop-down and select **Enable**. Alternatively, you can enable each API manually by selecting your project in the navigation bar and visiting each API page: - [Batch API](https://console.cloud.google.com/marketplace/product/google/batch.googleapis.com) - [Compute Engine API](https://console.cloud.google.com/marketplace/product/google/compute.googleapis.com) - [Cloud Storage API](https://console.cloud.google.com/marketplace/product/google/storage-api.googleapis.com) ### IAM Seqera requires a service account with appropriate permissions to interact with your Google Cloud resources. As an IAM user, you must have access to the service account that submits Batch jobs. :::caution By default, Google Cloud Batch uses the default Compute Engine service account to submit jobs. This service account is granted the Editor (`roles/Editor`) role. While this service account has the necessary permissions needed by Seqera, this role is not recommended for production environments. Control job access using a custom service account with only the permissions necessary for Seqera to execute Batch jobs instead. ::: #### Service account permissions [Create a custom service account][create-sa] with at least the following permissions: - Batch Agent Reporter (`roles/batch.agentReporter`) on the project - Batch Job Editor (`roles/batch.jobsEditor`) on the project - Logs Writer (`roles/logging.logWriter`) on the project (to let jobs generate logs in Cloud Logging) - Logs Viewer (`roles/logging.logViewer`) on the project (to view and retrieve logs from Cloud Logging) - Service Account User (`roles/iam.serviceAccountUser`) - Secret Manager Secret Accessor (`roles/secretmanager.secretAccessor`) on the project (required if your pipelines use Seqera secrets; the head job and tasks read secrets from GCP Secret Manager) If your Google Cloud project does not require access restrictions on any of its Cloud Storage buckets, you can grant project Storage Admin (`roles/storage.admin`) permissions to your service account to simplify setup. To grant access only to specific buckets, add the service account as a principal on each bucket individually. See [Cloud Storage bucket](#cloud-storage-bucket) below. #### User permissions Ask your Google Cloud administrator to grant you the following IAM user permissions to interact with your custom service account: - Batch Job Editor (`roles/batch.jobsEditor`) on the project - Service Account User (`roles/iam.serviceAccountUser`) on the job's service account (default: Compute Engine service account) - View Service Accounts (`roles/iam.serviceAccountViewer`) on the project - `storage.buckets.list` on the project via a custom role, if you use per-bucket Storage grants instead of project-wide Storage Admin. Seqera requires this permission to validate credentials — without it, credential validation fails and the compute environment is marked invalid. #### Authentication methods Seqera supports two methods for authenticating with Google Cloud: **Service account keys** To authenticate using a service account key, create a [service account JSON key file](https://cloud.google.com/iam/docs/keys-list-get#get-key): 1. In the Google Cloud navigation menu, select **IAM & Admin > Service Accounts**. 2. Select the email address of the service account. :::note The Compute Engine default service account is not recommended for production environments due to its powerful permissions. To use a service account other than the Compute Engine default, specify the service account email address under **Advanced options** on the Seqera compute environment creation form. ::: 3. Select **Keys > Add key > Create new key**. 4. Select **JSON** as the key type. 5. Select **Create**. A JSON file is downloaded to your computer. This file contains the credential needed to configure the compute environment in Seqera. You can manage your key from the **Service Accounts** page. **Workload Identity Federation** Workload Identity Federation (WIF) is the recommended authentication method for production and regulated environments because it eliminates the need for long-lived service account keys. WIF uses short-lived OIDC tokens for authentication, which are generated by Seqera Platform. Platform's OIDC issuer is the issuer value advertised at https://cloud.seqera.io/api/.well-known/openid-configuration. Setting up WIF requires the following steps in the GCP Console: 1. Create a [Workload Identity Pool and Provider](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) in your Google Cloud project. 2. Set Seqera as an OIDC provider within the pool. Set the Issuer URL to `https://cloud.seqera.io/api`. 3. Set the **Allowed audiences**. If left empty, GCP derives a default audience from the provider resource path in the format `//iam.googleapis.com/projects/{PROJECT}/locations/global/workloadIden tityPools/{POOL}/providers/{PROVIDER}`. If you specify a custom value, it must match exactly what you enter in the Token audience field when creating the Google WIF credential in Seqera. 4. Define an attribute mapping and condition. At a minimum set `google.subject=assertion.sub`. This maps the subject claim from Seqera's JWT to GCP's identity space. For more information see [here](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#mappings-and-conditions). You may see a pop-up asking to configure your application and provide an OIDC ID token path. This pop-up can be dismissed. 5. Grant `roles/iam.workloadIdentityUser` on the service account that WIF will impersonate to the Workload Identity Pool principal. This can be set for all pool identities or for a specific workspace. If you have not yet created a service account do so following the guidelines above. 6. If you use the same WIF credential for Data Explorer, grant `roles/iam.serviceAccountTokenCreator` on the service account to itself: ```bash gcloud iam service-accounts add-iam-policy-binding SA_EMAIL \ --member="serviceAccount:SA_EMAIL" \ --role="roles/iam.serviceAccountTokenCreator" ``` Replace `SA_EMAIL` with the service account email. Without this role, viewing or downloading file contents in Data Explorer fails with a signing error. Pipeline runs are not affected. After setting up WIF in the GCP Console, you need the following information to create a credential in Seqera Platform: 1. **Service Account Email**: The email address of the Google Cloud service account that WIF will impersonate. 2. **Workload Identity Provider**: The full resource path of the Workload Identity Provider (e.g., `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID`). 3. **Token Audience** (optional): The intended audience for the OIDC token. Configure this if your Workload Identity Provider requires a specific audience value. Ensure this matches what you have configured in the **Allowed Audiences** value in the GCP console. :::caution If WIF authentication fails at runtime, verify that: - The service account has the required roles (see [Service account permissions](#service-account-permissions)). - The Workload Identity Pool principal has `roles/iam.workloadIdentityUser` on the service account. - The Issuer URL configured in the WIF provider matches Platform's URL. - The Token Audience in the credential (if set) matches the Allowed Audiences in the WIF provider. ::: ### Cloud Storage bucket Google Cloud Storage is a type of **object storage**. To access files and store the results for your pipelines, create a **Cloud bucket** that your Seqera service account can access. #### Create a Cloud Storage bucket 1. In the hamburger menu (**≡**), select **Cloud Storage**. 2. From the **Buckets** tab, select **Create**. 3. Enter a name for your bucket. You will reference this name when you create the compute environment in Platform. 4. Select **Region** for the **Location type** and select the **Location** for your bucket. You'll reference this location when you create the compute environment in Seqera. :::note The Batch API is available in a limited number of [locations][batch-locations]. These locations are only used to store metadata about the pipeline operations. The storage bucket and compute resources can be in any region. ::: 5. Select **Standard** for the default storage class. 6. To restrict public access to your bucket data, select the **Enforce public access prevention on this bucket** checkbox. 7. Under **Access control**, select **Uniform**. 8. Select any additional object data protection tools, per your organization's data protection requirements. 9. Select **Create**. #### Assign bucket permissions 1. After the bucket is created, you are redirected to the **Bucket details** page. 2. Select **Permissions**, then **Grant access** under **View by principals**. 3. Copy the email address of your service account into **New principals**. 4. Select the **Storage Admin** role, then select **Save**. :::tip You've created a project, enabled the necessary Google APIs, created a bucket, and created a service account JSON key file with the required credentials. You now have what you need to set up a new compute environment in Seqera. ::: ### Seqera compute environment :::caution Your Seqera compute environment uses resources that you may be charged for in your Google Cloud account. See [Cloud costs](../monitoring/cloud-costs) for guidelines to manage cloud resources effectively and prevent unexpected costs. ::: After your Google Cloud resources have been created, create a new Platform compute environment: 1. In a workspace, select **Compute Environments > New Environment**. 2. Enter a descriptive name for this environment, e.g., _Google Cloud Batch (europe-north1)_. 3. Select **Google Cloud Batch** as the target platform. #### Credentials 1. From the **Credentials** drop-down, select existing Google credentials or select **+** to add new credentials. If you choose to use existing credentials, skip to the next section. 2. Enter a name for the credentials, e.g., _Google Cloud Credentials_. 3. Paste the contents of the JSON file created previously in the **Service account key** field. #### Location and work directory Select the **Location** where you will execute your pipelines. See [Location][location] to learn more. In the **Work directory** field, enter your storage bucket URL, e.g., `gs://my-bucket`. This bucket must be accessible in the location selected in the previous step. :::note When you specify a Cloud Storage bucket as your work directory, this bucket is used for the Nextflow [cloud cache](https://docs.seqera.io/nextflow/cache-and-resume#cache-stores) by default. You can specify an alternative cache location with the **Nextflow config file** field on the pipeline [launch](../launch/launchpad#launch-pipelines) form. ::: #### Seqera features - Select **Enable Wave containers** to facilitate access to private container repositories and provision containers in your pipelines using the Wave containers service. See [Wave containers][wave-docs] for more information. - Select **Enable Fusion v2** to allow access to your Google Cloud Storage data via the [Fusion v2][fusion-docs] virtual distributed file system. This speeds up most data operations. The Fusion v2 file system requires Wave containers to be enabled. See [Fusion file system][platform-fusion-docs] for configuration details. :::note The compute recommendations below are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. ::: 1. Use Seqera Platform version 23.1 or later. 1. Use a Google Cloud Storage bucket as the work directory. 1. Enable **Wave containers** and **Fusion v2**. 1. Specify suitable virtual machine types and local storage settings, or accept the default machine settings listed below. An `n2-highmem-16-lssd` VM or larger is recommended for production use. :::note To specify virtual machine settings in Platform during compute environment creation, use the **Global Nextflow config** field to apply custom Nextflow process directives to all pipeline runs launched with this compute environment. To specify virtual machine settings per pipeline run in Platform, or as a persistent configuration in your Nextflow pipeline repository, use Nextflow process directives. See [Google Cloud Batch process definition](https://docs.seqera.io/nextflow/google#process-definition) for more information. ::: When Fusion v2 is enabled, the following virtual machine settings are applied: - A 375 GB local NVMe SSD is selected for all compute jobs. - If you do not specify a machine type, a VM from families that support local SSDs is selected. - Any machine types you specify in the Nextflow config must support local SSDs. - Local SSDs are only offered in multiples of 375 GB. You can increment the number of SSDs used per process with the `disk` directive to request multiples of 375 GB. To work with files larger than 100 GB, use at least two SSDs (750 GB or more). - Fusion v2 can also use persistent disks for caching. Override the disk requested by Fusion using the `disk` directive and the `type: pd-standard`. - The `machineType` directive can be used to specify a VM instance type, family, or custom machine type in a comma-separated list of patterns. For example, `c2-*`, `n1-standard-1`, `custom-2-4`, `n*`, `m?-standard-*`. :::note Wave containers and Fusion v2 are recommended features for added capability and improved performance, but neither are required to execute workflows in your compute environment. ::: #### GCP resources Enable **Spot** to use Spot instances, which have significantly reduced cost compared to On-Demand instances. From Nextflow version 24.10, the default Spot reclamation retry setting changed to `0` on AWS and Google. By default, no internal retries are attempted on these platforms. Spot reclamations now lead to an immediate failure, exposed to Nextflow in the same way as other generic failures (returning for example, `exit code 1` on AWS). Nextflow will treat these failures like any other job failure unless you actively configure a retry strategy. For more information, see [Spot instance failures and retries](../troubleshooting_and_faqs/nextflow.md#spot-instance-failures-and-retries). :::info When a Spot instance is reclaimed by Google Cloud, Seqera Platform displays a human-readable description in the task details. Google Batch reserves exit codes in the 50001–59999 range for infrastructure events: | Exit code | Description | |-----------|-------------| | 50001 | Spot instance was reclaimed by Google Cloud | | 50002 | VM became unresponsive (host event or crash) | | 50003 | VM unexpectedly rebooted during task execution | | 50004 | Task reached unresponsive time limit and could not be cancelled | | 50005 | Task exceeded maximum allowed runtime | Exit codes 50006–59999 display a generic infrastructure failure message. Standard application exit codes (1–255) are displayed as before. ::: Apply [**Resource labels**][resource-labels] to the cloud resources consumed by this compute environment. Workspace default resource labels are prefilled. #### Scripting and environment variables - Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: - Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: #### Advanced options :::note If you use VM instance templates for the head or compute jobs (see below), resource allocation and networking values specified in the templates override any conflicting values you specify while creating your Seqera compute environment. ::: 1. Enable **Use Private Address** to ensure that your Google Cloud VMs aren't accessible to the public internet. 1. Use **Boot disk size** to control the persistent disk size that each task and the head job are provided. 1. Use **Boot Disk Image** to select a specific boot disk image for the compute instances. The drop-down is populated with available images from the GCP Compute API and supports autocomplete filtering. This field is optional. If not set, Google Batch uses the default image. 1. Use **Instance Type** to select a specific machine type for the compute instances. The drop-down is populated with available instance types for the selected region and supports autocomplete filtering. This field is optional. If not set, Google Batch selects an appropriate machine type automatically. :::note The **Instance Type** field sets a default machine type at the compute environment level. You can override this for individual processes using the `machineType` [process directive](https://docs.seqera.io/nextflow/google#process-definition) in your Nextflow configuration. ::: 1. Use **Head job CPUs** and **Head job memory** to specify the CPUs and memory allocated for the head job. :::caution The default head job resource values are insufficient for production pipelines. The Nextflow head job is a JVM process that tracks every submitted task, manages pipeline state, and polls the GCP Batch API. If the head job runs out of memory mid-run, the pipeline fails. Tasks already running on worker VMs run to completion, but no new tasks are scheduled. Output files that were already written are not cleaned up automatically. Results may be incomplete. Size the head job based on the number of tasks in your pipeline: | Pipeline scale | Tasks | Recommended CPUs | Recommended memory | |---|---|---|---| | Small | Up to 100 | 2 | 4 GB | | Medium | 100–500 | 4 | 8 GB | | Large | 500+ | 8 | 16 GB | Head job memory scales with the number of concurrent tasks and total pipeline duration. Long-running pipelines keep thousands of task records in memory for resumability, and need more memory than short pipelines with the same peak parallelism. Increase CPUs if task scheduling is slow or the head job logs show high garbage collection (GC) pressure. For large pipelines, you can also increase the JVM heap directly by setting `NXF_JVM_ARGS="-Xms4g -Xmx12g"` as a **Head job** environment variable (see [Scripting and environment variables](#scripting-and-environment-variables)). ::: :::note If you specify a **Head job instance template** (see step 9), the template's machine type overrides the **Head job CPUs** and **Head job memory** values set here. ::: 1. Use **Service Account email** to specify a service account email address other than the Compute Engine default to execute workflows with this compute environment (recommended for productions environments). 1. Use **VPC** and **Subnet** to specify the name of a VPC network and subnet to be used by this compute environment. You can apply network tags directly in the **Network Tags** field (see below) or through VM instance templates used for the Nextflow head and compute jobs. :::note You must specify both a **VPC** and **Subnet** for your compute environment to use either. ::: 1. Use **Network Tags** to apply GCP network tags to the compute instances in this environment. Network tags control which firewall rules and routing policies apply to your instances within their VPC. Enter tags as free-text values. Tags must follow [GCP format requirements](https://cloud.google.com/vpc/docs/add-remove-network-tags): lowercase letters, numbers, and hyphens only, between 1 and 63 characters. You can add up to 64 tags per instance. :::note Network tags require a **VPC** and **Subnet** to be configured. This field is disabled when no VPC is set. ::: 1. Use **Head job instance template** and **Compute jobs instance template** to specify the name or fully-qualified reference of a VM instance template, without the `template://` prefix, to use for the head and compute jobs. [VM instance templates][gcp-vm-instance-template] allow you to define the resources allocated to Batch jobs. Configuration values defined in a VM instance template override any conflicting values you specify while creating your Seqera compute environment. :::caution Seqera does not validate the VM instance template you specify in these fields. Generally, use templates that define only the machine type, network, disk, and configuration values that will not change across multiple VM instances and Seqera compute environments. See [Create instance templates](https://cloud.google.com/compute/docs/instance-templates/create-instance-templates) for instructions to create your instance templates. To prevent errors during workflow execution, ensure that the instance templates you use are suitably configured for your needs with an appropriate machine type. You can define multiple instance templates with varying machine type sizes in your Nextflow configuration using the `machineType` [process directive](https://docs.seqera.io/nextflow/google#process-definition) (e.g., `process.machineType = 'template://my-template-name'`). You can use [process selectors](https://docs.seqera.io/nextflow/config#config-process-selectors) to assign separate templates to each of your processes. ::: Select **Create** to finalize the compute environment setup. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your Google Cloud Batch compute environment. ::: [batch-locations]: https://cloud.google.com/batch/docs/locations [create-sa]: https://cloud.google.com/iam/docs/service-accounts-create#creating [get-json]: https://cloud.google.com/iam/docs/keys-list-get#get-key [location]: https://cloud.google.com/compute/docs/regions-zones#available [wave-docs]: https://docs.seqera.io/nextflow/wave [fusion-docs]: https://docs.seqera.io/fusion [platform-fusion-docs]: ../supported_software/fusion/overview [pre-post-run-scripts]: ../launch/advanced#pre-and-post-run-scripts [resource-labels]: ../resource-labels/overview [gcp-vm-instance-template]: https://cloud.google.com/compute/docs/instance-templates --- ## Google Cloud :::note This compute environment type is currently in public preview. Consult this guide for the latest information on recommended configuration and limitations. This guide assumes you already have a GCP account with a valid subscription. ::: Many of the current implementations of compute environments for cloud providers rely on the use of batch services such as AWS Batch, Azure Batch, and Google Batch for the execution and management of submitted jobs, including pipelines and Studio session environments. Batch services are suitable for large-scale workloads, but they add management complexity. In practical terms, the currently used batch services result in some limitations: - **Long launch delay**: When you launch a pipeline or Studio in a batch compute environment, there's a delay of several minutes before the pipeline or Studio session environment is in a running state. This is caused by the batch services that need to provision the associated compute service to run a single job. - **Complex setup**: Standard batch services require complex identity management policies and configuration of multiple components including batch job definitions, task specifications, resource policies, etc. The Google Cloud compute environment addresses these pain points with: - **Faster startup time**: By eliminating the per-task overhead of VM provisioning, environment bootstrapping, and container image pulling that occurs with traditional batch, Nextflow pipelines reach a `Running` status and Studio sessions connect in under a minute (a 4x improvement compared to classic GCP Batch compute environments). - **Simplified configuration**: Fewer configurable options, with opinionated defaults, provide the best Nextflow pipeline and Studio session execution environment, with both Wave and Fusion enabled. - **Fewer GCP dependencies**: Direct use of Compute Engine eliminates the reliance on Google Batch APIs and reduces the required IAM permissions to core services (Compute Engine, Cloud Storage, and IAM), resulting in a simpler architecture with fewer potential points of failure. This type of compute environment is best suited to run Studios and small to medium-sized pipelines. It offers more predictable compute pricing, given the fixed instance types. It spins up a standalone Google Compute Engine instance and executes a Nextflow pipeline or Studio session with a local executor on the Google Compute Engine machine. At the end of the execution, the instance is terminated. ## Limitations The Nextflow pipeline will run entirely on a single Google Compute Engine instance. If the instance does not have sufficient resources, the pipeline execution will fail. For this reason, the number of tasks Nextflow can execute in parallel is limited by the number of cores of the instance type selected. If you need more computing resources, you must create a new compute environment with a larger instance type. This makes the compute environment less suited for larger, more complex pipelines. ## Supported locations The following locations are currently supported: - `asia-east1` - `asia-east2` - `asia-northeast1` - `asia-northeast2` - `asia-northeast3` - `asia-south1` - `asia-south2` - `asia-southeast1` - `asia-southeast2` - `australia-southeast1` - `australia-southeast2` - `europe-central2` - `europe-north1` - `europe-southwest1` - `europe-west1` - `europe-west2` - `europe-west3` - `europe-west4` - `europe-west6` - `europe-west8` - `europe-west9` - `europe-west10` - `europe-west12` - `me-central1` - `me-west1` - `northamerica-northeast1` - `northamerica-northeast2` - `southamerica-east1` - `southamerica-west1` - `us-central1` - `us-east1` - `us-east4` - `us-east5` - `us-south1` - `us-west1` - `us-west2` - `us-west3` - `us-west4` ## Requirements ### Platform credentials To create and launch pipelines or Studio sessions with this compute environment type, you must attach Seqera credentials for the cloud provider. Some permissions are mandatory for the compute environment to be created and function correctly; others are used to pre-fill Platform options, which are optional. ### Required permissions #### Service account permissions​ [Create a custom service account](https://cloud.google.com/iam/docs/service-accounts-create#creating) with at least the following permissions: - Compute instance admin (`roles/compute.instanceAdmin.v1`) - Project IAM admin (`roles/resourcemanager.projectIamAdmin`) - Service Account Admin (`roles/iam.serviceAccountAdmin`) - Service Account User (`roles/iam.serviceAccountUser`) - Service Usage Consumer (`roles/serviceusage.serviceUsageConsumer`) If your Google Cloud project does not require access restrictions on any of its Cloud Storage buckets, you can grant project Storage Admin (`roles/storage.admin`) permissions to your service account to simplify setup. To grant access only to specific buckets, add the service account as a principal [on each bucket individually](https://docs.seqera.io/platform-cloud/compute-envs/google-cloud-batch#cloud-storage-bucket). For each Google Cloud compute environment created in the Seqera platform, a separate service account is created with the necessary permissions to launch pipelines/studios. :::caution On shared GCP projects, `roles/resourcemanager.projectIamAdmin` lets the service account grant any role to any principal on the project. A compromised credential can then escalate to any project-level role. `roles/iam.serviceAccountAdmin` grants create and delete access to any service account in the project. To harden this, add an [IAM condition](https://cloud.google.com/iam/docs/conditions-overview) to the `roles/iam.serviceAccountAdmin` binding that restricts it to service accounts whose names start with `towerforge-`. ::: #### Userdata script error detection (optional) Platform can retrieve the serial port output of the Compute Engine instance to detect errors in the userdata script that bootstraps the VM during instance startup. This capability is included in the `roles/compute.instanceAdmin.v1` role listed above. If you use a custom role instead, include the `compute.instances.getSerialPortOutput` permission. Without this permission, userdata script failures are not detected, and no warning is shown. ### Authentication methods Seqera supports two methods for authenticating with Google Cloud: #### Service account keys To authenticate using a service account key, create a [service account JSON key file](https://cloud.google.com/iam/docs/keys-list-get#get-key): 1. In the Google Cloud navigation menu, select **IAM & Admin > Service Accounts**. 2. Select the email address of the service account. 3. Select **Keys > Add key > Create new key**. 4. Select **JSON** as the key type. 5. Select **Create**. Google Cloud downloads a JSON file to your computer. It contains the credential you need to configure the compute environment in Seqera. #### Workload Identity Federation Workload Identity Federation (WIF) is the recommended authentication method for production and regulated environments because it avoids long-lived service account keys. Instead, Seqera Platform generates short-lived OIDC tokens for authentication. Platform advertises its OIDC issuer at https://cloud.seqera.io/api/.well-known/openid-configuration. ##### Enable APIs Before setting up WIF, enable the following APIs for your Google Cloud project: - [Cloud Resource Manager API](https://console.cloud.google.com/marketplace/product/google/cloudresourcemanager.googleapis.com) (`cloudresourcemanager.googleapis.com`) - [IAM API](https://console.cloud.google.com/marketplace/product/google/iam.googleapis.com) (`iam.googleapis.com`) - [IAM Service Account Credentials API](https://console.cloud.google.com/marketplace/product/google/iamcredentials.googleapis.com) (`iamcredentials.googleapis.com`) - [Cloud Logging API](https://console.cloud.google.com/marketplace/product/google/logging.googleapis.com) (`logging.googleapis.com`) - [Security Token Service API](https://console.cloud.google.com/marketplace/product/google/sts.googleapis.com) (`sts.googleapis.com`) :::note The Compute Engine, Cloud Storage, and Secret Manager APIs (`compute.googleapis.com`, `storage.googleapis.com`, `secretmanager.googleapis.com`) are also required. Enable them if not already active in your project. ::: ##### Set up WIF in the GCP Console In the GCP Console: 1. Create a [Workload Identity Pool and Provider](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) in your Google Cloud project. 2. Set Seqera as an OIDC provider within the pool. Set the **Issuer URL** to `https://cloud.seqera.io/api`. 3. Set the **Allowed audiences**. If left empty, GCP derives a default audience from the provider resource path in the format `//iam.googleapis.com/projects/{PROJECT}/locations/global/workloadIdentityPools/{POOL}/providers/{PROVIDER}`. If you specify a custom value, it must match exactly what you enter in the **Token audience** field when creating the WIF credential in Seqera. 4. Define an attribute mapping and condition. At a minimum, set google.subject=assertion.sub. This maps the subject claim from Seqera's JWT to GCP's identity space. For more information, see [Attribute mappings and conditions](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#mappings-and-conditions). If a pop-up asks you to configure your application and provide an OIDC ID token path, dismiss it. 5. Grant `roles/iam.workloadIdentityUser` on the service account that WIF will impersonate to the Workload Identity Pool principal. This can be scoped to all pool identities or to a specific workspace: - **All identities in the pool**: `principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*` - **Specific workspace only**: `principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/org:{ORG_ID}:wsp:{WORKSPACE_ID}:workflow` If you have not yet created a service account, do so following the guidelines under [Service account permissions](#service-account-permissions). 6. (Optional) If you use the same WIF credential for [Data Explorer][data-explorer], grant `roles/iam.serviceAccountTokenCreator` on the service account to the Workload Identity Pool principal: ```bash gcloud iam service-accounts add-iam-policy-binding SA_EMAIL \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*" \ --role="roles/iam.serviceAccountTokenCreator" ``` Replace `SA_EMAIL`, `PROJECT_NUMBER`, and `POOL_ID` with your values. Without this role, viewing or downloading file contents in Data Explorer fails. Seqera Platform logs the underlying error as `SigningException: Failed to sign the provided bytes` caused by `Permission 'iam.serviceAccounts.signBlob' denied`. Running pipelines is not affected. To scope this binding to a specific workspace, replace the `principalSet` wildcard with `principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/org:{ORG_ID}:wsp:{WORKSPACE_ID}:workflow`. ##### Configure WIF credentials in Platform After setting up WIF in the GCP Console, you need the following information to create a WIF credential in Platform: 1. **Service Account Email**: The email address of the Google Cloud service account that WIF will impersonate. 2. **Workload Identity Provider**: The full resource path of the Workload Identity Provider, e.g., `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID`. 3. **Token Audience** (optional): The intended audience for the OIDC token. Configure this only if your Workload Identity Provider requires a specific audience value. Ensure this matches the **Allowed audiences** value configured in the GCP console. :::caution If WIF authentication fails at runtime, verify that: - The service account has the required roles (see [Service account permissions](#service-account-permissions)). - The Workload Identity Pool principal has `roles/iam.workloadIdentityUser` on the service account. - The Issuer URL configured in the WIF provider matches Platform's OIDC issuer URL (`https://cloud.seqera.io/api`). - The Token Audience in the credential (if set) matches the Allowed audiences in the WIF provider. ::: ## Advanced options - **Use an ARM64 architecture instance**: Select this option to enable an ARM architecture instance to be created for your compute workload. This option defaults to using a [C4A machine series](https://cloud.google.com/compute/docs/general-purpose-machines#c4a_series) VM with Google's ARM-based Axion™ processor. - **User GPU-enabled instance**: Select this option to enable a GPU-enabled instance to be created for your compute workload. This option defaults to using an [A2 machine series](https://cloud.google.com/compute/docs/gpus) VM with an NVIDIA A100 GPU. - **Instance type**: The Compute Engine machine type used by the compute environment. Choosing the instance type will directly allocate the CPU and memory available for computation. See the [machine resource type documentation](https://cloud.google.com/compute/docs/machine-resource) for a comprehensive list of instance types and their resource limitations. :::note It is not possible to specify instance templates with predefined machine types, storage, bootstrapped, etc. ::: - **Image**: The image defining the operating system and pre-installed software for the VM. Currently only [Ubuntu LTS](https://cloud.google.com/compute/docs/images/os-details#ubuntu_lts) Google public image project images are available and supported. For GPU-enabled instances, a Deep Learning VM base image with CUDA pre-installed is automatically selected (See [Google Deep Learning VM Images](https://cloud.google.com/deep-learning-vm/docs/images#base_versions) for more details). Optimized, Seqera-owned custom images will be available in a future release. - **Boot disk size**: The size of the boot disk for the Compute Engine instance. A standard persistent disk (`pd-standard`) is used. If undefined, a default 50 GB volume will be used. - **Zone**: The [zone](https://cloud.google.com/compute/docs/regions-zones) within the selected region where the VM will be provisioned (defaults to the first zone in the alphabetical list). - **VPC**: An existing VPC network in your Google Cloud project. The drop-down is populated with networks discovered in your project. When specified, Platform uses this network for all VMs launched in this compute environment. Leave blank to use the project's default network. :::note Specifying a subnet that does not exist in the compute environment region, or that does not belong to the selected VPC, causes compute environment creation to fail. ::: - **Subnets**: One or more subnet names within the selected VPC and the compute environment region. VMs are placed in the first listed subnet at launch time; Intelligent Compute may distribute worker VMs across all listed subnets, in order. Leave blank to let Platform select the first available subnet on the network. This field has no effect when no VPC is specified. - **Network tags**: Network tags applied to launched VMs for firewall rule targeting. Tags must be lowercase and contain only letters, numbers, and hyphens (1–63 characters). This field has no effect when no VPC is specified. - **Use private address**: Select this option to launch VMs without a public IP address. The selected VPC must provide outbound internet access through Cloud NAT and Private Google Access. [data-explorer]: ../data/data-explorer --- ## HPC compute environments Seqera Platform streamlines the deployment of Nextflow pipelines into both cloud-based and on-prem HPC clusters and supports compute environment creation for the following management and scheduling solutions: - [Altair PBS Pro](https://www.altair.com/pbs-professional/) - [Grid Engine](https://www.altair.com/grid-engine/) - [IBM Spectrum LSF](https://www.ibm.com/products/hpc-workload-management/details) (Load Sharing Facility) - [Moab](http://docs.adaptivecomputing.com/suite/8-0/basic/help.htm#topics/moabWorkloadManager/topics/intro/productOverview.htm) - [Slurm](https://slurm.schedmd.com/overview.html) ## Requirements To launch pipelines into an **HPC** cluster from Seqera, the following requirements must be satisfied: - The cluster should allow outbound connections to the Seqera web service. - The cluster queue used to run the Nextflow head job must be able to submit cluster jobs. - The Nextflow runtime version **21.02.0-edge** (or later) must be [installed on the cluster](https://docs.seqera.io/nextflow/install). ## Credentials Seqera requires SSH access to your HPC cluster to run pipelines. Use [managed identities](../credentials/managed_identities) to enable granular access control and preserve individual cluster user identities. You can also use workspace [SSH credentials](../credentials/ssh_credentials) for cluster login, but this provides service account access to your HPC to all Platform users. This means that all users will be granted the same file system access, and all activity is logged under the same user account on your HPC cluster. For HPC clusters that do not allow direct access through an SSH client, a secure connection can be authenticated with [Tower Agent](../supported_software/agent/overview). ## Work and launch directories For instances where the work directory or launch directory must be set dynamically at runtime, you can use variable expansion. This works in conjunction with Tower Agent. The path that results from variable expansion must exist before workflow execution as the agent does not create directories. For example, if the HPC cluster file system has a `/workspace` directory with subdirectories for each user that can run jobs, the value for the work directory can be the following: `/workspace/$TW_AGENT_USER`. For a user `user1`, the work directory resolves to the `/workspace/user1` directory. The following variables are supported: - `TW_AGENT_WORKDIR`: Resolves to the work directory for Tower Agent. By default, this directory resolves to the `${HOME}/work` path, where `HOME` is the home directory of the user that the agent runs as. The work directory can be overridden by specifying the `--work-dir` argument when configuring Tower Agent. For more information, see the [Tower Agent][agent] documentation. - `TW_AGENT_USER`: Resolves to the username that the agent is running as. By default, this is the Unix username that the agent runs as. On systems where the agent cannot determine which user it runs as, it falls back to the value of the `USER` environment variable. ## HPC compute environment To create a new **HPC** compute environment: 1. In a Seqera workspace, select **Compute environments > New environment**. 1. Enter a descriptive name for this environment. Use only alphanumeric characters, dashes, and underscores. 1. Select your HPC environment from the **Platform** drop-down. 1. Select your existing managed identity, SSH, or Tower Agent credentials, or select **+** and **SSH** or **Tower Agent** to add new credentials. 1. Enter the absolute path of the **Work directory** to be used on the cluster. You can use the `TW_AGENT_WORKDIR` and `TW_AGENT_USER` variables in the file system path. :::caution All managed identity users must be a part of the same Linux user group. The group must have access to the HPC compute environment work directory. Set group permissions for the work directory as follows (replace `sharedgroupname` and `` with your group name and work directory): ```bash chgrp -R sharedgroupname chmod -R g+wxs setfacl -Rdm g::rwX ``` These commands change the group ownership of all files and directories in the work directory to `sharedgroupname`, ensure new files inherit the directory's group, and apply default ACL entries to allow the group read, write, and execute permissions for new files and directories. This setup facilitates shared access and consistent permissions management in the directory. ::: 1. Enter the absolute path of the **Launch directory** to be used on the cluster. If omitted, it will be the same as the work directory. 1. Enter the **Login hostname**. This is usually the hostname or public IP address of the cluster's login node. 1. Enter the **Head queue name**. This is the [default](https://docs.seqera.io/nextflow/process#queue) cluster queue to which the Nextflow job will be submitted. 1. Enter the **Compute queue name**. This is the [default](https://docs.seqera.io/nextflow/process#queue) cluster queue to which the Nextflow job will submit tasks. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options needed: - Use the **Nextflow queue size** to limit the number of jobs that Nextflow can submit to the scheduler at the same time. - Use the **Head job submit options** to add platform-specific submit options for the head job. You can optionally apply these options to compute jobs as well: :::note Once set during compute environment creation, these options can't be overridden at pipeline launch time. ::: :::note In IBM LSF compute environments, use **Unit for memory limits**, **Per job memory limits**, and **Per task reserve** to control how memory is requested for Nextflow jobs. ::: 1. Select **Create** to finalize the creation of the compute environment. See [Launch pipelines](../launch/launchpad) to start executing workflows in your HPC compute environment. [agent]: ../supported_software/agent/overview --- ## Intelligent Compute :::info[Preview] Seqera Intelligent Compute is in preview. Seqera must enable it on a per-workspace basis before you can use it. Contact your account manager to request access for one or more workspaces. ::: :::caution Intelligent Compute may assign different CPU and memory values to tasks than your pipeline's `process` directives specify. The scheduler picks the most cost-effective instance shape that meets each task's resource request. ::: Intelligent Compute is a scheduling service that runs Nextflow pipelines on a Seqera-managed Amazon ECS cluster. It allocates compute resources based on what each task needs rather than what the pipeline requests. This reduces cost and improves utilization across a run. Intelligent Compute is available only on AWS Cloud compute environments. The standard AWS Cloud compute environment runs each pipeline on a single EC2 instance with a local executor. Intelligent Compute runs pipelines on multi-node ECS clusters that scale beyond a single instance. When you enable Intelligent Compute on an AWS Cloud compute environment, Seqera provisions and manages the following resources in your AWS account on first use: - An Amazon ECS cluster per compute environment configuration - ECS capacity providers (Managed Instances or Auto Scaling Groups) - ECS task definitions per container image and resource shape - IAM roles for ECS task execution, EC2 instance profiles, and infrastructure management - CloudWatch log groups under `/seqera` (for example, `/seqera/platform`) All managed resources use the `seqera-sched-` prefix. Seqera creates them on first use and removes them automatically when no longer needed. ## IAM permissions Intelligent Compute requires **two IAM policies** attached to the same IAM user or role that Seqera uses to access your AWS account: 1. **AWS Cloud policy** — required for all AWS Cloud compute environments. If you have already set up an AWS Cloud compute environment, this policy is already in place. 2. **Intelligent Compute policy** — additional permissions required specifically for Intelligent Compute.
AWS Cloud policy {AwsCloudFullPolicy}
[Download aws-cloud-full-policy.json](./_policies/aws-cloud-full-policy.json)
Intelligent Compute policy {AwsCloudIntelligentComputePolicy}
[Download aws-cloud-intelligent-compute-policy.json](./_policies/aws-cloud-intelligent-compute-policy.json) ### Permission groups | Group | Purpose | |-------|---------| | `ECSScopedOperations` | Create, delete, describe, and tag ECS clusters, capacity providers, and tasks. Scoped to `seqera-sched-*` resources. | | `ECSUnscopedOperations` | Register, deregister, list, and describe ECS task definitions. ECS task definition APIs do not support resource-level permissions. | | `IAMRoleManagement` | Create, update, and delete IAM roles and instance profiles scoped to `seqera-sched-*`. Seqera creates four role types on first use: execution role, infrastructure role, per-cluster instance role, and per-cluster task role. | | `PassRoleToECS` | Pass `seqera-sched-*` and `TowerForge-*` roles to ECS, ECS tasks, and EC2. Required to attach roles to ECS infrastructure and task definitions. | | `ServiceLinkedRoles` | Create service-linked roles for ECS, autoscaling, and Spot. Required only if these roles do not already exist in your account. | | `CloudWatchLogs` | Create and manage log groups under `/seqera` (for example, `/seqera/platform`), and read log events. Task stdout and stderr are written to CloudWatch. | | `EC2NetworkDiscovery` | Describe VPCs, subnets, security groups, and route tables. Create security groups and VPC endpoints. Used for VPC auto-discovery and network setup. | | `ECRAccess` | Authorize ECR and pull container images. ECS tasks pull images from ECR. | | `S3Access` | Read objects and list buckets. Used to read Fusion trace files and pipeline work directory content. | | `ASGEC2Operations` | Describe instance types and create or delete EC2 launch templates. Required only for Auto Scaling Group-backed clusters. | | `ASGManagement` | Create, update, and delete Auto Scaling Groups scoped to `seqera-sched-*`. Required only for Auto Scaling Group-backed clusters. | | `ASGDescribe` | Describe Auto Scaling Groups. Required only for Auto Scaling Group-backed clusters. | | `SSMECSOptimizedAmi` | Read the ECS-optimized AMI ID from SSM Parameter Store. Used to look up the latest Amazon Linux 2023 ECS-optimized AMI. | | `CostExplorer` | Query `ce:GetCostAndUsage`. Used to display cost post pipeline launch, after receiving data from AWS Cost Explorer with a 24-48 delay. If this permission is absent, cost predictions do not appear. | **Conditional statements:** - `ASGEC2Operations`, `ASGManagement`, and `ASGDescribe` are required only if Auto Scaling Group-backed clusters are enabled. You can omit them for Managed Instances deployments. - `ServiceLinkedRoles` is required only if the listed service-linked roles do not already exist in your AWS account. - `CostExplorer` is required only if you want cost predictions at pipeline launch. ### Create and attach the IAM policies Both policies must be attached to the IAM user or role that Seqera uses to access your AWS account before you create the compute environment. Create each policy as follows: 1. Open the [AWS IAM console](https://console.aws.amazon.com/iam). 1. Select **Policies** under **Access management**, then select **Create policy**. 1. Select the **JSON** tab, paste the policy JSON, then select **Next**. 1. Enter a name (for example, `SeqeraAwsCloudPolicy`), then select **Create policy**. 1. Repeat steps 2–4 for the Intelligent Compute policy (for example, `SeqeraIntelligentComputePolicy`). 1. Attach both policies to the IAM user or role that Seqera uses to access your AWS account. ## Set up an AWS Cloud compute environment with Intelligent Compute :::info[**Prerequisites**] You need the following: - Intelligent Compute enabled for your workspace by Seqera. Contact your account manager to request access. - AWS credentials with both the standard AWS Cloud permissions and the Intelligent Compute permissions attached. ::: 1. In your Seqera workspace, select **Compute Environments**, then select **Add compute environment**. 1. Enter a name and select **AWS Cloud** as the platform. 1. Select your AWS credentials. 1. Select the **Region** where Seqera provisions the ECS cluster. 1. Enter a **Work directory** (S3 URI, for example `s3://my-bucket/work`). 1. Under **Compute Mode**, enable the **Seqera Intelligent Compute** toggle. 1. Configure the [Intelligent Compute options](#configuration-options) as needed. 1. Select **Add**. Seqera validates credentials and configuration on save. On first use, it provisions the required IAM roles and ECS cluster in your account. Clusters and associated resources are removed automatically when no longer needed. ## Resource metrics The **Metrics** tab for a run on Intelligent Compute shows three resource values for CPU and memory: **Requested**, **Allocated**, and **Used**. | Metric | Source | What it represents | |--------|--------|-------------------| | **Requested** | Pipeline `process` directives | The CPU and memory your pipeline asked for, as written in your `process` directives (for example, `cpus = 4`, `memory = 8 GB`). | | **Allocated** | Scheduler decision | The CPU and memory the scheduler assigned to the task container. May differ from **Requested** when the scheduler picks a more cost-effective instance shape that still meets the task's requirements. | | **Used** | Nextflow trace data | The CPU and memory the task consumed, measured from the Nextflow trace metrics (`pcpu` × `realtime` for CPU, `peakRss` for memory). Absent for tasks that did not produce trace data. | **How to read the numbers:** - If **Requested** is much higher than **Allocated**, the scheduler found a more efficient instance shape than your directives implied. - If **Allocated** is much higher than **Used**, the task ran with idle headroom. - If **Used** is close to **Allocated**, resource utilization is near-optimal for that task. - If **Allocated** matches **Requested**, confirm whether Seqera Intelligent Compute has been set up with a prediction model. ## Configuration options | Option | Values | Default | Description | |--------|--------|---------|-------------| | **Seqera Intelligent Compute** | Enabled / Disabled | Disabled | Enables the Intelligent Compute scheduler for this compute environment. This option only appears if Intelligent Compute is enabled for your workspace. | | **Provisioning model** | `spotFirst`, `spot`, `ondemand` | `spotFirst` | Instance procurement strategy. `spotFirst` uses Spot instances and falls back to On-Demand if Spot capacity is unavailable. `spot` uses Spot instances only. `ondemand` uses On-Demand instances only. | | **Instance types** | Comma-separated EC2 instance type identifiers (for example, `m5.xlarge, c5.2xlarge`) | Empty | Restricts which instance types the scheduler can select. When empty, the scheduler picks the most cost-effective type for each task. | | **Prediction model** | `none`, `qr/v1`, `qr/v2` | `none` | For private preview, use `qr/v2`. | | **Backend strategy** | `ECS`, `EC2` | `ECS` | Task execution backend. Use `ECS` (default). `EC2` is reserved for future use. | | **Fusion snapshots** | Enabled / Disabled | Disabled | When enabled, interrupted tasks (for example, after a Spot reclaim) resume from a Fusion snapshot instead of restarting from scratch. | | **Use NVMe instance storage** | Enabled / Disabled | Disabled | Restrict Intelligent Compute to instance types that provide local SSD (NVMe) storage for faster I/O. | | **Enable warm pool** | Enabled / Disabled | Disabled | Keep a pool of idle VMs available to reduce task start latency. Only available when **Backend strategy** is `EC2`. | | **Desired warm VMs** | Integer | — | Target number of idle VMs to keep warm. Must be greater than zero. Only visible when **Enable warm pool** is enabled. | | **Scale-to-zero timeout** | Seconds | — | Seconds of inactivity after which the warm pool scales to zero. Set to `0` to never scale to zero. Only visible when **Enable warm pool** is enabled. | --- ## Kubernetes [Kubernetes](https://kubernetes.io/) is the leading technology for the deployment and orchestration of containerized workloads in cloud-native environments. Seqera Platform streamlines the deployment of Nextflow pipelines into Kubernetes, both for cloud-based and on-prem clusters. The following instructions create a Seqera compute environment for a **generic Kubernetes** distribution. See [Amazon EKS](./eks) or [Google Kubernetes Engine (GKE)](./gke) for EKS and GKE compute environment instructions. ## Cluster preparation To prepare your Kubernetes cluster for the deployment of Nextflow pipelines using Seqera, this guide assumes that you've already created the cluster and that you have administrative privileges. This guide applies a Kubernetes manifest that creates a service account named `tower-launcher-sa` and the associated role bindings, all contained in the `tower-nf` namespace. Seqera uses the service account to launch Nextflow pipelines. Use this service account name when setting up the compute environment for this Kubernetes cluster in Seqera. **Prepare your Kubernetes cluster for Seqera Platform** 1. Verify the connection to your Kubernetes cluster: ```bash kubectl cluster-info ``` 1. Create a file named `tower-launcher.yml` with the following YAML: ```yaml file=../_templates/k8s/tower-launcher.yml showLineNumbers ``` 1. Apply the manifest: ```bash kubectl apply -f tower-launcher.yml ``` 1. Create a persistent API token for the `tower-launcher-sa` service account: ```bash kubectl apply -f - < ``` ## Seqera compute environment After you've prepared your Kubernetes cluster for Seqera integration, create a compute environment: **Create a Seqera Kubernetes compute environment** 1. In a workspace, select **Compute environments > New environment**. 1. Enter a descriptive name for this environment, e.g., _K8s cluster_. 1. Select **Kubernetes** as the target platform. 1. From the **Credentials** drop-down, select existing Kubernetes credentials, or select **+** to add new credentials. If you choose to use existing credentials, skip to step 7. :::tip You can create multiple credentials in your Seqera workspace. See [Credentials](../credentials/overview). ::: 1. Enter a name, such as _K8s Credentials_. 1. Select either the **Service Account Token** or **X509 Client Certs** tab: - To authenticate using a Kubernetes service account, enter your **Service account token**. Obtain the token with the following command: ```bash kubectl describe secret | grep -E '^token' | cut -f2 -d':' | tr -d '\t ' ``` Replace `` with the name of the service account token created in the [cluster preparation](#cluster-preparation) instructions (default: `tower-launcher-token`). - To authenticate using an X509 client certificate, paste the contents of your certificate and key file (including the `-----BEGIN...-----` and `-----END...-----` lines) in the **Client certificate** and **Client Key** fields respectively. See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/certificates/) for instructions to generate your client certificate and key. 1. Enter the **Control plane URL**, obtained with this command: ```bash kubectl cluster-info ``` It can also be found in your `~/.kube/config` file under the `server` field corresponding to your cluster. 1. Specify the **SSL certificate** to authenticate your connection. Find the certificate data in your `~/.kube/config` file. It is the `certificate-authority-data` field corresponding to your cluster. 1. Specify the **Namespace** created in the [cluster preparation](#cluster-preparation) instructions, which is _tower-nf_ by default. 1. Specify the **Head service account** created in the [cluster preparation](#cluster-preparation) instructions, which is _tower-launcher-sa_ by default. 1. Specify the **Storage claim** created in the [cluster preparation](#cluster-preparation) instructions, which serves as a scratch filesystem for Nextflow pipelines. The storage claim is called _tower-scratch_ in each of the provided examples. 1. Apply [**Resource labels**](../resource-labels/overview) to the cloud resources consumed by this compute environment. Workspace default resource labels are prefilled. 1. Expand **Staging options** to include: - Optional [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. - Global Nextflow configuration settings for all pipeline runs launched with this compute environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden during pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: 1. Configure any advanced options described below, as needed. 1. Select **Create** to finalize the compute environment setup. See [Launch pipelines](../launch/launchpad) to start executing workflows in your Kubernetes compute environment. ### Advanced options Seqera Platform compute environments for Kubernetes include advanced options for storage and work directory paths, resource allocation, and pod customization. **Seqera Kubernetes advanced options** - The **Storage mount path** is the file system path where the Storage claim is mounted (default: `/scratch`). - The **Work directory** is the file system path used as a working directory by Nextflow pipelines. It must be the storage mount path (default) or a subdirectory of it. - The **Compute service account** is the service account used by Nextflow to submit tasks (default: the `default` account in the given namespace). - The **Pod cleanup policy** determines when to delete terminated pods. - Use **Custom head pod specs** to provide custom options for the Nextflow workflow pod (`nodeSelector`, `affinity`, etc). For example: ```yaml spec: nodeSelector: disktype: ssd ``` - Use **Custom service pod specs** to provide custom options for the compute environment pod. See above for an example. - Use **Head job CPUs** and **Head job memory** to specify the hardware resources allocated to the Nextflow workflow pod. --- ## Compute environment overview Seqera Platform **compute environments** define the execution platform where a pipeline will run. Compute environments enable users to launch pipelines on a growing number of **cloud** and **on-premises** platforms. Each compute environment must be configured to enable Seqera to submit tasks. See the individual compute environment pages below for platform-specific configuration steps. ## Platforms - [Seqera Compute](./seqera-compute) - [AWS Batch](./aws-batch) - [AWS Cloud](./aws-cloud) - [Azure Batch](./azure-batch) - [Azure Cloud](./azure-cloud) - [Google Batch](./google-cloud-batch) - [Google Cloud](./google-cloud) - [Grid Engine](./hpc) - [Altair PBS Pro](./hpc) - [IBM LSF](./hpc) - [Moab](./hpc) - [Slurm](./hpc) - [Kubernetes](./k8s) - [Amazon EKS](./eks) - [Google Kubernetes Engine](./gke) :::note Compute Environments now support descriptions. Enter a description during creation to provide context and information. To update a description, select **Edit** from the menu of the relevant compute environment. You can update descriptions at any time (e.g., to reflect a status change), up to a 1000-character limit. You can also add descriptions to existing compute environments that don't have one. ::: ## Select default compute environment If you have more than one compute environment, you can select a workspace primary compute environment to be used as the default when launching pipelines in that workspace. In a workspace, select **Compute Environments**. Then select **Make primary** from the options menu next to the compute environment you wish to use as default. ## Rename compute environment You can edit the names of compute environments in private and organization workspaces. Select **Edit** from the options menu next to the compute environment you wish to edit. Select **Update** on the edit page to save your changes after you have updated the compute environment name. ## Export compute environment You can export a compute environment's configuration as a JSON file for troubleshooting, audits, or as a reference when recreating it. :::note The exported JSON is for reference only. Re-importing it through the Seqera Platform UI is not supported. ::: Any user with the Maintain, Launch, or View role on the workspace can export. The compute environment detail page, or the form page for a specific compute environment. **What's included**: - Name, platform, region, and work directory - Forge or manual configuration block - Fusion and Wave settings - Environment variables - Pre- and post-run scripts - Labels - A reference to the credential used (the credential itself is excluded) **What's not included**: - Credentials and secrets ## Disable compute environment Users with **Admin** or **Owner** [workspace permissions](../orgs-and-teams/roles#workspace-participant-roles) can disable and enable compute environments. When you disable a compute environment: - Actions that use this compute environment will fail to run. **Update actions to use a new compute environment**. - New pipelines and Studio sessions will not run on the disabled compute environment. **Update pipelines and Studios to use a new compute environment**. - **Running pipelines and Studio sessions are not terminated**. Ongoing runs and Studio sessions will finish gracefully. - If the compute environment was set as primary, it will be unset. Until you select a new primary compute environment, new runs will default to the next available compute environment. To disable a compute environment, select **Disable** from the options menu next to the compute environment in your workspace **Compute Environments** page. To re-enable a disabled compute environment, select **Enable** from the options menu. Enabled compute environments can run new pipelines and Studio sessions. ## Delete compute environment Compute environments can be deleted when they are no longer required. You must delete the compute environment before deleting its associated credentials. If the credentials are deleted first, the compute environment deletion will fail with an error. If this happens, raise a ticket with Support. ## GPU usage The process for provisioning GPU instances in your compute environment differs for each cloud provider. ### AWS Batch The AWS Batch compute environment creation form in Seqera includes an **Enable GPUs** option. This enables you to run GPU-dependent workflows in the compute environment. Some important considerations: - Seqera only supports NVIDIA GPUs. Select instances with NVIDIA GPUs for your GPU-dependent processes. - The **Enable GPUs** setting causes Batch Forge to specify the most current [AWS-recommended GPU-optimized ECS AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html) as the EC2 fleet AMI when creating the compute environment. This setting can be overridden by **AMI ID** in the advanced options. - The **Enable GPUs** setting alone does not deploy GPU instances in your compute environment. You must still specify GPU-enabled instance types in the **Advanced options > Instance types** field. - Your Nextflow script must include [accelerator directives](https://docs.seqera.io/nextflow/process.html?highlight=accelerator#accelerator) to use the provisioned GPUs. - The NVIDIA Container Runtime uses [environment variables](https://github.com/NVIDIA/nvidia-container-runtime#environment-variables-oci-spec) in container images to specify a GPU accelerated container. These variables should be included in the [`containerOptions`](https://docs.seqera.io/nextflow/process#process-containeroptions) directive for each GPU-dependent process in your Nextflow script. The `containerOptions` directive can be set inline in your process definition or via configuration. For example, to add the directive to a process named `UseGPU` via configuration: ```groovy process { withName: UseGPU { containerOptions '-e NVIDIA_DRIVER_CAPABILITIES=compute,utility -e NVIDIA_VISIBLE_DEVICES=all' } } ``` - GPU-accelerated containers (such as NVIDIA Parabricks) bundle a specific CUDA runtime. The compute environment's AMI must include an NVIDIA driver compatible with the container's CUDA runtime. When **Enable GPUs** is set, Batch Forge selects the current AWS-recommended GPU-optimized ECS AMI. If you override **AMI ID** under **Advanced options**, confirm that the custom AMI's driver satisfies the container's CUDA version. See the [NVIDIA CUDA compatibility matrix](https://docs.nvidia.com/deploy/cuda-compatibility/) for supported driver versions. For GPU driver and CUDA compatibility errors, see [AWS troubleshooting](../troubleshooting_and_faqs/aws_troubleshooting#gpus). ### GPU metrics :::note Detailed GPU metrics are only available for tasks that run with Fusion version 2.5.10 onwards and using Nextflow version 26.03.3-edge onwards ::: When [Fusion](https://docs.seqera.io/fusion) is enabled, Seqera Platform automatically collects GPU metrics for tasks that run on NVIDIA GPU instances. No additional configuration is required beyond enabling Fusion and provisioning GPU instances in your compute environment. The following metrics are collected per task: - **GPU type**: The GPU model (e.g., NVIDIA A10G, A100). - **Driver version**: The NVIDIA driver version in use. - **GPU utilization %**: The percentage of GPU compute capacity used. - **GPU memory peak**: The maximum GPU memory used during execution. - **GPU memory average**: The average GPU memory used during execution. For tasks that use multiple GPUs, metrics are aggregated (average or peak across all GPUs assigned to the task) and displayed as a single combined value per task. #### Where GPU metrics appear - **Task detail view**: Select a GPU task in the task table to view GPU type, driver version, utilization, and memory metrics alongside existing CPU metrics. ![GPU metrics in task detail view](./_images/gpu-metrics-task.png) - **Metrics tab**: A dedicated **GPU** section displays box-and-whisker plots grouped by task name, with tabs for **GPU Utilization %**, **Memory Peak**, and **Memory Average**. This section appears only when the workflow includes tasks with GPU data. ![GPU utilization](./_images/gpu-metrics-utilization.png) ![GPU memory peak](./_images/gpu-metrics-memory-peak.png) ![GPU memory average](./_images/gpu-metrics-memory-average.png) - **Platform API**: GPU metrics are included in [task](https://docs.seqera.io/platform-api/describe-workflow-task) and [workflow](https://docs.seqera.io/platform-api/list-workflow-tasks) API responses for programmatic access. :::note GPU metrics are only available for tasks that run with Fusion enabled on NVIDIA GPU instances. Non-GPU tasks do not display a GPU metrics section. For tasks that fail mid-execution, partial metrics collected up to the point of failure are shown. ::: --- ## Compute environment pre-flight checks Pre-flight checks validate that a compute environment is usable before and at the point of pipeline launch. They run in the background on a recurring schedule and synchronously at launch time. Problems appear before pipeline submission rather than mid-run. Pre-flight checks only flag conditions that would block a pipeline launch. Pre-flight checks are enabled by default for all Cloud customers and cannot be disabled. ## What to verify before creating a compute environment Before creating or deploying a compute environment, confirm the following: **Credentials** - The access keys, service account key, or managed identity are valid and have not been rotated or revoked. - The IAM role or service account has the permissions required by the target platform. See the relevant compute environment page for the minimum required policy. **Work directory** - The bucket or storage container exists in the same region as the compute environment (required for AWS Batch and AWS Cloud compute environments only). - The credential attached to the compute environment has read and write access to the work directory path. **Wave** (if enabled) - The Wave service is running and reachable from the Platform instance. **Tower Agent** (HPC/grid compute environments only) - Tower Agent is reachable from Platform. See [Tower Agent](../supported_software/agent/overview) for installation and startup instructions. ## Validation process Platform runs three tiers of validation: ### 1. Credential validation Runs on a recurring schedule. For each cloud credential (AWS, GCP, Azure) in scope, Platform calls the provider API to verify that the credential is still accepted. For AWS role-based credentials and GCP Workload Identity Federation, this check confirms the credential is well-formed but cannot fully verify the underlying role or identity provider trust configuration. When a credential fails this check, Platform marks it **INVALID** and records the provider error on the credential record. This error appears in the launch-time error when a pipeline is blocked, but not in the compute environment banner. To see the specific provider error, check the credential record directly. ### 2. Compute environment validation Seqera checks the associated credential status. If the credential is `INVALID`, the compute environment is marked `INVALID` immediately. A compute environment marked `INVALID` displays a banner with the error message. An `AVAILABLE` compute environment has its `lastValidated` timestamp refreshed. :::note These checks cover AWS Batch, AWS Cloud, Azure Batch, Azure Cloud, Google Cloud Batch, and Google Cloud compute environments. ::: ### 3. Pipeline launch-time checks Runs immediately when a user submits a pipeline launch. If any check fails, the launch is blocked and a specific error is returned. Multiple failures are reported together. | Check | What it does | |---|---| | Compute environment status | Blocks launch if the compute environment is marked `INVALID` | | Credential status | Blocks launch if the credential associated with the compute environment is marked `INVALID` | | Wave connectivity | For compute environments with Wave enabled, verifies the Wave service connection is active | | Tower Agent | For HPC compute environments, verifies a Tower Agent is online for the environment | ## Manual credential validation When a credential is marked `INVALID` and you have rotated the keys or fixed the underlying issue, you can trigger an immediate re-validation: 1. Navigate to **Credentials** in your workspace. 2. Find the credential and select **Validate**. Platform makes a live call to the cloud provider and updates the credential status immediately. If the check passes, the credential returns to `AVAILABLE`. Compute environments marked `INVALID` because of this credential do not recover automatically. Use **Validate** on each affected compute environment after restoring the credential. ## Manual compute environment validation When a compute environment is marked `INVALID` and you have fixed the underlying issue, you can trigger an immediate re-validation without waiting for the next background sweep: 1. Navigate to **Compute environments** in your workspace. 2. Find the compute environment and open its **⋮** (three-dot) drop-down. 3. Select **Validate**. Platform runs pre-flight checks and updates the compute environment status immediately. If all checks pass, the compute environment returns to `AVAILABLE`. :::warning[Validate the credential before the compute environment] If both the credential and its associated compute environment are marked `INVALID`, you must restore the credential to `AVAILABLE` before validating the compute environment. If the credential is still `INVALID`, the compute environment will remain `INVALID` regardless. ::: ## Error reference ### Compute environment error messages These banners appear on the compute environment detail page when the compute environment is `INVALID`. | Banner | Meaning | Action | |---|---|---| | `Associated credentials are invalid or expired. Update the credentials and validate this compute environment, or contact your workspace maintainer to resolve this.` | The background sweep found the attached credential is no longer valid | Go to **Credentials**, update or rotate the credential, then use **Validate** on the compute environment | ### Launch-time errors These are returned immediately to the user when a launch is blocked. | Error | Cause | Resolution | |---|---|---| | `The selected compute environment '...' is in an invalid state` | Compute environment is marked `INVALID` (see banner for the specific reason) | Fix the root cause, then use **Validate** on the compute environment | | `The credentials '...' used by this compute environment are invalid` | Credential is marked `INVALID` | Go to **Credentials**, update or rotate the credential, then use **Validate** on the compute environment | | `Wave is required by the selected compute environment but the Wave service connection is not active. Verify that Wave is running and check for connectivity issues` | Platform cannot reach the Wave service | Contact your platform administrator. Once Wave is restored, retry the launch | | `No Tower Agent is online for the selected compute environment. Check that Tower Agent is running at your cluster.` | No Tower Agent is connected for this compute environment (HPC/grid only) | Start or restart Tower Agent on the cluster. See [Tower Agent](../supported_software/agent/overview) | ### Credential error messages When the credential sweep marks a credential `INVALID`, the provider-specific reason is stored on the credential record. It appears in the launch-time error when a pipeline is blocked, but not in the compute environment banner. To see the specific provider error, check the credential record directly. | Provider | Example message | |---|---| | AWS | `AWS credentials are invalid or expired. Update or rotate the access keys.` | | GCP | `Google credentials are invalid or expired. Update the service account key.` | | GCP Workload Identity Federation | `Google WIF credential validation failed. Verify the provider and service account configuration.` | | Azure Batch | `Azure Batch credentials are invalid. Verify the Batch account name and key.` | | Azure Storage | `Azure Storage credentials are invalid. Verify the storage account name and key.` | --- ## Seqera Compute Seqera Compute enables you to run pipelines and Studio sessions in Seqera Cloud in a fully managed and optimized AWS environment. Seqera automatically provisions and manages all the underlying resources, including AWS accounts, credentials, roles, compute environments, and S3 storage buckets, requiring minimal user configuration. Using prepaid credits enables control and visibility of the compute spend in each of your organization's workspaces. ### Manage Seqera Compute credits Seqera Compute uses prepaid credits with real-time billing. Credits are deducted as tasks complete. See [Billing and credit management](../administration/credit-management.md) for details. ### Default limits #### Compute environment limits Seqera Compute environments automatically provision cloud resources when you launch pipelines or Studios. The maximum resources that can be allocated to a Seqera Compute environment are: - 48 vCPUs - 192 GiB memory Running workflows that request resources exceeding these limits will result in errors. #### Workspace limits Seqera Compute has default workspace limits on compute environments, and organization limits on data storage and CPU cores. | | **Basic** | **Pro** | |------------------------------------|----------------------------------|------------------------------------| | Cloud storage | 25 GB | Unlimited | | Compute environments per workspace | 5 | 20 | | Total CPU cores | 100 | 1000 | :::info [Contact us](https://seqera.io/contact-us/) to discuss custom limits for Pro, academic, or evaluation licenses. ::: ### Create a Seqera Compute environment 1. In a workspace with Seqera Compute enabled, select **Compute environments > New environment**. 1. Enter a descriptive name for this environment, such as _Seqera Compute 1 (eu-west-1)_. 1. Under **Platform**, select **Seqera Compute**. 1. Select a target execution **Region**. :::info Seqera Compute is available in the following AWS regions: | Americas | Europe | Asia Pacific | Middle East & Africa | |--------------------------------------|-----------------------------------|-------------------------------------|----------------------------| | us-east-1 (Northern Virginia, USA) | eu-central-1 (Frankfurt, Germany) | ap-east-1 (Hong Kong) | af-south-1 (Cape Town, South Africa) | | us-east-2 (Ohio, USA) | eu-north-1 (Stockholm, Sweden) | ap-northeast-1 (Tokyo, Japan) | me-south-1 (Bahrain) | | us-west-1 (Northern California, USA) | eu-south-1 (Milan, Italy) | ap-northeast-2 (Seoul, South Korea) | | | us-west-2 (Oregon, USA) | eu-west-1 (Ireland) | ap-northeast-3 (Osaka, Japan) | | | ca-central-1 (Central, Canada) | eu-west-2 (London, UK) | ap-south-1 (Mumbai, India) | | | sa-east-1 (São Paulo, Brazil) | eu-west-3 (Paris, France) | ap-southeast-1 (Singapore) | | | | | ap-southeast-2 (Sydney, Australia) | | | | | ap-southeast-3 (Jakarta, Indonesia) | | ::: 1. Configure any [advanced options](#advanced-options-optional) described in the next section, as needed. 1. Select **Add** to complete the Seqera Compute environment configuration and return to the compute environments list. It will take a few seconds for the compute environment resources to be created before you are ready to launch pipelines or add studios. :::info See [Launch pipelines](../launch/launchpad) to start executing workflows in your Seqera Compute environment. ::: #### Advanced options (optional) 1. Toggle **Automatic data retention policy**. When enabled (default), intermediary files are deleted after 28 days to manage cloud storage usage and cost. 1. Enter a relative **Work directory** path to be appended to the S3 storage bucket Seqera creates for this compute environment. 1. Enter [pre- or post-run Bash scripts](../launch/advanced#pre-and-post-run-scripts) that execute before or after the Nextflow pipeline execution in your environment. 1. Enter Global Nextflow configuration settings for all pipeline runs launched with this environment. Values defined here are pre-filled in the **Nextflow config file** field in the pipeline launch form. These values can be overridden at pipeline launch. :::info Configuration settings in this field override the same values in the pipeline repository `nextflow.config` file. See [Nextflow config file](../launch/advanced#nextflow-config-file) for more information on configuration priority. ::: 1. Under **Environment variables**, add each variable with a **Name**, **Value**, and **Target Environment**: - **Head job**: Adds the variable to the Nextflow head job container, which evaluates `nextflow.config` and submits tasks to the compute backend. Use this target for variables that Nextflow or its plugins read, such as `NXF_OPTS`, `NXF_JVM_ARGS`, `NXF_PLUGINS_DEFAULT`, or proxy settings the head node uses to reach external services. - **Compute job**: Adds the variable to the worker containers that run individual pipeline tasks. Use this target for variables your pipeline tools read, such as `OPENAI_API_KEY` for a process that calls the OpenAI API, registry credentials needed inside the task container, or tool-specific settings like `JAVA_HOME`. - **Head and Compute jobs**: Adds the variable to both the head job and the compute jobs. Use this target for values needed in both places, such as an HTTP proxy used by both Nextflow and task tools, or a credential needed in both the head job and individual compute tasks. :::note For sensitive values such as API keys and tokens, use [pipeline secrets](../secrets/overview) instead of custom environment variables. Custom environment variables are stored in the compute environment configuration and cannot be edited after creation. To rotate a value, recreate the compute environment. ::: --- ## Tower Agent credentials [Tower Agent](../supported_software/agent/overview) enables Seqera Platform to launch pipelines on HPC clusters that do not allow direct access through an SSH client. Tower Agent authenticates a secure connection with Seqera using a Tower Agent credential. ## Tower Agent sharing You can share a single Tower Agent instance with all members of a workspace. Create a Tower Agent credential, with **Shared agent** enabled, in the relevant workspace. All workspace members can then use this credential (Connection ID + Seqera access token) to use the same Tower Agent instance. ## Create a Tower Agent credential 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-agent-creds`. - **Provider**: Select **Tower Agent**. - **Agent connection ID**: The connection ID used to run your Tower Agent instance. Must match the connection ID used when running the Agent (see **Usage** below). - **Shared agent**: Enables Tower Agent sharing for all workspace members. - **Usage**: Populates a code snippet for Tower Agent download with your connection ID. Replace `` with your [Seqera access token](https://docs.seqera.io/platform-api/create-token). 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## AWS ECR credentials AWS Elastic Container Registry (ECR) credentials allow the Wave container service to authenticate and pull container images from your private ECR repositories. Wave requires IAM user credentials with long-term access keys and appropriate ECR read permissions. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## AWS ECR Private Registry Wave requires programmatic access to your private Elastic Container Registry (ECR) via [long-term access keys](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#create-long-term-access-keys). Create a user with registry read permissions (e.g., a subset of the AWS-managed `AmazonEC2ContainerRegistryReadOnly` policy) for this purpose. **Create an IAM user with AWS ECR access** 1. Open the [IAM console](https://console.aws.amazon.com/iam/). 2. Select **Users** from the navigation pane. 3. Select the name of the user whose keys you want to manage, then select the **Security credentials** tab. We recommend creating an IAM user specifically for Wave authentication instead of using existing credentials with broader permissions. 4. In the **Access keys** section, select **Create access key**. Each IAM user can have only two access keys at a time, so if the Create option is deactivated, delete an existing access key first. 5. On the **Access key best practices & alternatives** page, select **Other** and then **Next**. 6. On the **Retrieve access key** page, you can either **Show** the user's secret access key details, or store them by selecting **Download .csv file**. 7. The newly created access key pair is active by default and can be stored as a container registry credential in Seqera. :::note Your credential must be stored in Seqera as a **container registry** credential, even if the same access keys already exist as a workspace credential. ::: ## Add private ECR credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your IAM user access key ID. For example, `AKIAIOSFODNN7EXAMPLE`. - **Password**: Specify your IAM user secret access key. - **Registry server**: Specify your private ECR registry URL. For example, `.dkr.ecr..amazonaws.com`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. ## AWS ECR Public Registry Amazon ECR Public Gallery (`public.ecr.aws`) hosts publicly accessible container images. While images can be pulled without authentication, AWS applies rate limits to unauthenticated pulls. Authenticating with AWS credentials removes these rate limits and is required when running pipelines at scale. ### Required IAM permissions The IAM user needs the following permissions to authenticate to ECR Public: - `ecr-public:GetAuthorizationToken` - `ecr-public:BatchCheckLayerAvailability` - `ecr-public:GetRepositoryPolicy` - `ecr-public:DescribeRepositories` - `ecr-public:DescribeImages` - `ecr-public:DescribeImageTags` - `sts:GetServiceBearerToken` Attach the AWS managed policy `AmazonElasticContainerRegistryPublicReadOnly` and add the `sts:GetServiceBearerToken` permission. This permission is not included in the managed policy and must be granted separately, or ECR Public authentication will fail. ### Add ECR Public credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `ecr-public-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your IAM user access key ID. For example, `AKIAIOSFODNN7EXAMPLE`. - **Password**: Specify your IAM user secret access key. - **Registry server**: Enter `public.ecr.aws`. 3. After you've completed all the form fields, select **Add**. Wave matches the `public.ecr.aws` hostname to these credentials and authenticates ECR Public pulls on your behalf. --- ## Azure container registry credentials Azure Container Registry credentials allow the Wave container service to authenticate and pull container images from your private Azure registries. Azure uses Role-Based Access Control (RBAC) to manage registry access. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Azure container registry access Azure container registry makes use of Azure RBAC (Role-Based Access Control) to grant users access. For more information, see [Azure container registry roles and permissions](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-roles). You must use Azure credentials with long-term registry read (**content/read**) access to authenticate Seqera to your registry. We recommend a [token with repository-scoped permissions](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-repository-scoped-permissions) that's used only by Seqera. **Create an access token with Azure container registry access** 1. In the Azure portal, navigate to your container registry. 2. Under **Repository permissions**, select **Tokens > +Add**. 3. Enter a token name. 4. Under **Scope map**, select **Create new**. 5. In the **Create scope map** section, enter a name and description for the new scope map. 6. Select your **Repository** from the drop-down. 7. Select **content/read** from the **Permissions** drop-down, then select **Add** to create the scope map. 8. In the **Create token** section, ensure the **Status** is **Enabled** (default), then select **Create**. 9. Return to **Repository permissions > Tokens** for your registry, then select the token you just created. 10. On the token details page, select **password1** or **password2**. 11. In the password details section, uncheck the **Set expiration date?** checkbox, then select **Generate**. 12. Copy and save the generated password (this is only displayed once). ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your registry token name. For example, `my-registry-token`. - **Password**: Your registry token password. For example, `my-registry-token`. - **Registry server**: Specify the container registry server name. You can obtain this from the Azure portal: **Settings > Access keys > Login server**. For example, `myregistry.azurecr.io`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## Container registry credentials Seqera Platform supports the configuration of credentials for the Wave container service to authenticate to private and public container registries. For more information about Wave, see [Wave containers](https://docs.seqera.io/wave). :::note Container registry credentials are only used by Wave containers. Enable Wave when you create a [compute environment](../compute-envs/overview) in Seqera, or add `wave { enabled=true }` to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Supported container registries Seqera supports credential configuration for the following container registries. Select a registry below for detailed instructions on how to create and configure credentials for that provider: - [AWS ECR credentials](./aws_registry_credentials.md) - [Azure container registry credentials](./azure_registry_credentials.md) - [Docker Hub credentials](./docker_hub_registry_credentials.md) - [Gitea container registry credentials](./gitea_registry_credentials.md) - [GitHub container registry credentials](./github_registry_credentials.md) - [GitLab container registry credentials](./gitlab_registry_credentials.md) - [Google registry credentials](./google_registry_credentials.md) - [Quay container registry credentials](./quay_registry_credentials.md) ## Next steps - Learn more about [Wave containers](https://docs.seqera.io/wave/provisioning). - Configure [compute environment credentials](../compute-envs/overview.md) for your pipeline infrastructure. - Set up [data repository credentials](./data_repositories.md) to access cloud storage. --- ## Data repositories Data Explorer requires programmatic access via valid credentials to browse and interact with remotely hosted private data repositories. To automatically connect to one or more data repositories, create a new credential that includes **Name** and **Provider**. Specific data repositories require additional information to connect. ## AWS Simple Storage Service (S3) object storage Add an **Access key**, and **Secret key**. You can optionally provide an IAM role for temporary access - this must be a fully qualified AWS role ARN. S3 object storage buckets are prefixed with an AWS icon and `s3://` in Data Explorer. :::note Seqera Compute uses AWS S3 object storage, and are prefixed with a Seqera icon and the `s3://` namespace in Data Explorer. ::: ## Azure Blob Storage Select between different credential types: a **Shared key**, **Entra**, or **Cloud**. - **Shared key:** Access your Azure accounts directly using primary or secondary access keys. - **Entra:** Authenticate via an Azure Entra service principal for enhanced security and identity management. - **Cloud:** Authenticate via an Azure Entra service principal for Azure Cloud. :::info Select Shared key for full administrator access via long-lived keys, choose Entra for access through an Entra service principal, or opt for Cloud to access via an Entra service principal with compatibility to the single VM compute type but not Azure Batch. ::: Add a **Batch account name**, **Batch account key**, **Blob Storage account name**, and **Blob Storage account key**. Azure Blob Storage are prefixed with an Azure icon and `az://` in Data Explorer. ## GCP object storage Add the contents of the **Service account key** JSON file. GCP object storage buckets are prefixed with a GCP icon and `gs://` in Data Explorer. ## S3-compatible storage This includes cloud-provider and on-premise based storage solutions with an S3-compatible API. Examples include [Cloudflare R2][cloudflare], [MinIO][minio], and [Oracle Cloud Infrastructure][oci]. Add an **Access key**, **Secret key**, **Server base URL**, and optionally select path-style URL access. Refer to your S3-compatible storage provider documentation to determine if path-style URL access is applicable. :::info OCI has specific object-storage endpoints that are [S3-compatible][oci-s3-compatible], and include `.compat.` in the server base URL. These are in the form `https://.compat.objectstorage..oci.customer-oci.com`. ::: S3-compatible storage are prefixed with a S3-compatible storage icon and `s3://` in Data Explorer. {/* Links */} [cloudflare]: https://www.cloudflare.com/developer-platform/products/r2/ [minio]: https://min.io [oci]: https://www.oracle.com/cloud/ [oci-s3-compatible]: https://docs.oracle.com/en-us/iaas/api/#/en/s3objectstorage --- ## Docker Hub credentials Docker Hub credentials allow the Wave container service to authenticate and pull container images from your Docker Hub repositories. Docker Hub uses personal access tokens (PATs) with read-only permissions for secure programmatic access. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Docker Hub registry access You must use Docker Hub credentials with **Read-only** access to authenticate Seqera to your registry. Docker Hub uses personal access tokens (PATs) for authentication. We don't currently support Docker Hub authentication with 2FA (two-factor authentication). **Create a Docker Hub PAT** 1. Log in to [Docker Hub](https://hub.docker.com/). 2. Select your username in the top right corner and select **Account Settings**. 3. Select **Security > New Access Token**. 4. Enter a token description and select **Read-only** from the Access permissions drop-down, then select **Generate**. 5. Copy and save the generated access token (this is only displayed once). ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your Docker username. For example, `user1`. - **Password**: Specify your personal access token (PAT). For example, `1fcd02dc-...215bc3f3`. - **Registry server**: Specify the container registry hostname, excluding the protocol. For example, `docker.io`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## Gitea container registry credentials Gitea Container Registry credentials allow the Wave container service to authenticate and pull container images from your Gitea repositories. Gitea registries support [authentication][gitea-auth] using personal access tokens for programmatic access. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Create a personal access token (PAT) You must create a PAT to access your Gitea container registry from Wave. For more information, see [Create a personal access token][gitea-create]. ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your Gitea username. For example, `gitlab_user1`. - **Password**: Specify your Gitea personal access token (PAT). For example, `1fcd02dc-...215bc3f3`. - **Registry server**: Specify your Gitea container registry URL. For example, `gitea.example.com`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. [gitea-auth]: https://docs.gitea.com/usage/packages/container#login-to-the-container-registry [gitea-create]: https://docs.gitea.com/development/api-usage#authentication --- ## GitHub container registry credentials GitHub Container Registry credentials allow the Wave container service to authenticate and pull container images from GitHub Packages. GitHub Packages only supports [authentication][github-pat] using a personal access token (classic) for programmatic access. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Create a personal access token (PAT) You must create a PAT to access your GitHub container registry from Wave. For more information, see [Create a personal access token][github-create]. ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your GitHub username. For example, `github_user1`. - **Password**: Specify your personal access token (PAT) classic. For example, `1fcd02dc-...215bc3f3`. - **Registry server**: Specify your GitHub container registry URL. For example, `ghcr.io`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. [github-pat]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic [github-create]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic --- ## GitLab container registry credentials GitLab Container Registry credentials allow the Wave container service to authenticate and pull container images from your GitLab repositories. If your organization has enabled two-factor authentication (2FA), you must use a [personal access token][gitlab-pat] for [GitLab container registry authentication][gitlab-cr]. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Create a personal access token (PAT) If your organization enabled 2FA for your organization or project, you must create a PAT to access your GitLab container registry from Wave. For more information, see [Create a personal access token][gitlab-create]. If your organization created a [project access token][gitlab-project] or a [group access token][gitlab-group], ask your GitLab administrator for access. ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your GitLab username. - **Password**: Specify your personal access token (PAT), group access token, or project access token if 2FA is enabled by your GitLab organization. Otherwise specify your GitLab password. - **Registry server**: Specify your GitLab container registry URL. For example, `gitlab.example.com`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. [gitlab-cr]: https://docs.gitlab.com/ee/user/packages/container_registry/authenticate_with_container_registry.html [gitlab-pat]: https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html [gitlab-create]: https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token [gitlab-project]: https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html [gitlab-group]: https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html --- ## Google registry credentials Google Cloud registry credentials allow the Wave container service to authenticate and pull container images from Google Artifact Registry. Google Cloud registries require programmatic access using service account keys with appropriate read permissions. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: ## Google Cloud registry access :::note Although Google Cloud Container Registry is still available and supported as a [Google Enterprise API](https://cloud.google.com/blog/topics/inside-google-cloud/new-api-stability-tenets-govern-google-enterprise-apis), new features will only be available in Artifact Registry. Container Registry will only receive critical security fixes. Google recommends using Artifact Registry for all new registries moving forward. ::: Google Cloud Artifact Registry and Container Registry are fully integrated with Google Cloud services and support various authentication methods. Seqera requires programmatic access to your private registry using [long-lived service account keys](https://cloud.google.com/artifact-registry/docs/docker/authentication#json-key) in JSON format. Create dedicated service account keys that are only used to interact with your repositories. Seqera requires the [Artifact Registry Reader](https://cloud.google.com/artifact-registry/docs/access-control#permissions) or [Storage Object Viewer](https://cloud.google.com/container-registry/docs/access-control#permissions) role. ## Create a Google service account with registry access **Google Cloud Artifact Registry** Administrators can create a service account from the Google Cloud console: 1. Go to the [Create service account](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create?walkthrough_id=iam--create-service-account) page. 2. Select a Cloud project. 3. Enter a service account name and (optional) description. 4. Select **Create and continue**. 5. From the **Role** drop-down under step 2, select **Artifact Registry > Artifact Registry Reader**, then select **Continue**. 6. (Optional) Grant other users and admins access to this service account. 7. Select **Done**. 8. From the project service accounts page, select the three dots menu icon under **Actions** for the service account you just created, then select **Manage keys**. 9. On the **Keys** page, select **Add key**. 10. On the **Create private key** popup, select **JSON** and then **Create**. This triggers a download of a JSON file containing the service account private key and service account details. 11. Base-64 encode the contents of the JSON key file: ```bash #Linux base64 KEY-FILE-NAME > NEW-KEY-FILE-NAME #macOS base64 -i KEY-FILE-NAME -o NEW-KEY-FILE-NAME #Windows Base64.exe -e KEY-FILE-NAME > NEW-KEY-FILE-NAME ``` **Google Cloud Container Registry** Administrators can create a service account from the Google Cloud console: 1. Navigate to the [Create service account](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create?walkthrough_id=iam--create-service-account) page. 2. Select a Cloud project. 3. Enter a service account name and an optional description. 4. Select **Create and continue**. 5. From the **Role** drop-down under step 2, search for and select **Storage Object Viewer**, then select **Continue**. 6. (Optional) Grant other users and admins access to this service account under step 3. 7. Select **Done**. 8. From the project service accounts page, select the three dots menu icon under **Actions** for the service account you just created, then select **Manage keys**. 9. On the **Keys** page, select **Add key**. 10. On the **Create private key** popup, select **JSON** and then **Create**. This triggers a download of a JSON file containing the service account private key and service account details. ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify the service account key type: - Container registry: `_json_key` - Artifact Registry: `_json_key_base64` - **Password**: Specify the JSON key file content. This content is base64-encoded for Artifact Registry. You must remove any line breaks or trailing spaces. For example, `wewogICJ02...9tIgp9Cg==`. - **Registry server**: Specify the container registry hostname, excluding the protocol. For example, `-docker.pkg.dev`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## Managed identities Managed identities offer significant advantages for high performance computing (HPC) environments by enabling granular access control for individual workspace users. Unlike traditional SSH credentials that grant all workspace users access to HPC clusters using the same set of credentials, managed identities ensure each user’s activity is logged under their own credentials. This preservation of user identity is crucial as it naturally inherits the HPC system's fair usage queue policies, mitigates the noisy neighbor problem, and reduces the long wait times associated with First-In-First-Out (FIFO) queues common with shared SSH credentials. Traditional SSH credentials, while simplifying access control to computing resources, result in all user activities on the HPC cluster being logged under the same user credentials. This means all Seqera workspace users have the same access permissions on your HPC cluster, leading to indistinguishable user activities. Managed identities resolve these limitations by allowing administrators to configure a managed identity at the organizational level for access to supported HPC compute environments. This managed identity is selected for authentication similarly to traditional credentials, but contains multiple user credentials each tied to a unique Seqera user. This setup preserves the identity of the user launching workflows on the compute environment and improves traceability and adherence to data access policies. Moreover, with managed identities, users only have the access permissions that their system administrators have granted, minimizing the risk of unauthorized read/write operations in restricted folders. In contrast, shared SSH credentials provide all workspace users with the same access level on the HPC side, which is often more extensive than what an individual user typically needs. By grouping individual user SSH credentials into a single element, managed identities allow administrators to streamline user login and compute environment access while maintaining visibility into data access and compute resource usage for each user. ## Create a managed identity Organization owners can create managed identities at the organization level. A managed identity with user credentials can be used as a credential in HPC clusters for the same provider. 1. From your organization page, select the **Managed identities** tab, then **Add managed identity**. 1. Enter the details of your cluster: - A unique **Cluster name** of your choice using alphanumeric, dash, and underscore characters. - Select a cluster **Provider** from the drop-down. - The fully qualified cluster **Hostname** to be used to connect to the cluster via SSH. This is usually the cluster login node. - The SSH **Port** number for the login connection. The default is port 22. 1. Select **Add cluster**. The new cluster is now listed under your organization's managed identities. Select **Edit** next to a managed identity in the list to edit its details and add user credentials. :::note If the managed identity is already in use on a compute environment, editing its details may lead to errors when using the compute environment. ::: ## Add user credentials Organization owners can grant individual users access to managed identities by adding each user's credentials to the managed identity. You must add user credentials to a managed identity before it can be used in a compute environment. Organization members can add, edit, and delete their own user credentials in a managed identity. :::caution All managed identity users must be a part of the same Linux user group. The group must have access to the HPC compute environment work directory. Set group permissions for the work directory as follows (replace `sharedgroupname` and `` with your group name and work directory): ```bash chgrp -R sharedgroupname chmod -R g+wxs setfacl -Rdm g::rwX ``` These commands change the group ownership of all files and directories in the work directory to `sharedgroupname`, ensure new files inherit the directory's group, and apply default ACL entries to allow the group read, write, and execute permissions for new files and directories. This setup facilitates shared access and consistent permissions management in the directory. ::: 1. From the **Managed identities** tab, select **Edit** next to the cluster in question, then select the **Users** tab. 1. The members of the organization are prepopulated in the **Users** list. Users without credentials are listed with a **Missing** credentials status. Add a user's credentials by selecting **Add credentials** from the user action menu, or the **Add credentials** button. 1. Enter the credential details in the **Add credentials** window: - The member's **Linux username** used to access the cluster. - Paste the contents of the **SSH private key** file for the user's SSH key pair, including the `-----BEGIN OPENSSH PRIVATE KEY-----` and `-----END OPENSSH PRIVATE KEY-----` lines. Ensure no additional lines or spaces are included. - The SSH private key **Passphrase**, if the key has a passphrase. Otherwise, leave this blank. 1. Select **Add credentials**. The Linux username for the user is now populated in the list, and the **Credentials** status is changed to **Added**. Edit existing user credentials by selecting **Edit credentials** from the **Actions** menu next to a user name in the list. --- ## Credentials overview Seqera Platform supports secure credential management for all your infrastructure and service integrations. Configure credentials to authenticate with: - [Git hosting services][git]: Access private repositories from GitHub, GitLab, Bitbucket, and other Git providers. - [Container registries][registry]: Authenticate the Wave container service with private registries like Docker Hub, AWS ECR, Azure Container Registry, and Google Artifact Registry. - [Data repositories][data]: Connect to cloud storage services like AWS S3, Azure Blob Storage, and Google Cloud Storage. - [Managed identities][managed]: Use cloud provider managed identities for secure, credential-free authentication. - [SSH credentials][ssh]: Connect to HPC and on-premises compute environments. - [Agent credentials][agent]: Authenticate Seqera Agents for hybrid and on-premises deployments. :::note Seqera Platform encrypts all credentials with AES-256 encryption before storing them. No Seqera API exposes credentials in an unencrypted way. ::: [git]: ../git/overview [registry]: ./container_registry_credentials [data]: ./data_repositories [managed]: ./managed_identities [ssh]: ./ssh_credentials [agent]: ./agent_credentials --- ## Quay container registry credentials Quay container registry credentials allow the Wave container service to authenticate and pull container images from your Quay repositories. Quay uses [robot accounts](https://docs.quay.io/glossary/robot-accounts.html) with read access permissions for secure programmatic authentication. :::note Container registry credentials are only used by the Wave container service. Add `wave { enabled=true }` to the **Nextflow config** field on the launch page, or to your `nextflow.config` file, for your pipeline execution to use Wave containers. ::: **Create a Quay robot account** 1. Sign in to [quay.io](https://quay.io/). 2. From the user or organization view, select the **Robot Accounts** tab. 3. Select **Create Robot Account**. 4. Enter a robot account name. The username for robot accounts have the format `namespace+accountname`, where `namespace` is the user or organization name and `accountname` is your chosen robot account name. 5. Grant the robot account repository **Read** permissions from **Settings > User and Robot Permissions** in the repository view. 6. Select the robot account in your admin panel to retrieve the token value. ## Add credentials to Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: Specify a unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-registry-creds`. - **Provider**: Select **Container registry**. - **User name**: Specify your robot account username. For example, `namespace+accountname`. - **Password**: Specify your robot account access token. For example, `PasswordFromQuayAdminPanel`. - **Registry server**: Specify your container registry hostname. For example, `quay.io`. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## SSH credentials SSH public key authentication relies on asymmetric cryptography to generate a public and private key pair. The public key remains on the target (remote) machine, while the private key (and passphrase) is stored in Seqera Platform as a credential. The key pair is used to authenticate a connection with your SSH-enabled environment. To preserve individual user identities by using multiple user SSH credentials to access your HPC compute environments, see [Managed identities](./managed_identities). :::note All credentials are (AES-256) encrypted before secure storage and not exposed in an unencrypted way by any Seqera API. ::: ## Create an SSH key pair To use SSH public key authentication: - The remote system must have a version of SSH installed. This guide assumes the remote system uses OpenSSH. If you're using a different version of SSH, the key generation steps may differ. - The SSH public key must be present on the remote system (usually in `~/.ssh/authorized_keys`). To generate an SSH key pair: 1. From the target machine, open a terminal window and run `ssh-keygen`. 2. Follow the prompts to: - Specify a file path and name (or keep the default). - Specify a passphrase (recommended). 3. Navigate to the target folder (default `/home/user/.ssh/id_rsa`) and open the private key file with a plain text editor. 4. Copy the private key file contents before navigating to Seqera. ## Create an SSH credential in Seqera 1. Add your credentials to your organization or personal workspace: - From an organization workspace: Go to **Credentials > Add Credentials**. - From your personal workspace: From the user menu, go to **Your credentials > Add credentials**. 2. Complete the following fields: - **Name**: A unique name for the credentials using alphanumeric characters, dashes, or underscores. For example, `my-ssh-creds`. - **Provider**: Select **SSH**. - **SSH private key**: Paste the SSH private key file contents. Include the `-----BEGIN OPENSSH PRIVATE KEY-----` and `-----END OPENSSH PRIVATE KEY-----` lines. - **Passphrase**: The SSH private key passphrase (recommended). If your key pair was created without a passphrase, leave this blank. 3. After you've completed all the form fields, select **Add**. The new credential is now listed under the **Credentials** tab. --- ## Data Explorer With Data Explorer, you can browse and interact with remote data repositories from organization workspaces in Seqera Platform. It supports AWS S3, Azure Blob Storage, Google Cloud Storage, and Amazon S3-compatible API storage (for example, Cloudflare R2, MinIO, Nebius, and Oracle Cloud). Access the **Data Explorer** tab from any workspace to view and manage all available data repositories. Data Explorer is also integrated with the pipeline launch form, run detail pages, and Studios. Use these integrations to select input data files and output directories, view the output files of a run, or use files in object storage directly for interactive analysis. If you use Seqera Cloud and want to disable Data Explorer, [contact](https://seqera.io/contact-us/) your Seqera account executive. ## Participant roles The role assigned to a workspace user affects what functionality is available in Data Explorer. These permissions are listed in the [Participant roles][roles]. ## Access control Two mechanisms control Data Explorer access: - **Participant roles** determine which Data Explorer actions a workspace user can perform, such as browsing, previewing, downloading, and uploading. See [Participant roles][roles]. - **Credentials** determine which objects those actions can reach. Each data-link uses the credentials you select when you add the data repository to the workspace. The cloud provider permissions attached to those credentials define the scope of Data Explorer access to that repository. To narrow what Data Explorer can do in a bucket, assign that data-link a dedicated credential with a more restrictive cloud provider policy. Sharing one broad credential across compute environments and data repositories gives Data Explorer the full scope of that credential. Data Explorer has no per-bucket or per-workspace setting that disables downloads or uploads while leaving browsing available. To remove download and upload access completely, disable Data Explorer for your entire Seqera Cloud account. :::warning Cross-origin resource sharing (CORS) is not an access-control mechanism. Browsers enforce CORS, and it covers only the upload, multi-file download, and genome preview paths described in [CORS configurations for cloud providers](#cors-configurations-for-cloud-providers). Leaving a bucket's CORS configuration unset does not prevent Data Explorer users from reaching the objects in that bucket. CORS has no effect on access through the Seqera Platform API, the Seqera Platform CLI (`tw`), or your cloud provider's tools. Use credentials and cloud provider access policies to control access to your data. ::: ## Add data repository links Data Explorer lists public and private data repositories. Repositories accessible to your workspace credentials are retrieved automatically. Workspace maintainers can also configure repositories manually. - **Retrieve data repositories with workspace credentials** Private data repositories accessible to the credentials defined in your workspace are listed in Data Explorer automatically. The permissions required for your [AWS](../compute-envs/aws-batch#required-platform-iam-permissions), [Google Cloud](../compute-envs/google-cloud-batch#iam), [Azure Batch](../compute-envs/azure-batch#storage-account), or Amazon S3-compatible API storage credentials allow full Data Explorer functionality. For AWS S3, Data Explorer requires the following minimum IAM permissions: - `s3:ListAllMyBuckets` (on `*`) to auto-discover the buckets accessible to your workspace credentials. - `s3:ListBucket`, `s3:GetBucketLocation`, `s3:GetBucketPolicy`, and `s3:GetBucketAcl` on each bucket you want to browse, to resolve its region and access configuration. - `s3:GetObject` and `s3:PutObject` on the objects in each bucket, to download and upload files. These are a subset of the S3 permissions documented for the [AWS Batch](../compute-envs/aws-batch#required-platform-iam-permissions), [AWS Cloud](../compute-envs/aws-cloud#required-platform-iam-permissions), and [Amazon EKS](../compute-envs/eks#required-platform-iam-permissions) compute environments. For Azure Blob Storage, see the [Azure Cloud data-links permissions](../compute-envs/azure-cloud#data-links). - **Configure individual data repositories manually** Select **Add data repository** from the Data Explorer tab to add a link to an individual repository (or prefix within a cloud bucket). Specify the **Provider**, **Path**, **Name**, **Credentials**, and **Description**, then select **Add**. For public cloud buckets, select **Public** from the **Credentials** drop-down. ## Remove data repository links A workspace maintainer can remove a manually created data-link to a repository. From the **Data Explorer** tab, find the data repository that you want to remove. Select the options menu for the repository, and select **Remove**. When prompted, select **Remove** from the confirmation modal that appears. If you remove a data-link associated with a repository, the repository is automatically removed from the relevant Studio configuration. ## Browse data repositories ![](./_images/data_explorer.png) - **View data repository details** To view details such as the cloud provider, address, and credentials, select the information icon next to a data-link in the Data Explorer list. - **Search and filter data repositories** Search for repositories by name and region (for example, `region:eu-west-2`) in the search field, and filter by provider. - **Hide data repositories from list view** Using checkboxes, choose one or more data repositories, then select the **Hide** icon in the Data Explorer toolbar. To hide repositories individually, select **Hide** from the three dots options menu of a repository in the list. The Data Explorer list filter defaults to **Only visible**. Select **Only hidden** or **All** from the filtering menu to view hidden data repositories in the list. You can unhide a data repository by selecting **Show** from the three dots options menu in the list view. - **View data repository contents** Select a data-link from the Data Explorer list to view the contents of that data repository. From the **View data repository** page, you can browse directories and search for objects by name in a particular directory. The size and path of an object appear in columns to the right of the object name. To view data repository details such as the provider, address, and credentials, select the information icon. - **Preview and download files** From the **View data repository** page, you can preview and download files. Select the download icon in the **Actions** column to download a file directly from the list view. Select a file to open a preview window that includes a **Download** button. File preview is supported for these object types: - Nextflow output files (`.command.*`, `.fusion.*`, and `.exitcode`) - Molecular data using the [Mol* library][molstar] - Genome tracks using the [igv.js library][igv] (annotations, wigs, alignments, and variants) - Text - CSV and TSV - PDF - HTML - Images (JPG, PNG, and SVG) :::note With the exception of genome tracks, the preview file size limit is 10 MB. Files of 10-25 MB can still be downloaded directly. Seqera Enterprise users can increase the default 25 MB file size download limit with `tower.content.max-file-size` in the `tower.yml` [configuration](https://docs.seqera.io/platform-enterprise/enterprise/configuration/overview#data-features) file. Increasing this value can degrade Platform performance. ::: - **Copy object paths** Select the **Path** of an object on the **View data repository** page to copy its absolute path to the clipboard. Use these object paths to specify input data locations during [pipeline launch](../launch/launchpad), add them to a [dataset](../data/datasets) for pipeline input, or when mounting data during Studio creation. ### View lineage data for objects :::note Data lineage is available on request. Contact your Seqera account manager. ::: When an object in Data Explorer was produced by a Nextflow run with [data lineage tracking enabled][workspace-lineage-settings], the object preview displays the object's lineage data alongside its file metadata. Select an object to preview. When lineage data is available, this displays: | Field | Source | Description | |-------|--------|-------------| | **Lineage Labels** | `labels` | Lineage labels assigned to the output. Each label is a clickable link to the lineage record for that label. See the Nextflow [`label` directive][nextflow-label-directive] for assignment details. | | **Produced by** | `pipeline-run` | Workflow run ID that created this object. Select the run ID to navigate to the workflow run. | | **Source for** | `pipeline-run` | Workflow run ID that used this file as an input. Select the run ID to navigate to the workflow run. | If the object was not produced by a lineage-enabled run, no lineage fields appear in the preview. :::tip Each lineage ID, lineage label, produced by, and source for in the preview is a navigable link. Use these links to retrace the run, task, inputs that produced an object, or outputs created by the object without leaving Seqera Platform. To capture lineage data, lineage must be enabled for the run that produced the object. Enable lineage from [**Workspace settings → Lineage**][workspace-lineage-settings] or the launch form lineage toggle. See [Getting started with data lineage][nextflow-lineage-tutorial] for the underlying lineage data model. ::: ## Isolate view, read, and write permissions to specific data repository paths To isolate pipeline or Studios view, read, and write permissions to a specific **data repository path**, workspace maintainers can create **custom data-links** by manually configuring an individual data repository plus path to a specific folder/directory. This is supported to any level of the data repository path hierarchy, provided it is a folder (also known as a **prefix**). You can **Hide** or **Show** either the base data repository or any related custom data-links on demand in Data Explorer using the **Show/Hide** toggle and the **Show data repositories** filter options: - Only visible (default) - Only hidden - All :::note This customized Data Explorer view displays by default for all workspace users until a workspace maintainer updates or removes the filter. ::: ## Upload files to private data repositories Data Explorer supports single or bulk file uploads to your private data repositories. From the **View data repositories** page, select **Upload** and choose either the **Upload files** or **Upload folder** option. You can also drag and drop files and folders directly into Data Explorer. You can upload up to 300 files at a time via the Platform interface. The file size upload limits reflect the size limitations of the relevant cloud storage provider or data repository integration. These limits apply to cloud providers: - [AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html) - Single `PUT` upload: 5 GiB - Multi-part upload: 5 TiB - [Azure](https://learn.microsoft.com/en-us/rest/api/storageservices/put-blob?tabs=microsoft-entra-id#remarks) - Single `PUT` upload: 5 GiB - Multi-part upload: 4.77 TiB - [Cloudflare R2](https://developers.cloudflare.com/r2/platform/limits/) - Single `PUT` upload: 4.995 GiB - Multi-part upload: 50 TiB - [GCP](https://cloud.google.com/storage/quotas#objects): - Single `PUT` upload: 5 TiB - Multi-part upload: 5 TiB - [MinIO](https://docs.min.io/enterprise/aistor-object-store/reference/aistor-server/thresholds/) - Single `PUT` upload: 5 TiB - Multi-part upload: 50 TiB - [Oracle Cloud](https://docs.oracle.com/en-us/iaas/Content/Object/Tasks/managingobjects_topic-To_upload_objects_to_a_bucket.htm) - Single `PUT` upload: 64 MiB - Multi-part upload: 50 GiB To cancel an upload, select **X** in the upload window. Any files not uploaded display as **Failed**. Files that uploaded successfully are not removed. :::note You must configure cross-origin resource sharing (CORS) for your data repository provider to allow file uploads from Platform. CORS configuration differs for each provider. ::: ## Download multiple files You can download up to 1,000 files using the browser interface, or an unlimited number of files with the auto-generated download script that uses your data repository provider's CLI and credentials. :::note If you use a non-Chromium based browser, such as Safari or Firefox, file paths are concatenated with an underscore (`_`) character and the data repository directory structure is not reproduced locally. For example, the file `s3://example-us-east-1/path/to/files/my-file-1.txt` is saved as `path_to_files_my-file-1.txt`. ::: Open the data repository and navigate to the folder that you want to download files and folders from. By default, you can download the contents of the current directory by choosing **Download current directory**. Alternatively, use checkboxes to select specific files and folders, and select the **Download** button. You can **Download files** via the browser or **Download using code**. The code snippet is specific to the data repository provider you configured. Only the three major cloud providers are supported. You may be prompted to authenticate during the download process. Refer to your data repository provider's documentation for troubleshooting credential-related issues: - [AWS](https://docs.aws.amazon.com/cli/latest/reference/s3/) - [Azure](https://learn.microsoft.com/en-us/cli/azure/storage?view=azure-cli-latest) - [GCP](https://cloud.google.com/sdk/gcloud/reference/storage) ## CORS configurations for cloud providers Each cloud provider has a specific way to allow Cross-Origin Resource Sharing (CORS) for uploads, multi-file downloads, and genome file previews (IGV). CORS enables these browser-based paths, but it is not an access-control mechanism. See [Access control](#access-control) for the mechanisms that restrict access to your data. ### Amazon S3 CORS configuration Apply a [CORS configuration](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html) to enable file uploads, folder downloads, and genome file previews (IGV) from the Seqera Platform to and from specific S3 buckets. The CORS configuration is a JSON file that defines the origins, headers, and methods allowed for resource sharing requests to a bucket. Follow [these AWS instructions](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html) to apply the CORS configuration below to each bucket you wish to enable file uploads, folder downloads, and genome file previews for: **Seqera Cloud S3 CORS configuration** ```json [ { "AllowedHeaders": ["*"], "AllowedMethods": ["PUT", "POST", "DELETE", "GET"], "AllowedOrigins": ["https://cloud.seqera.io"], "ExposeHeaders": ["ETag"] } ] ``` **Seqera Enterprise S3 CORS configuration** Replace `` with your Seqera Enterprise server URL: ```json [ { "AllowedHeaders": ["*"], "AllowedMethods": ["PUT", "POST", "DELETE", "GET"], "AllowedOrigins": ["https://"], "ExposeHeaders": ["ETag"] } ] ``` ### Azure Blob Storage CORS configuration :::note CORS configuration in Azure Blob Storage is set at the account level. This means that CORS rules for your account apply to every blob in the account. ::: Apply a [CORS configuration](https://learn.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services#enabling-cors-for-azure-storage) to enable file uploads, folder downloads, and genome file previews (IGV) from the Seqera Platform to and from your Azure Blob Storage account. **Seqera Cloud Azure CORS configuration** 1. From the [Azure portal](https://portal.azure.com), go to the **Storage account** you want to configure. 2. Under **Settings** in the left navigation menu, select **Resource sharing (CORS)**. 3. Add a new entry under **Blob service**: - **Allowed origins**: `https://cloud.seqera.io` - **Allowed methods**: `GET,POST,PUT,DELETE,HEAD` - **Allowed headers**: `x-ms-blob-type,content-type` - **Exposed headers**: `x-ms-blob-type` 4. Select **Save** to apply the CORS configuration. **Seqera Enterprise Azure CORS configuration** 1. From the [Azure portal](https://portal.azure.com), go to the Storage account you want to configure. 2. Under **Settings** in the left navigation menu, select **Resource sharing (CORS)**. 3. Add a new entry under **Blob service**: - **Allowed origins**: `https://` - **Allowed methods**: `GET,POST,PUT,DELETE,HEAD` - **Allowed headers**: `x-ms-blob-type,content-type` - **Exposed headers**: `x-ms-blob-type` 4. Select **Save** to apply the CORS configuration. ### Google Cloud Storage CORS configuration Apply a [CORS configuration](https://cloud.google.com/storage/docs/cross-origin#cors-components) to enable file uploads, folder downloads, and genome file previews (IGV) from Seqera to specific GCS buckets. The CORS configuration is a JSON file that defines the origins, headers, and methods allowed for resource sharing requests to a bucket. Follow [these Google instructions](https://cloud.google.com/storage/docs/using-cors#command-line) to apply the CORS configuration below to each bucket you wish to enable file uploads, folder downloads, and genome file previews for. :::note Google Cloud Storage only supports CORS configuration via gcloud CLI. ::: **Seqera Cloud GCS CORS configuration** ```json { "origin": ["https://cloud.seqera.io"], "method": ["GET", "POST", "PUT", "DELETE", "HEAD"], "responseHeader": ["Content-Type", "Content-Range"], "maxAgeSeconds": 3600 } ``` **Seqera Enterprise GCS CORS configuration** ```json { "origin": ["https://"], "method": ["GET", "POST", "PUT", "DELETE", "HEAD"], "responseHeader": ["Content-Type", "Content-Range"], "maxAgeSeconds": 3600 } ``` ## Limitations Using remote data repositories as inputs for pipelines or Studios requires the same credentials as the underlying Seqera Platform compute environment. You **cannot** use data from S3-compatible object storage providers (for example, MinIO and Nebius) as inputs for pipelines or Studios, because they do not offer configurable compute environments. :::note Multi-credential support for compute environments and Fusion is under active development and will resolve this limitation. ::: {/* links */} [roles]: ../orgs-and-teams/roles [molstar]: https://molstar.org/ [igv]: https://igv.org/doc/igvjs/ [nextflow-lineage-tutorial]: https://docs.seqera.io/nextflow/tutorials/data-lineage [nextflow-label-directive]: https://docs.seqera.io/nextflow/reference/process#label [workspace-lineage-settings]: ../orgs-and-teams/workspace-management#lineage --- ## Data lineage :::info Data lineage in Platform is in public preview. It requires Nextflow 25.04 or later, AWS S3 object storage, and Amazon Simple Queue Service (SQS). For best results, use Nextflow 26.04 or later. ::: :::warning The feature is experimental and subject to change. This page provides the latest configuration recommendations and limitations. ::: Data lineage tracks the full provenance of every pipeline run at both the task and workflow level, including what executed, what data it consumed, and what outputs it produced. Use it to audit results, verify reproducibility, and trace file provenance. ## Why use data lineage Production pipelines generate results that teams need to trust, audit, and reproduce. Data lineage provides a precise, immutable record of how each result was produced. - **Reproducibility**: Every run, task, and output file receives a unique lineage ID (LID), a traversable URI that points to a structured record of what ran. Verify that two runs produced identical results, or identify where they diverged. - **Auditing and compliance**: For teams in regulated industries such as pharma, clinical genomics, and contract research organizations (CROs), lineage provides the audit trail needed for regulatory compliance. Each record captures inputs, outputs, parameters, compute environment, and the user who launched the run. - **Debugging**: When a cached task unexpectedly re-executes, or a pipeline produces an unexpected result, lineage traces backward from any output to all contributing tasks and parameters. Compare two task runs to isolate what changed. - **Broader team access**: Exploring Nextflow lineage previously required CLI access and comfort reading raw JSON. Platform now surfaces lineage data in pipeline run detail pages and Data Explorer. Users can inspect provenance directly. - **Cross-workflow discoverability**: [Workflow output labels][workflow-labels] make output files discoverable across runs. Navigate lineage records by label to find all matching outputs workspace-wide, without knowing which specific run produced a file. ## How data lineage works When lineage is enabled, Nextflow generates a structured JSON record for each entity in your pipeline during workflow execution: | Record type | Description | |---|---| | **WorkflowRun** | Full pipeline execution: repository, commit ID, parameters, compute environment, session ID, and Platform context (user, workspace, pipeline) | | **TaskRun** | Individual task execution: script, code checksum, inputs, outputs, container, and dependencies | | **FileOutput** | Output file: path, checksum, size, timestamp, and links back to the task and workflow that produced it | Each record gets a lineage ID (LID), a `lid://` URI that uniquely identifies the entity. Every LID and lineage label renders as a clickable link, and you can navigate to all related entities across your organization. ### Functional flow 1. Nextflow appends lineage record objects (`*.data.json`) to the defined object storage bucket. 1. The bucket is configured to filter for objects matching `.data.json` and sends object store notifications to the queue. 1. SQS queue receives `s3:ObjectCreated:*` events. 1. Platform reads the queue, returning the lineage objects created, and indexes them in the database. 1. The index enriches the [run details][run-details]. 1. The index enriches the display of workflow-generated objects in Data Explorer with links to the origin pipeline run and task, sources of the object, and any lineage labels associated with the object. ## Enable data lineage To start collecting data lineage for all pipeline runs in your workspace: 1. Open **Settings > Workspace settings**. 2. Select **Lineage**. If you don't see **Lineage** listed, contact your system administrator. 3. Toggle the **Enable lineage by default** on to collect data lineage for all pipeline runs in the workspace or toggle off to require per pipeline launch configuration. Choose either a **Manual** or an **Automatic** configuration for lineage resources: - **Manual**: Define the credentials, region, object storage bucket and path, SQS queue name, and (optionally) SQS queue ARN. - **Automatic**: Define the credentials, region, and (optionally) the object storage bucket and path where lineage data is stored and indexed. This is the default setting. If the storage bucket field is empty, a default bucket is generated for storing lineage data. 4. Once set and enabled, all pipeline runs in the workspace generate data lineage. See [Lineage][workspace-lineage] for more information about the settings. :::danger Updating the lineage settings after pipelines have generated lineage data will result in historic data loss. The lineage index is tied to the lineage storage bucket and path. Changing it makes existing records inaccessible. To avoid data loss when updating the storage location, first copy all existing lineage data to the new bucket and path (for example, `aws s3 cp --recursive s3://old-bucket/path s3://new-bucket/path`), then update the workspace setting. ::: When launching a pipeline in a data-lineage enabled workspace, the **Enable lineage** toggle in the pipeline **Run setup** reflects the **Enable lineage by default** workspace setting. Turn it off to _explicitly exclude_ data lineage for the pipeline run. :::tip Maintain role users and above can toggle lineage on or off when launching a specific pipeline run. ::: ### IAM permissions required Data lineage requires additional AWS IAM permissions. The permissions required depend on the role: - **Platform integration credentials** (IAM user): see [AWS Batch — Data lineage](../compute-envs/aws-batch#data-lineage-optional) or [AWS Cloud — Data lineage](../compute-envs/aws-cloud#data-lineage-optional) - **EC2 instance role / head job role** (manually managed): see [Manual AWS Batch configuration](../enterprise/advanced-topics/manual-aws-batch-setup#create-an-ec2-instance-role) ### Lineage labels Assign lineage labels to output files using the `label` directive in your Nextflow process definitions. Labels appear in lineage records. Both Platform labels and Nextflow lineage labels propagate to lineage records. Platform excludes resource labels because they relate to underlying compute resources, not the data itself. :::info Nextflow lineage labels are **immutable**. They are set at execution time and cannot be changed. Platform labels are _mutable_ by design and can change after a run launches. Changing Platform labels after launch produces a mismatch between Platform run labels and Nextflow lineage labels. ::: ### Changing or disabling data lineage If data lineage is **changed** from automatically-provisioned to manually-provisioned: - **New object storage bucket**: The bucket notification rule is cleared and the Platform-managed SQS queue is deleted. Some events may be missed. The bucket and its data are preserved. - **Same object storage bucket, different SQS queue**: The bucket notification rule is redirected to the new SQS queue ARN, and the old Platform-managed SQS queue is deleted. Some events may be missed. The bucket and its data are preserved. - **Same object storage bucket, same SQS queue**: No cloud provider resources change. All events, the bucket, and its data are preserved. If data lineage is **changed** from manually provisioned to automatically provisioned a new object storage bucket, SQS queue, and notification are created by Platform. Previously defined bucket and data, SQS queue and notifications are preserved. If data lineage is **deactivated**: - **Automatically provisioned**: Queue notification rule is cleared on the bucket, SQS queue deleted. Bucket and data are preserved. - **Manually provisioned**: No change to cloud resources. Bucket and data are preserved. ## Data lineage displayed in Platform ### Workflow run details When a run was executed with lineage enabled, the [run details page][run-details] displays lineage data across the following tabs: - **Run Info**: Shows the lineage ID, lineage labels, and the full Platform context captured at execution time: user, workspace, compute environment, pipeline name, revision, and commit ID. - **Tasks**: Displays the lineage ID and lineage labels for each `TaskRun` alongside existing task data. You can trace any task back to its lineage record. All task file inputs and outputs, and upstream and downstream tasks linked by lineage records, are displayed. - **Inputs**: Lists all input datasets and parameters with file paths, types, and lineage IDs and lineage labels where available. - **Outputs**: Lists all `FileOutput` records linked to the workflow run: output name, file path, type, lineage ID, and lineage labels. Files link directly to [Data Explorer][data-explorer]. :::tip All LIDs and lineage labels are clickable links. Click any LID to open [lineage search](#search-lineage-records) pre-filled with that identifier. ::: :::note If more than one Nextflow run publishes a file to the same destination, there are **two** lineage records. The `FileOutput` records for published files are saved under the lineage ID of the workflow run and can be used to differentiate them. ::: ### Data Explorer Output objects from a lineage-enabled run display their LID and any lineage labels when you preview the object in Data Explorer. You can trace any file back to the pipeline run that produced it. ## Search lineage records Use the search bar in the top navigation to find workflow runs, tasks, and output files across every workspace you can access. Search covers only workspaces that have lineage enabled and in which you are a participant. Results are ordered by most recently indexed. An empty query returns the most recent records across all accessible workspaces. As you type, the field suggests keywords and, where supported, values. ### Search syntax A query is a series of space-separated tokens. Each token is either a `qualifier:value` pair or free text. Three rules apply to every qualifier: - A space between tokens is **AND**: `type:file label:qc` returns output files that carry the `qc` label. - A comma inside a value is **OR**: `type:workflow,task` returns workflow runs and tasks. - Repeating a qualifier is **AND**: `label:qc label:validated` returns records carrying both labels. Qualifier names and free text are case-insensitive. Free text matches any substring of the record value. For example, `salmon` matches any record whose value contains `salmon`. :::caution A record has exactly one type and lives in exactly one workspace. Repeating `type:` or `workspace:` returns an empty list because no record can match both values. For example, `type:workflow type:file` requires a record to be both a workflow run and a file. Use the comma form `type:workflow,file` to match either type. ::: ### Qualifiers | Qualifier | Accepts | Description | | --- | --- | --- | | `type:` | `workflow`, `task`, `file` | Restrict results to a record type. Also accepts the internal names `WorkflowRun`, `TaskRun`, and `FileOutput`. | | `label:` | Any label | Records tagged with the label. Covers both Platform labels and Nextflow lineage labels. | | `workspace:` | `organization/workspace` | Scope the search to one or more workspaces by fully qualified name. | | `workspaceId:` | Numeric workspace ID | Numeric alias for `workspace:`. | | `workflow:` | A `WorkflowRun` LID | Scope the search to a single run. Results include the run itself, its tasks, and its published output files. | | `task:` | A `TaskRun` LID | Scope the search to a single task. Results include the task itself and the output files in its work directory. | | Free text | Any string | Case-insensitive substring match on the record value. | The field suggests `workspace:`, `type:`, and `label:` as you type. Enter the remaining qualifiers manually. `workspace:` and `workspaceId:` set the scope of a search rather than filter its results. A query that contains only a workspace still returns that workspace's most recent records. Omit both to search every workspace available to you. Referencing a workspace you do not participate in returns an error rather than an empty list. ### Examples | Query | Returns | | --- | --- | | `type:workflow,task` | Workflow run or task records | | `label:qc,validated` | Records labeled `qc` or `validated` | | `label:qc label:validated` | Records labeled both `qc` and `validated` | | `label:qc,draft label:validated` | Records labeled `validated` and either `qc` or `draft` | | `type:file salmon` | Output files whose value contains `salmon` | | `workspace:acme/dev label:qc` | Records labeled `qc` in the `acme/dev` workspace | | `workspace:acme/dev,acme/prod` | Records in the `acme/dev` or `acme/prod` workspace | | `workspace:acme/dev workspace:acme/prod` | Nothing, because a record lives in one workspace. Use the comma form instead. | | `workflow:lid://abc123` | The run `lid://abc123`, its tasks, and its published output files | | `workflow:lid://abc123 type:task` | The tasks of run `lid://abc123` | | `task:lid://abc123 type:file` | The output files of task `lid://abc123` | :::tip Lineage search is also available through the Platform API. The `GET /lineage/search` endpoint accepts the same query syntax in its `q` parameter and returns paginated results. See the [Platform API reference][platform-api] for the full set of lineage endpoints. ::: ## Advanced: Experimenting with data lineage To test or troubleshoot data lineage for a _specific pipeline_, add the following to your **Nextflow config file** under **Advanced options** when _adding_ a pipeline to the launchpad. ```groovy lineage.enabled = true lineage.store.location = '' ``` To test for a _single pipeline run_, add the same code to your **Nextflow config file** under **Advanced options** when _launching_ the pipeline run. :::warning If data lineage is defined for a workspace, only that data is displayed in Platform. Any unique _specific pipeline_ or _single pipeline run_ lineage data is only accessible via the AWS S3 console and other related services (such as Amazon Athena). ::: ## Costs associated with data lineage Monthly S3 object storage bucket and SQS costs scale based on the number of pipeline runs launched with lineage enabled. Typical SQS queue costs for a single rnaseq pipeline run daily are less than $10 USD/month. {/* links */} [workflow-labels]: https://docs.seqera.io/nextflow/workflow#labels [workspace-lineage]: ../orgs-and-teams/workspace-management#lineage [run-details]: ../monitoring/run-details [data-explorer]: data-explorer [platform-api]: https://docs.seqera.io/platform-api --- ## Datasets Datasets are CSV (comma-separated values) and TSV (tab-separated values) files stored in, or linked to, a workspace. Use them as pipeline inputs to simplify data management, reduce data-entry errors, and support reproducible analyses. On the datasets screen, you can: - Upload directly or link to an externally hosted dataset. - View the count of pipeline runs in the workspace that have used a specific dataset input. - Apply multiple labels to datasets for easier searching and grouping. - Sort datasets by name, most recently updated, and most recently used. - Hide datasets that are not used in the workspace. - View dataset metadata (created by, last updated, last used). - Edit dataset details (name, description, and labels). - Create new versions of an uploaded dataset. ## Benefits - Datasets reduce errors from manual data entry when you launch pipelines. - Datasets can be generated automatically in response to events (such as new-file notifications from S3 storage). - Datasets can simplify differential data analysis when you use the same pipeline to launch a run for each dataset as it becomes available. ## Format The most commonly used datasets for Nextflow pipelines are sample sheets, where each row contains a sample identifier, the location of that sample's files (such as FASTQ files), and other sample details. For example, [*nf-core/rnaseq*](https://github.com/nf-core/rnaseq) works with input datasets (sample sheets) that include sample names, FASTQ file locations, and strandedness annotations. The Seqera Community Showcase sample dataset for *nf-core/rnaseq* looks like this: **Example rnaseq dataset** |sample |fastq_1 |fastq_2 |strandedness| |-------------------|------------------------------------|---------------------------------------------|------------| |WT_REP1 |s3://nf-core-awsmegatests/rnaseq/...|s3://nf-core-awsmegatests/rnaseq/... |reverse | |WT_REP1 |s3://nf-core-awsmegatests/rnaseq/...|s3://nf-core-awsmegatests/rnaseq/... |reverse | |WT_REP2 |s3://nf-core-awsmegatests/rnaseq/...|s3://nf-core-awsmegatests/rnaseq/... |reverse | |RAP1_UNINDUCED_REP1|s3://nf-core-awsmegatests/rnaseq/...| |reverse | |RAP1_UNINDUCED_REP2|s3://nf-core-awsmegatests/rnaseq/...| |reverse | |RAP1_UNINDUCED_REP2|s3://nf-core-awsmegatests/rnaseq/...| |reverse | |RAP1_IAA_30M_REP1 |s3://nf-core-awsmegatests/rnaseq/...|s3://nf-core-awsmegatests/rnaseq/... |reverse | :::note Use [Data Explorer](../data/data-explorer) to browse for cloud storage objects directly and copy the object paths to be used in your datasets. ::: ### Automation and pipeline schemas Combine datasets, [secrets](../secrets/overview), and [actions](../pipeline-actions/overview) to automate workflows that curate your data and maintain and launch pipelines in response to specific events. See [workflow-automation](https://seqera.io/blog/workflow-automation/) for an example of pipeline workflow automation. For your pipeline to use your dataset as input during runtime, information about the dataset and file format must be included in the relevant parameters of your [pipeline schema](../pipeline-schema/overview). The pipeline schema specifies the accepted dataset file type in the `mimetype` attribute (either `text/csv` or `text/tsv`). ## Dataset file content requirements and validation Datasets can point to files stored in Amazon S3, GitHub, Hugging Face, and other locations. To stage the file paths defined in the dataset, Nextflow requires access to the infrastructure where the files reside, whether on cloud or HPC systems. Add the access keys for data sources that require authentication to your [secrets](../secrets/overview). :::note Seqera doesn't validate your dataset file contents. While datasets can contain static file links, you're responsible for maintaining the access to that data. ::: ## Add a dataset All Seqera user roles have access to the datasets feature in organization workspaces. There are two ways to add a dataset: 1. **Direct upload**: Best when you need immutability and the file is under 10 MB. 2. **Link to an externally hosted file**: Best for large files, but availability and immutability depend on the external hosting service. ### Direct upload 1. In the sidebar navigation, select **Datasets**. 1. Select **Add Dataset** and choose **Upload file**. 1. Complete the **Name** and **Description** fields using information relevant to your dataset. 1. Optionally add one or more **Labels** to your dataset. You can use labels as a search filter but they don't apply to other resources in Seqera. 1. Upload a dataset to your workspace with drag-and-drop or use the **Upload file** file explorer dialog. 1. For datasets that use their first row for column names, customize the dataset view using the **Set first row as header** option. 1. Select **Add**. :::warning The size of the uploaded dataset file cannot exceed 10 MB. ::: ### Link to an externally hosted file 1. In the sidebar navigation, select **Datasets**. 1. Select **Add Dataset** and choose **Link to URL**. 1. Complete the **Name** and **Description** fields using information relevant to your dataset. 1. Optionally add one or more **Labels** to your dataset. You can use labels as a search filter but they don't apply to other resources in Seqera. 1. Copy and paste the dataset URL into the **Dataset URL** field. 1. For datasets that use their first row for column names, customize the dataset view using the **Set first row as header** option. 1. Select **Add**. 1. The dataset appears with a `Linked` badge. ## Manage dataset versions For directly uploaded datasets, Seqera can manage multiple versions. :::note For linked datasets, versioning is unavailable. ::: ### Add a dataset version 1. Select the three dots next to the dataset you want to add a new version for. 2. Select **Add version**. 3. Upload a dataset to your workspace with drag-and-drop or use the system **Upload file** file explorer dialog. 4. For datasets that use their first row for column names, customize the dataset view using the **Set first row as header** option. 5. Select **Add**. :::caution All subsequent versions of a dataset must be the same format (CSV or TSV) as the initial version. ::: ### View dataset versions To see all versions of a dataset, use the **Show** drop-down in the **Preview** tab. Seqera automatically displays a preview of the most recent version and flags it as **(latest)**, unless it is disabled. To preview previous dataset versions, change the version from the **Show** drop-down. The **Created by** and **Created on** values also change. To download a dataset version, select the **Download** icon. To copy a permalink to the dataset, select the **Copy** icon. ### Disable a dataset version To disable one or more dataset versions, select **Disable version**. A disabled version cannot be selected as a pipeline input. If you disable the most recent version, the most recent non-disabled version is flagged as **(latest)**. :::note For compliance reasons, datasets or dataset versions cannot be deleted, they can only be **hidden** or **disabled**, respectively. Once disabled, a dataset version cannot be re-enabled. ::: ## Use a dataset To use a dataset with pipelines added to your workspace: 1. Open any pipeline that contains a pipeline schema from the [Launchpad](../launch/launchpad). 2. Select the input field for the pipeline, removing any default values. 3. Pick the dataset to use as input to your pipeline. :::note The input field drop-down displays only datasets that match the file type specified in the `nextflow_schema.json` of the chosen pipeline. If the schema specifies `"mimetype": "text/csv"`, no TSV datasets are available for use with that pipeline, and vice-versa. If multiple dataset versions exist, the pipeline input always defaults to the **latest** version. ::: ## Manage datasets **View runs** To view a list of all pipeline runs in a workspace that have used a specific dataset input either: - Select the three dots next to a dataset and select **View runs**. - Select the number in the **Runs** column. **Toggle dataset visibility** Select the three dots next to a dataset and select **Mark dataset as hidden** to hide a dataset no longer used in your workspace. To show a hidden dataset, select **Mark dataset as visible**. This filter applies to all workspace users. You can toggle between **Visible**, **Hidden**, and **All** datasets in the **Show** drop-down on the main datasets page. :::note Hidden datasets do not count toward your per workspace quota. ::: **Filter datasets** Filter the list of datasets to only display datasets that match one or more filters defined in the **Search datasets** field. Select the info icon to see the list of available filters. **Edit dataset details** Select the three dots next to a dataset to edit the name, description, and labels associated with a dataset. --- ## Data privacy Seqera Platform orchestrates pipeline execution in your own infrastructure and stores only a limited set of metadata about your runs and tasks. ## Your data Your data stays within your infrastructure. To launch a pipeline with Seqera Platform, you create credentials and a compute environment in a workspace to connect your own infrastructure, such as high-performance computing (HPC) clusters, virtual machines (VMs), or Kubernetes. Seqera Platform uses this configuration to run the pipeline in your infrastructure, the same way the Nextflow CLI does. Seqera Platform does not manipulate your data, and your data is not transferred to the infrastructure where Seqera Platform runs. You can view some data in your storage from the Seqera Platform interface, such as logs and reports generated in a pipeline run. This data is never stored in Seqera Platform infrastructure. ## User deletion When a Seqera Platform user account is deleted: - The user account email is changed to `none@your-domain`. Runs and run metadata associated with the user account display that email address. - The username is changed to `username-`. - All of the user's organization, workspace, and team memberships are deleted. - All of the user's access tokens are deleted from their personal workspace. Enterprise installations also delete the following from the user's personal workspace: - All credentials - All compute environments - All actions created by the user ### Studios connectivity Studios is a stateless application that uses access tokens to manage connections. By default, access tokens expire after one hour, and a deleted user account can retain access to a running Studio session until its token expires. To revoke access sooner, a workspace user with the Maintain role can stop and start all Studio sessions in the workspace where the account was deleted. ## Metadata stored by Seqera Platform The Nextflow runtime sends workflow execution metadata to Seqera Platform when: - You launch a pipeline from Seqera Platform. - You run a pipeline with the `-with-tower` command-line option. - You set `tower.enabled` in your Nextflow configuration. ### Workflow metadata Seqera Platform collects and stores the following metadata fields during a workflow execution: | Name | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `command_line` | The command line used to launch the workflow execution | | `commit_id` | The workflow project commit ID at the time of the execution | | `complete` | The workflow execution completion timestamp | | `config_files` | The Nextflow config file path(s) involved in the workflow execution | | `config_text` | The Nextflow config content used for the workflow execution. Note: secrets, such as AWS keys, are stripped and _not_ included in this field | | `container` | The container image name(s) used for the pipeline execution | | `container_engine` | The container engine name used for the pipeline execution | | `duration` | The workflow execution overall duration (wall time) | | `error_message` | The error message reported when the Nextflow execution fails | | `error_report` | The extended error message reported when the workflow execution fails | | `exit_status` | The workflow execution (POSIX) exit code | | `home_dir` | The launching user home directory path | | `launch_dir` | The workflow launching directory path | | `manifest_author` | The workflow project author as defined in the Nextflow config manifest file | | `manifest_default_branch` | The workflow project default Git branch as defined in the Nextflow config manifest file | | `manifest_description` | The workflow project description as defined in the Nextflow config manifest file | | `manifest_gitmodules` | The workflow project Git submodule flag in the Nextflow config manifest file | | `manifest_home_page` | The workflow project Git home page as defined in the Nextflow config manifest file | | `manifest_main_script` | The workflow project main script file name as defined in the Nextflow config manifest file | | `manifest_name` | The workflow project name as defined in the Nextflow config manifest file | | `manifest_nextflow_version` | The workflow project required Nextflow version defined in the Nextflow config manifest file | | `manifest_version` | The workflow project version string as defined in the Nextflow config manifest file | | `nextflow_build` | The build number of the Nextflow runtime used to launch the workflow execution | | `nextflow_timestamp` | The build timestamp of the Nextflow runtime used to launch the workflow execution | | `nextflow_version` | The version string of the Nextflow runtime used to launch the workflow execution | | `params` | The workflow params used to launch the pipeline execution | | `profile` | The workflow config profile string used for the pipeline execution | | `project_dir` | The directory path where the workflow scripts are stored | | `project_name` | The workflow project name | | `repository` | The workflow project repository | | `resume` | The flag set when a resume execution was submitted | | `revision` | The workflow project revision number | | `run_name` | The workflow run name as given by the Nextflow runtime | | `script_file` | The workflow script file path | | `script_id` | The workflow script checksum number | | `script_name` | The workflow script filename | | `session_id` | The workflow execution unique UUID as assigned by the Nextflow runtime | | `start` | The workflow execution start timestamp | | `stats_cached_count` | The number of cached tasks upon completion | | `stats_cached_duration` | The aggregate time of cached tasks upon completion | | `stats_cached_pct` | The percentage of cached tasks upon completion | | `stats_compute_time_fmt` | The overall compute time as a formatted string | | `stats_failed_count` | The number of failed tasks upon completion | | `stats_failed_count_fmt` | The number of failed tasks upon completion as a formatted string | | `stats_failed_duration` | The aggregate time of failed tasks upon completion | | `stats_failed_pct` | The percentage of failed tasks upon completion | | `stats_ignored_count` | The number of ignored tasks upon completion | | `stats_ignored_count_fmt` | The number of ignored tasks upon completion as a formatted string | | `stats_ignored_pct` | The percentage of ignored tasks upon completion | | `stats_succeed_count` | The number of succeeded tasks upon completion | | `stats_succeed_count_fmt` | The number of succeeded tasks upon completion as a formatted string | | `stats_succeed_duration` | The aggregate time of succeeded tasks upon completion | | `stats_succeed_pct` | The percentage of succeeded tasks upon completion | | `status` | The workflow execution status | | `submit` | The workflow execution submission timestamp | | `success` | The flag reporting whether the execution completed successfully | | `user_name` | The POSIX user name that launched the workflow execution | | `work_dir` | The workflow execution scratch directory path | ### Task metadata Seqera Platform collects and stores the following metadata fields for each task: | Name | Description | | -------------- | ---------------------------------------------------------------------------------------------- | | `attempt` | Number of Nextflow execution attempts of the task | | `cloud_zone` | Cloud zone where the task execution was allocated | | `complete` | Task execution completion timestamp | | `container` | Container image name used to execute the task | | `cost` | Estimated task compute cost | | `cpus` | Number of CPUs requested | | `disk` | Amount of disk storage requested | | `duration` | Amount of time for the task to complete | | `env` | Task execution environment variables | | `error_action` | Action applied on task failure | | `executor` | Executor requested for the task execution | | `exit_status` | Task POSIX exit code on completion | | `hash` | Task unique hash code | | `inv_ctxt` | Number of involuntary context switches | | `machine_type` | Cloud virtual machine type | | `memory` | Amount of memory requested | | `module` | Environment module requested | | `name` | Task unique name | | `native_id` | Task unique ID as assigned by the underlying execution platform | | `pcpu` | Percentage of CPU used to compute the task | | `peak_rss` | Peak of real memory during the task execution | | `peak_vmem` | Peak of virtual memory during the task execution | | `pmem` | Percentage of memory used to compute the task | | `price_model` | Cloud price model applied for the task | | `process` | Nextflow process name | | `queue` | Compute queue name requested | | `rchar` | Number of bytes the process read, using any read-like system call from files, pipes, and terminals | | `read_bytes` | Number of bytes the process directly read from disk | | `realtime` | Time required to compute the task | | `rss` | Real memory (resident set) size of the process | | `scratch` | Flag reporting the task was executed in a local scratch path | | `script` | Task command script | | `start` | Task execution start timestamp | | `status` | Task execution status | | `submit` | Task submission timestamp | | `syscr` | Number of read-like system call invocations that the process performed | | `syscw` | Number of write-like system call invocations that the process performed | | `tag` | Nextflow tag associated with the task execution | | `task_id` | Nextflow task ID | | `time` | Task execution timeout requested | | `vmem` | Virtual memory size used by the task execution | | `vol_ctxt` | Number of voluntary context switches | | `wchar` | Number of bytes the process wrote, using any write-like system call | | `workdir` | Task execution work directory | | `write_bytes` | Number of bytes the process wrote to disk | --- ## Manual AWS Batch configuration This page describes how to set up AWS roles and Batch queues manually for the deployment of Nextflow workloads with Seqera Platform. :::tip Manual AWS Batch configuration is only necessary if you don't want to let Seqera Platform create the required AWS Batch resources in your AWS account automatically, done using the internal tool called Batch Forge. ::: Complete the following steps to configure the AWS Batch resources needed by Seqera Platform: 2. Create the instance role policy. 3. Create the AWS Batch service role. 4. Create an EC2 Instance role. 5. Create a Nextflow head job role. 6. Create an EC2 SpotFleet role. 7. Create a launch template. 8. Create the AWS Batch compute environments. 9. Create the AWS Batch queue. ### Create the instance role policy Create the policy with a role that allows Seqera to submit Batch jobs on your EC2 instances: 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create policy** from the Policies page. 1. Create a new policy with the following content: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "batch:DescribeJobQueues", "batch:CancelJob", "batch:SubmitJob", "batch:ListJobs", "batch:DescribeComputeEnvironments", "batch:TerminateJob", "batch:DescribeJobs", "batch:RegisterJobDefinition", "batch:DescribeJobDefinitions", "batch:TagResource", "ecs:DescribeTasks", "ec2:DescribeInstances", "ec2:DescribeInstanceTypes", "ec2:DescribeInstanceAttribute", "ecs:DescribeContainerInstances", "ec2:DescribeInstanceStatus", "logs:Describe*", "logs:Get*", "logs:List*", "logs:Create*", "logs:Put*", "logs:StartQuery", "logs:StopQuery", "logs:TestMetricFilter", "logs:FilterLogEvents" ], "Resource": "*" } ] } ``` 1. Save it with the name `seqera-batchjob`. ### Create the Batch Service role Create a service role used by AWS Batch to launch EC2 instances on your behalf: 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create role** from the Roles page. 1. Select **AWS service** as the trusted entity type, and **Batch** as the service. 1. On the next page, the `AWSBatchServiceRole` is already attached. No further permissions are needed for this role. 1. Enter `seqera-servicerole` as the role name and add an optional description and tags if needed, then select **Create**. ### Create an EC2 instance role Create a role that controls which AWS resources the EC2 instances launched by AWS Batch can access: 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create role** from the Roles page. 1. Select AWS service as the trusted entity type, EC2 as the service, and _EC2 - Allows EC2 instances to call AWS services on your behalf_ as the use case. 1. Select **Next: Permissions**. Search for the following policies to attach to the role: - `AmazonEC2ContainerServiceforEC2Role` - `AmazonS3FullAccess` (you may want to use a custom policy to allow access only on specific S3 buckets) - `seqera-batchjob` (the instance role policy created above) 1. Enter `seqera-instancerole` as the role name and add an optional description and tags if needed, then select **Create**. If you enable [data lineage](../../data/data-lineage) in your workspace, attach the following additional policy to this role to allow access to the lineage S3 bucket: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "LineageListBucket", "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": "arn:aws:s3:::seqera-lineage-" }, { "Sid": "LineageObjectAccess", "Effect": "Allow", "Action": "s3:*Object", "Resource": "arn:aws:s3:::seqera-lineage-/*" }, { "Sid": "LineageObjectTagging", "Effect": "Allow", "Action": [ "s3:PutObjectTagging", "s3:GetObjectTagging" ], "Resource": "arn:aws:s3:::seqera-lineage-/*" } ] } ``` ### Create a Nextflow head job role Create an IAM role for the Nextflow head job. This role is attached to the Nextflow head job container and grants it the permissions needed to orchestrate workflow tasks and retrieve task logs from CloudWatch. You specify this role in the **Head Job role** field when creating a manual compute environment in Seqera Platform. :::note This role is separate from the EC2 instance role. The head job role is attached directly to the Nextflow container via the Batch job definition, while the instance role applies to the underlying EC2 instance. ::: 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create policy** from the Policies page. 1. Create a new policy with the following content: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "BatchJobManagement", "Effect": "Allow", "Action": [ "batch:DescribeJobQueues", "batch:CancelJob", "batch:SubmitJob", "batch:ListJobs", "batch:DescribeComputeEnvironments", "batch:TerminateJob", "batch:DescribeJobs", "batch:RegisterJobDefinition", "batch:DescribeJobDefinitions", "batch:TagResource", "ecs:DescribeTasks", "ec2:DescribeInstances", "ec2:DescribeInstanceTypes", "ec2:DescribeInstanceAttribute", "ecs:DescribeContainerInstances", "ec2:DescribeInstanceStatus" ], "Resource": "*" }, { "Sid": "CloudWatchLogsAccess", "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:FilterLogEvents", "logs:GetLogEvents", "logs:ListTagsLogGroup", "logs:PutLogEvents", "logs:StartQuery", "logs:StopQuery", "logs:TestMetricFilter" ], "Resource": "*" } ] } ``` :::note `logs:GetLogEvents` is required for Nextflow to retrieve task stderr from CloudWatch when tasks fail. Without it, error reports for failed tasks show an `AccessDeniedException` instead of the actual task error. ::: 1. Save it with the name `seqera-headjob-policy`. 1. Select **Create role** from the Roles page. Select **AWS service** as the trusted entity type and **Elastic Container Service Task** as the use case. 1. Attach the `seqera-headjob-policy` policy to the role. 1. Enter `seqera-headjob-role` as the role name and select **Create**. ### Create an EC2 SpotFleet role The EC2 SpotFleet role allows you to use Spot instances when you run jobs in AWS Batch. Create a role for the creation and launch of Spot fleets — Spot instances with similar compute capabilities (i.e., vCPUs and RAM): 1. In the [IAM Console](https://console.aws.amazon.com/iam/home), select **Create role** from the Roles page. 1. Select AWS service as the trusted entity type, EC2 as the service, and _EC2 - Spot Fleet Tagging_ as the use case. 1. On the next page, the `AmazonEC2SpotFleetTaggingRole` is already attached. No further permissions are needed for this role. 1. Enter `seqera-fleetrole` as the role name and add an optional description and tags if needed, then select **Create**. ### Create a launch template Create a launch template to configure the EC2 instances deployed by Batch jobs: 1. In the [EC2 Console](https://console.aws.amazon.com/ec2/v2/home), select **Create launch template** from the Launch templates page. 1. Scroll down to **Advanced details** and paste the following in the **User data** field: ```bash MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="//" --// Content-Type: text/cloud-config; charset="us-ascii" #cloud-config write_files: - path: /root/custom-ce.sh permissions: 0744 owner: root content: | #!/usr/bin/env bash exec > >(tee /var/log/tower-forge.log|logger -t TowerForge -s 2>/dev/console) 2>&1 ## yum install -q -y jq sed wget unzip nvme-cli lvm2 ## install CloudWatch agent curl -s https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm -o amazon-cloudwatch-agent.rpm rpm -U ./amazon-cloudwatch-agent.rpm rm -f ./amazon-cloudwatch-agent.rpm curl -s https://nf-xpack.seqera.io/amazon-cloudwatch-agent/config-v0.4.json \ # | sed 's/$FORGE_ID//g' \ > /opt/aws/amazon-cloudwatch-agent/bin/config.json /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \ -a fetch-config \ -m ec2 \ -s \ -c file:/opt/aws/amazon-cloudwatch-agent/bin/config.json ## format NVMe storage for Fusion mkdir -p /scratch/fusion NVME_DISKS=($(nvme list | grep 'Amazon EC2 NVMe Instance Storage' | awk '{ print $1 }')) NUM_DISKS=${#NVME_DISKS[@]} if (( NUM_DISKS > 0 )); then if (( NUM_DISKS == 1 )); then mkfs -t xfs ${NVME_DISKS[0]} mount ${NVME_DISKS[0]} /scratch/fusion else pvcreate ${NVME_DISKS[@]} vgcreate scratch_fusion ${NVME_DISKS[@]} lvcreate -l 100%FREE -n volume scratch_fusion mkfs -t xfs /dev/mapper/scratch_fusion-volume mount /dev/mapper/scratch_fusion-volume /scratch/fusion fi fi chmod a+w /scratch/fusion ## ECS configuration mkdir -p /etc/ecs echo ECS_IMAGE_PULL_BEHAVIOR=once >> /etc/ecs/ecs.config echo ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE=true >> /etc/ecs/ecs.config echo ECS_ENABLE_SPOT_INSTANCE_DRAINING=true >> /etc/ecs/ecs.config echo ECS_CONTAINER_CREATE_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_CONTAINER_START_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_CONTAINER_STOP_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_MANIFEST_PULL_TIMEOUT=10m >> /etc/ecs/ecs.config ## stop docker systemctl stop docker ## install AWS CLI curl -s https://nf-xpack.seqera.io/miniconda-awscli/miniconda-25.3.1-awscli-1.40.12.tar.gz \ | tar xz -C / export PATH=$PATH:/home/ec2-user/miniconda/bin ln -s /home/ec2-user/miniconda/bin/aws /usr/bin/aws ## restart docker systemctl start docker systemctl enable --now --no-block ecs ## kernel settings to prevent OOM echo "1258291200" > /proc/sys/vm/dirty_bytes echo "629145600" > /proc/sys/vm/dirty_background_bytes runcmd: - bash /root/custom-ce.sh --//-- ``` 1. To prepend a custom identifier to the CloudWatch log streams for AWS resources created by your manual compute environment, uncomment the `| sed 's/$FORGE_ID//g' \` line and replace `` with your custom identifier. If omitted, `$FORGE_ID` remains as-is in the config. 1. Save the template with the name `seqera-launchtemplate`. 1. In the [EC2 Console](https://console.aws.amazon.com/ec2/v2/home), select **Create launch template** from the Launch templates page. 1. Scroll down to **Advanced details** and paste the following in the **User data** field: ```bash MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="//" --// Content-Type: text/cloud-config; charset="us-ascii" #cloud-config write_files: - path: /root/custom-ce.sh permissions: 0744 owner: root content: | #!/usr/bin/env bash exec > >(tee /var/log/tower-forge.log|logger -t TowerForge -s 2>/dev/console) 2>&1 ## yum install -q -y jq sed wget unzip nvme-cli lvm2 ## install CloudWatch agent curl -s https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm -o amazon-cloudwatch-agent.rpm rpm -U ./amazon-cloudwatch-agent.rpm rm -f ./amazon-cloudwatch-agent.rpm curl -s https://nf-xpack.seqera.io/amazon-cloudwatch-agent/config-v0.4.json \ # | sed 's/$FORGE_ID//g' \ > /opt/aws/amazon-cloudwatch-agent/bin/config.json /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \ -a fetch-config \ -m ec2 \ -s \ -c file:/opt/aws/amazon-cloudwatch-agent/bin/config.json ## ECS configuration mkdir -p /etc/ecs echo ECS_IMAGE_PULL_BEHAVIOR=once >> /etc/ecs/ecs.config echo ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE=true >> /etc/ecs/ecs.config echo ECS_ENABLE_SPOT_INSTANCE_DRAINING=true >> /etc/ecs/ecs.config echo ECS_CONTAINER_CREATE_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_CONTAINER_START_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_CONTAINER_STOP_TIMEOUT=10m >> /etc/ecs/ecs.config echo ECS_MANIFEST_PULL_TIMEOUT=10m >> /etc/ecs/ecs.config ## stop docker systemctl stop docker ## install AWS CLI curl -s https://nf-xpack.seqera.io/miniconda-awscli/miniconda-25.3.1-awscli-1.40.12.tar.gz \ | tar xz -C / export PATH=$PATH:/home/ec2-user/miniconda/bin ln -s /home/ec2-user/miniconda/bin/aws /usr/bin/aws ## restart docker systemctl start docker systemctl enable --now --no-block ecs ## kernel settings to prevent OOM echo "1258291200" > /proc/sys/vm/dirty_bytes echo "629145600" > /proc/sys/vm/dirty_background_bytes runcmd: - bash /root/custom-ce.sh --//-- ``` 1. To prepend a custom identifier to the CloudWatch log streams for AWS resources created by your manual compute environment, uncomment the `| sed 's/$FORGE_ID//g' \` line and replace `` with your custom identifier. If omitted, `$FORGE_ID` remains as-is in the config. 1. Save the template with the name `seqera-launchtemplate`. ### Create the Batch compute environments :::caution AWS Graviton instances (ARM64 CPU architecture) are not supported in manual compute environments. To use Graviton instances, create your AWS Batch compute environment with [Batch Forge](../../compute-envs/aws-batch#create-a-seqera-aws-batch-compute-environment). ::: Nextflow makes use of two job queues during workflow execution: - A head queue to run the Nextflow application - A compute queue where Nextflow will submit job executions While the compute queue can use a compute environment with Spot instances, the head queue requires an on-demand compute environment. If you intend to use an on-demand compute environment for compute jobs, the same job queue can be used for both head and compute. :::note Spot instances can significantly reduce your AWS compute costs, provided your workflow compute tasks can run on ephemeral instances. ::: Create a compute environment for each queue in the AWS Batch console: The head queue requires an on-demand compute environment. Do not select **Use Spot instances** during compute environment creation. 1. In the [Batch Console](https://eu-west-1.console.aws.amazon.com/batch/home), select **Create** on the Compute environments page. 1. Select **Amazon EC2** as the compute environment configuration. :::note Seqera AWS Batch compute environments created with [Batch Forge](../../compute-envs/aws-batch#create-a-seqera-aws-batch-compute-environment) support using Fargate for the head job, but manual compute environments must use EC2. ::: 1. Enter a name of your choice, and apply the `seqera-servicerole` and `seqera-instancerole`. 1. When creating the Seqera compute environment, enter the ARN of `seqera-headjob-role` in the **Head Job role** field. 1. Enter vCPU limits and instance types, if needed. :::note To use the same queue for both head and compute tasks, you must assign sufficient resources to your compute environment. ::: 1. Expand **Additional configuration** and select the `seqera-launchtemplate` from the Launch template drop-down. 1. Configure VPCs, subnets, and security groups on the next page as needed. 1. Review your configuration and select **Create compute environment**. Create this compute environment to use Spot instances for your workflow compute tasks. This compute environment cannot be assigned to the Nextflow head job queue. 1. In the [Batch Console](https://eu-west-1.console.aws.amazon.com/batch/home), select **Create** on the Compute environments page. 1. Select **Amazon EC2** as the compute environment configuration. 1. Enter a name of your choice, and apply the `seqera-servicerole` and `seqera-instancerole`. 1. Select **Enable using Spot instances** to use Spot instances and save computing costs. 1. Select the `seqera-fleetrole` and enter vCPU limits and instance types, if needed. 1. Expand **Additional configuration** and select the `seqera-launchtemplate` from the Launch template drop-down. 1. Configure VPCs, subnets, and security groups on the next page as needed. 1. Review your configuration and select **Create compute environment**. ### Create the Batch queue Create a Batch queue to be associated with each compute environment. :::note You only need to create one queue if you intend to use on-demand instances for your workflow compute tasks. Compute environments with Spot instances require separate queues for the head and compute tasks. ::: 1. Go to the [Batch Console](https://eu-west-1.console.aws.amazon.com/batch/home). 2. Create a new queue. 3. Associate the queue with the head queue compute environment created in the previous section. 4. Save it with a name of your choice. 1. Go to the [Batch Console](https://eu-west-1.console.aws.amazon.com/batch/home). 2. Create a new queue. 3. Associate the queue with the compute queue environment created in the previous section. 4. Save it with a name of your choice. Use the AWS resources created on this page to create your [manual AWS Batch compute environment](../../compute-envs/aws-batch#manual-configuration-of-batch-resources). --- ## Azure Batch compute environment setup This guide details how to set up an Azure Batch and Seqera Cloud account to run a workflow in a Seqera Azure Batch compute environment. It begins with the simplest possible setup and then details more complex environment configuration options. ## Prerequisites - An Azure account with sufficient permissions to create resources. - [Azure CLI][install-azure-cli] - [Seqera Platform CLI][install-seqera-cli] ### Set up Azure Batch In the Azure Portal: 1. Create an Azure Storage account with the default settings. 1. In the Azure Storage account, add a single blob container called `work`. This is the [Nextflow working directory][nextflow-working-directory]. 1. Create a new Azure Batch account. Use Batch Managed for now, with the default settings. Use the same region as your Storage account and attach the Storage account to the Batch account when prompted. 1. On the Azure Batch page, select **Quotas**. 1. Select **Request Quota Increase**. 1. For **Quota Type**, select **Batch**, then select **Next**. 1. Select **Enter Details**, then choose the **Location** as the region of your Batch account. 1. Select **EDv5 Series**. 1. Select **Active jobs and job schedules per Batch account**. 1. Select **Pools per Batch account**. Increase each value to a minimum of the following: - **EDv5 Series**: 192 - **Active jobs and job schedules per Batch account**: 100 - **Pools per Batch account**: 50 ### Set up Seqera Cloud In Seqera Cloud: - Create a new account. - [Create a new organization and workspace][create-org-workspace]. - Add a GitHub credential the workspace to prevent API rate-limiting issues with GitHub. ## Compute environment and pipeline configuration ### Option 1. Azure Batch with Seqera Batch Forge **Behavior**: - Seqera Platform will submit a Nextflow job and task to this pool. - The Nextflow job will execute and submit each task to the same node pool on Azure Batch. - The node pool will autoscale up and down based on the number of waiting tasks. **Advantages**: - Simple to set up. - Low cost. - Autoscales for number of waiting tasks. **Disadvantages**: - The Nextflow job will submit each task to the same node pool on Azure Batch, which can cause bottlenecks. - Because the processes require larger resources than the head node, you often have oversized machines running Nextflow or undersized machines running processes. - Dedicated nodes only. The first configuration is a simple Azure Batch compute environment created with Batch Forge. This environment uses the same Batch pool for both the Nextflow head job and task nodes. First, add the Azure Batch account credentials to Seqera Platform: 1. In the Azure portal, go to the Batch account you created and note the Batch account name and region. 1. Go to the **Keys** tab to find the primary access keys for the Batch account and Storage account. 1. In your Seqera Platform workspace, go to the **Credentials** tab and select **Add credentials**. 1. Enter a credential name such as `azure-keys` and select Azure from the **Provider** drop-down. 1. Enter the Batch account name and key, and Storage account name and key. 1. Select **Create** to save the credentials. Seqera now has the credentials needed to access your Azure Batch and Storage accounts and make the necessary changes. Next, create a compute environment with Batch Forge: 1. Go to the **Compute Environments** tab and select **Add Compute Environment**. 1. Enter a name such as `1-azure-batch-forge`. 1. Select Azure Batch from the **Provider** drop-down. 1. Select your `azure-keys` credentials. 1. Select the **Region** of your Batch account. 1. Select the `az://work` container in your Storage account. 1. For **VMs type**, select `standard_e2ds_v5`. 1. For **VMs count**, select 4. 1. Enable **Autoscale** and **Dispose resources**. 1. All other options can be left default. Select **Create** to save the compute environment. Add the `nextflow-hello` pipeline to your workspace: [Add a pipeline][add-pipeline] from your workspace Launchpad with the following settings: - Select your Azure Batch compute environment from the drop-down. - For **Pipeline to launch**, enter `https://github.com/nextflow-io/hello`. - For **Work directory**, enter a subdirectory in the `az://work` container in your Storage account. Select **Launch** next to the pipeline name in your workspace Launchpad to complete the launch form and launch the workflow. ### Option 2. Use a separate node and head pool on Seqera Platform **Behavior**: - Seqera Platform will submit a Nextflow job and task to the first pool. - The Nextflow job will execute and submit each task to the second pool. - Both pools will autoscale up and down based on the number of waiting tasks. **Advantages**: - The processes are not bottlenecked by the head node. - You can set the worker nodes to use a different VM size than the head node. **Disadvantages**: - More complex to set up. - Still fairly inflexible. - You have to wait a long time for nodes to autoscale up and down in response to the work. This configuration separates head and task nodes into different Batch pools. To create a separate node pool to run all the processes: 1. Create another compute environment in Seqera Platform, exactly as before: - **Name**: `2-azure-batch-low-priority` or similar - **Platform**: Azure Batch - **Credentials**: `azure-keys` - **Region**: As before - **Work directory**: As before - **VMs type**: `standard_e2ds_v5` - **VMs count**: `4` 1. Note the compute environment ID, which is the first item on the compute environment page. 1. In the Azure Portal, go to the Batch account you created earlier. 1. Go to the **Pools** tab and create a new pool. 1. Find the pool called `tower-pool-${id}`, where `${id}` is the ID you noted earlier. 1. Select **Scale**. 1. Select **Evaluate**, then **Save**. You can now run Nextflow on the first pool, but execute all the processes on the second pool. 1. On the pipeline launch page, duplicate the existing pipeline, but do not save it yet. 1. Under advanced options, add the following configuration block to the `nextflow.config` text input: ```nextflow process.queue = 'tower-pool-${id}' ``` :::info Remember to replace `${id}` with the ID of the compute environment you created earlier! ::: 1. Save the pipeline as `hello-world-worker`. Select **Launch** next to the `hello-world-worker` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. ### Option 3. Configure the head pool with a hot node **Behavior**: - A "hot" head node is left running. - The head node will run Nextflow as soon as the work is created. - The worker node pool will autoscale up and down based on the number of waiting tasks. **Advantages**: - The latency of the pipeline is reduced. **Disadvantages**: - The always-on head node incurs additional cost. This configuration separates the head and task pools as before and leaves a single head node up and running to make the response time faster. To create the compute environment with a persistent head node: 1. Get the ID of the first node pool (`1-azure-batch-forge`). 1. In the Azure Portal, go to the Batch account you created earlier. 1. Go to the **Pools** tab and find the pool called `tower-pool-${id}`, where `${id}` is the ID you made a note of earlier. 1. Select **Scale**. 1. In the line `targetPoolSize = max(0, min($targetVMs, 4));`, change the `0` to `1`. 1. Select **Evaluate**, then **Save**. The node pool will increase to a minimum of 1 node. Now, when you make adjustments to the pipeline, the head node will not be scaled down. Select **Launch** next to the `hello-world-worker` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. With this run, it should respond much faster. The _latency_ of the pipeline has improved, although the overall run time will be similar. This effect is more substantial on larger production pipelines. :::tip If you do not wish to continue paying for the head node, scale the node pool back down by replacing the original autoscale formula (`targetPoolSize = max(0, min($targetVMs, 4))`). You can also delete the compute environment in Platform, which will delete the head node. ::: ### Option 4. Use the Nextflow autopool feature **Behavior**: - Seqera will submit a Nextflow job and task to the first pool, which uses dedicated VMs. - The Nextflow job will create pools in the Azure Batch account based on the pipeline's requirements. - The pools are called `nf-pool-${id}`, where `${id}` is a unique identifier for the pool. - The pools are created with the VM size specified in the Nextflow config. - The pools are created with the autoscale settings specified in the Nextflow config. :::info Nextflow will create a range of pools based on resource sizes and try to reuse them for similar tasks. This means that if you run a process with different CPU, memory, or machineType, it will create a new pool for that process. ::: **Advantages**: - Nextflow handles the creation and management of pools. - You can create flexible pools with the correct VM size and autoscale settings. - The pools are highly configurable via Nextflow configuration. **Disadvantages**: - You may be overly specific and end up with a lot of pools, which can exhaust your quota for the maximum number of pools. With the autopool feature, Nextflow automatically creates and manages Azure Batch pools based on your pipeline's requirements. To configure your pipeline to use Nextflow autopool: 1. Duplicate the `hello-world-worker` pipeline to a new pipeline called `hello-world-autopool`. 1. Update your Nextflow config to use autopool mode: ```groovy process.queue = "auto" process.machineType = "Standard_E*d_v5" azure { batch { autoPoolMode = true allowPoolCreation = true pools { auto { autoscale = true vmCount = 1 maxVmCount = 4 } } } } ``` 3. Save the pipeline. Select **Launch** next to the `hello-world-autopool` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. ### Option 5. Use Entra authentication **Behavior**: - Seqera authenticates to Azure Batch and Azure Storage using a service principal. - It submits a job and task to the Azure Batch service using the service principal. - The task runs Nextflow, which authenticates to Azure Batch and Azure Storage using the managed identity. - All processes run on the head node as in the first example. **Advantages**: - No keys or short access tokens are exchanged, increasing security. - A service principal can have very granular permissions, so you can grant it only the permissions it needs. - Managed identities can be scoped to a specific resource, so the Nextflow head job has very restricted permissions. - Different managed IDs can have different permissions, so different compute environments can have different scoped permissions. **Disadvantages**: - The setup is quite complicated with room for error. - Errors can be harder to troubleshoot. Seqera can utilize an Azure Entra service principal to authenticate and access Azure Batch for job execution and Azure Storage for data management, and Nextflow can authenticate to Azure services using a managed identity. This method offers enhanced security compared to access keys, but must run on Azure infrastructure. See [Microsoft Entra](https://docs.seqera.io/nextflow/azure#microsoft-entra) in the Nextflow documentation for more information. #### Create a service principal for Seqera to use for authentication 1. [Create an Azure service principal](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal). 1. [Assign roles to the service principal](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal?tabs=current). 1. [Get the Service Principal ID, Tenant ID, and Client Secret](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#option-3-create-a-new-client-secret). 1. [Add to Seqera credentials](../../compute-envs/azure-batch.md#entra-service-principal-and-managed-identity) In Seqera: 1. Add new credentials with the name `entra-keys` and select the Azure **Provider**. 1. Add the Service Principal ID, Tenant ID and Client Secret. 1. Select **Create** to save the credentials. #### Create a managed identity for Nextflow to use for authentication Back in the Azure Portal: 1. [Create a managed identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp) 1. [Assign the relevant roles to the managed identity](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal?tabs=current). See [Required role assignments](https://docs.seqera.io/nextflow/azure#required-role-assignments) for Nextflow requirements. 1. Note the managed identity client ID for later. 1. In the Azure Portal, go to the Batch account you created earlier. 1. Go to the **Pools** tab and find the pool called `tower-pool-${id}`, where `${id}` is the ID of the head node pool created earlier. 1. Select **Identity**. 1. Select **Add User Assigned Identity**. 1. Select the managed identity created earlier. 1. Select **Add**. Processes running on this pool can now use the managed identity to authenticate to Azure Batch and Storage. In Seqera: 1. Add a new compute environment with the name `entra-mi` and select the Azure Batch **Provider** type. 1. For **Location**, select the same region as your Batch account. 1. For **Config mode**, select Manual. 1. For **Compute pool**, select the pool you added the managed identity to earlier (`tower-pool-${id}`). 1. For **Managed Identity Client ID**, enter the client ID of the managed identity created earlier. Duplicate the `hello-world-autopool` pipeline and save it as `hello-world-entra-mi` but use the new compute environment. Select **Launch** next to the `hello-world-entra-mi` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. The pipeline will run as before, but using the managed identity to authenticate to Azure Batch and Storage. No keys or storage required. :::note You can also use User Subscription mode instead of Batch Managed here, but this is beyond the scope of this tutorial. ::: ### Option 6. Use a node pool attached to a VNet **Behavior**: - Each node is attached to the VNet and uses the security and networking rules of that virtual network subnetwork. - All other behavior is as normal. **Advantages**: - Security can be increased by restricting the virtual network subnet. - Exchange of data can be faster and cheaper than other services. **Disadvantages**: - It requires fairly complicated setup. - If security is too restrictive, it can fail silently and be unable to report the error state. It is common to attach Azure Batch pools to a virtual network. This is useful to connect to other resources in the same VNet or place things behind enhanced security. Seqera Platform does not support this feature directly, so you must manually create an Azure Batch pool. See [Create a Nextflow-compatible Azure Batch pool](../../compute-envs/azure-batch#create-a-nextflow-compatible-azure-batch-pool) to create an Azure Batch pool manually that is compatible with Seqera and Nextflow. Use the following settings: - Name & ID: `3-azure-batch-vnet` - Add the managed identity created earlier as a user-assigned managed identity. - VMs type: `standard_e2ds_v5` - Use the autoscale formula described in the documentation, with a minimum size of 0 and a maximum size of 4. - For Virtual network, create a new virtual network with the default subnet. You can add this to a new resource group here. In practice, you are more likely to connect an Azure Batch Node pool to an existing virtual network that is connected to other resources, such as Seqera Platform or the Azure Storage Account. In this instance, connecting it to a VNet with public internet access will route the network traffic via the virtual network while still allowing you to perform every action. Back in Seqera Platform, add a new Azure Batch compute environment: 1. Add a new compute environment with the name `3-azure-batch-vnet` and select the Azure Batch **Provider** type. 1. For **Location**, select the same region as your Batch account. 1. For **Credentials**, select the service principal credentials. 1. For **Config mode**, select Manual. 1. For **Compute pool**, select the Compute pool name `3-azure-batch-vnet`. 1. For **Managed Identity Client ID**, enter the client ID of the managed identity created earlier. Duplicate the **original** `hellow-world` pipeline and save it as `hello-world-vnet`. Select **Launch** next to the `hello-world-vnet` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. The pipeline runs as before, but it will run on the node pool attached to the VNet. It will resemble a normal Azure Batch pipeline run. Using this technique allows you to run pipelines on Azure Batch with more restrictive networking and security requirements. ### Option 7. Use a node pool attached to a VNet with worker nodes attached to the same VNet **Behavior**: - We use a separate head node pool to run Nextflow, along with automatically created Nextflow autoscale pools to run processes. - Each worker node is attached to the VNet and uses the security and networking rules of that virtual network subnetwork. **Advantages**: - Security can be increased by restricting the virtual network subnet. - Exchange of data can be faster and cheaper than other services. - Additionally, you get the advantages of using worker nodes with autopools. **Disadvantages**: - The set up is very complicated now and errors are likely to occur. - Errors can be hard to troubleshoot. Finally, you can combine some of the previous approaches. Nextflow can create and modify Azure Batch pools based on the pipeline requirements. You can also attach Azure Batch pools to a VNet. Next, attach the worker nodes to the same VNet. To achieve this, the following requirements must be met: - The pipeline must be launched on the node pool attached to the VNet. - The managed identity must be used to authenticate to Azure Batch and Storage. - The managed identity must have permissions to create resources attached to the VNet. - Nextflow creates node pools attached to the VNet. Do the following: 1. Duplicate the `hello-world-entra-mi` pipeline, but modify the compute environment to `3-azure-batch-vnet` and change the pipeline name to `hello-world-vnet`. 1. Check the virtual network string under the pool details in the Azure Portal, under the **Network Configuration** section. The value should be a Subnet ID, such as `/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.Network/virtualNetworks/${vnetName}/subnets/${subnetName}`. Save this value. 1. Change the Nextflow configuration under the **Advanced** tab to include a virtual network with the autopools: ```nextflow process.queue = "auto" process.machineType = "Standard_E*d_v5" azure { batch { autoPoolMode = true allowPoolCreation = true pools { auto { autoscale = true vmCount = 1 maxVmCount = 4 virtualNetwork = '/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.Network/virtualNetworks/${vnetName}/subnets/${subnetName}' } } } } ``` Select **Launch** next to the `hello-world-vnet` pipeline in your workspace Launchpad to complete the launch form and launch the workflow. The pipeline runs as before, but using the managed identity to authenticate to Azure Batch and Storage. It also creates worker pools attached to the VNet. ### Clear up resources Once you have completed setup and workflow execution, you can delete the pipelines and compute environments from Seqera. In Azure, you can delete the Batch account, which will delete all pools, jobs, and tasks. You can then delete the Storage account. If you wish to keep the Azure resources, you can remove each pool within a Batch account and mark any active jobs as terminated to free up any quotas on your Azure Batch account. [install-azure-cli]: https://learn.microsoft.com/en-us/cli/azure/install-azure-cli [install-seqera-cli]: https://docs.seqera.io/platform-cli/installation [nextflow-working-directory]: https://docs.seqera.io/nextflow/cache-and-resume#work-directory [create-org-workspace]: ../../getting-started/workspace-setup [add-pipeline]: ../../getting-started/quickstart-demo/add-pipelines#add-from-the-launchpad --- ## Default version compatibility Seqera supports the two most recent major Seqera Platform versions (for example, 25.3.x and 26.1.x) at any given time. Each Seqera Platform version uses `nf-launcher` to set its baseline Nextflow version. To use a different Nextflow version in your pipeline runs, add a [pre-run script](../launch/advanced#pre-and-post-run-scripts) during launch. Seqera Platform may not work reliably with Nextflow versions other than the baseline. If you do not specify a Nextflow version in your configuration, Seqera Platform uses the baseline version listed in the following table: | Platform version | nf-launcher version | Nextflow version | Fusion version | Connect client version | | ---------------- | ------------------- | ---------------- | -------------- | ---------------------- | | 26.1.4 | j21-26.04 | 26.04 | 2.4 | 0.12.0 | | 26.1.3 | j21-26.04 | 26.04 | 2.4 | 0.12.0 | | 26.1.2 | j21-26.04 | 26.04 | 2.4 | 0.12.0 | | 26.1.0 | j21-26.04 | 26.04 | 2.4 | 0.12.0 | | 25.3.6 | j21-25.10.2 | 25.10.2 | 2.4 | 0.11.0 | | 25.3.4 | j21-25.10.2 | 25.10.2 | 2.4 | 0.9.0 | | 25.3.1 | j21-25.10.2 | 25.10.2 | 2.4 | 0.9.0 | | 25.3.0 | j21-25.04.8 | 25.04.8 | 2.4 | | | 25.2.4 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.2.3 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.2.2 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.2.3 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.2.1 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.1.3 | j17-24.10.9-b1 | 24.10.9 | 2.4 | | | 25.2.0 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.1.5 | j17-24.10.9-b1 | 24.10.9 | 2.4 | | | 25.1.4 | j17-24.10.9-b1 | 24.10.9 | 2.4 | | | 25.1.3 | j17-24.10.9-b1 | 24.10.9 | 2.4 | | | 25.2.3 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.2.1 | j21-25.04.3 | 25.04.3 | 2.4 | | | 25.1.3 | j17-24.10.9-b1 | 24.10.9 | 2.4 | | | 25.1.1 | j17-24.10.5 | 24.10.5 | 2.4 | | | 25.1.0 | j17-24.10.5 | 24.10.5 | 2.4 | | | 24.2.7 | j17-24.10.9-a1 | 24.10.9 | 2.4 | | | 24.2.4 | j17-24.10.4 | 24.10.4 | 2.4 | | | 24.2.1 | j17-24.10.2 | 24.10.2 | 2.4 | | | 25.1.0 | j17-24.10.5 | 24.10.5 | 2.4 | | | 24.2.7 | j17-24.10.9-a1 | 24.10.9 | 2.4 | | | 24.2.6 | j17-24.10.9-a1 | 24.10.9 | 2.4 | | | 25.1.0 | j17-24.10.5 | 24.10.5 | 2.4 | | | 24.2.7 | j17-24.10.9-a1 | 24.10.9 | 2.4 | | | 24.2.4 | j17-24.10.4 | 24.10.4 | 2.4 | | | 24.2.1 | j17-24.10.2 | 24.10.2 | 2.4 | | | 24.2.4 | j17-24.10.4 | 24.10.4 | 2.4 | | | 24.2.3 | j17-24.10.4 | 24.10.4 | 2.4 | | | 24.2.2 | j17-24.10.0 | 24.10.0 | 2.4 | | | 24.2.1 | j17-24.10.2 | 24.10.2 | 2.4 | | | 24.2.0 | j17-24.10.0 | 24.10.0 | 2.4 | | `nf-launcher` versions prefixed with `j21` use Java 21, and versions prefixed with `j17` use Java 17. --- ## Deployment options Seqera Platform is available in two deployment options: Seqera Cloud, hosted by Seqera, and Seqera Enterprise, installed in your organization's own infrastructure. You can access either deployment through the web-based user interface (UI), the API, the CLI, or directly in Nextflow. ## Platform options ### Seqera Cloud [Seqera Cloud](https://cloud.seqera.io) is the hosted deployment, recommended for users who are new to Platform and for individuals and organizations that want to set up quickly. The free tier includes up to five concurrent runs per user. Seqera Cloud Pro offers unlimited runs and dedicated support. [Contact us](https://cloud.seqera.io/demo/) for a demo to discuss your requirements. ### Seqera Enterprise [Seqera Enterprise](https://docs.seqera.io/platform-enterprise/latest/enterprise/overview) runs in your organization's own cloud or on-premises infrastructure. It includes: - Monitoring, logging, and observability - Pipeline execution Launchpad - Cloud resource provisioning - Pipeline actions and event-based execution - LDAP and OpenID authentication - Enterprise role-based access control (RBAC) - Full-featured API - Dedicated support for Nextflow and Seqera Platform To install Platform in your organization's infrastructure, [contact us](https://cloud.seqera.io/demo/) for a demo. ## Access Platform Access your Seqera instance through the UI, the API, the CLI, or in Nextflow directly with the `-with-tower` run option. ### Web-based UI 1. Create an account and sign in to Seqera Cloud at [cloud.seqera.io](https://cloud.seqera.io). :::note Login sessions remain active while the browser window is open and active. After you close the browser window, Platform signs you out within 6 hours by default. ::: 2. Create and configure a new [compute environment](../compute-envs/overview). 3. Start [launching pipelines](../launch/launchpad). ### Seqera API The Seqera API provides programmatic access to Platform. Use the API to automate operations such as launching pipelines, creating compute environments, and managing workspaces, or to integrate Platform with your existing infrastructure and tooling. Authenticate API requests with a Platform access token. See [API](https://docs.seqera.io/platform-api) for the full endpoint reference and usage details. :::tip To find the organization and workspace IDs that API endpoints use, see [Automation](./quickstart-demo/automation#find-your-organization-and-workspace-ids). ::: ### Seqera CLI The Seqera CLI (`tw`) brings Platform concepts such as pipelines and compute environments to the terminal. Launch pipelines, manage cloud resources, and administer your analyses from the command line, or define Platform resources declaratively to version and manage them as code. See [CLI](https://docs.seqera.io/platform-cli) for installation instructions and the command reference. ### Nextflow `-with-tower` If you run Nextflow directly in an existing environment, add the `-with-tower` option to your run command to use Platform capabilities: 1. Create an account and sign in to Seqera at [cloud.seqera.io](https://cloud.seqera.io). 2. In your personal workspace, go to the user menu and select **Settings** > **Your tokens**. 3. Select **Add token**. 4. Enter a unique name for your token, then select **Add**. 5. Copy and store your token securely. :::caution Platform displays the access token only once. Save the token value before you close the **Personal Access Token** window. ::: 6. Open a terminal window and create environment variables to store the Seqera access token and Nextflow version. Replace `` with your new token: ```bash export TOWER_ACCESS_TOKEN= export NXF_VER=23.10.1 ``` :::note Bearer token support requires Nextflow version 20.10.0 or later. Set the version with the `NXF_VER` environment variable. ::: 7. To submit a pipeline to a [workspace](../orgs-and-teams/workspace-management) using Nextflow, add the workspace ID to your environment: ```bash export TOWER_WORKSPACE_ID=000000000000000 ``` To find your workspace ID, select your organization in Seqera and select the **Workspaces** tab. 8. Run your Nextflow pipeline with the `-with-tower` option: ```bash nextflow run main.nf -with-tower ``` Replace `main.nf` with the filename of your Nextflow script. You can now monitor your runs in the Seqera UI. To configure and run Nextflow pipelines in cloud environments, see [compute environments](../compute-envs/overview). :::tip For additional run configuration options using Nextflow configuration files, see the [Nextflow documentation](https://docs.seqera.io/nextflow/config.html?highlight=tower#scope-tower). ::: --- ## Run a pipeline On this page, learn how to run a pipeline with sample data and get started running your own pipelines. :::tip [**Sign up**](https://cloud.seqera.io/login "Seqera Platform") to try Seqera for free, or request a [**demo**](https://seqera.io/demo/ "Seqera Platform Demo") for deployments in your own on-premises or cloud environment. ::: The Community Showcase [Launchpad](../launch/launchpad) is an example workspace provided by Seqera. The showcase is pre-configured with compute environments, credentials, and pipelines to start running Nextflow workflows immediately. A pipeline consists of a pre-configured workflow repository, compute environment (with 100 free CPU hours), and launch parameters. The Community Showcase comes pre-loaded with two AWS Batch compute environments to run showcase pipelines. ### Components - [Datasets](../data/datasets) are collections of versioned, structured data (usually in the form of a samplesheet) in CSV or TSV format. A dataset is used as the input for a pipeline run. Sample datasets are used in pipelines with the same name, e.g., the *nf-core-rnaseq-test* dataset is used as input when you run the *nf-core-rnaseq* pipeline. - [Compute environments](../compute-envs/overview) are the platforms where workflows are executed. A compute environment consists of access credentials, configuration settings, and storage options for the environment. - [Credentials](../credentials/overview) are the authentication keys Seqera uses to access compute environments, private code repositories, and external services. Credentials are SHA-256 encrypted before secure storage. The Community Showcase includes all the credentials you need to run pipelines in the included AWS Batch compute environments. - [Secrets](../secrets/overview) are retrieved and used during pipeline execution. In your private or organization workspace, you can store the access keys, licenses, or passwords required for your pipeline execution to interact with third-party services. The secrets included in the Community Showcase contain license keys to run *nf-dragen* and *nf-sentieon* pipelines in the Showcase compute environments. ## Run a pipeline with sample data 1. From the [Launchpad](../launch/launchpad), select a pipeline to view the pipeline detail page. *nf-core-rnaseq* is a good first pipeline example. 2. Optional: Select the URL under **Workflow repository** to view the pipeline code repository in another tab. 3. Select **Launch** from the pipeline detail page. 4. On the **Launch pipeline** page, enter a unique **Workflow run name** or use the pre-filled random name. 5. Optional: Enter labels to be assigned to the run in the **Labels** field. 6. Under **Input/output options**, select the dataset named after your chosen pipeline from the drop-down under **input**. 7. Under **outdir**, specify an output directory where run results will be saved. This must be an absolute path to storage on cloud infrastructure and defaults to `./results`. 8. Under **email**, enter an email address where you wish to receive the run completion summary. 9. Under **multiqc_title**, enter a title for the MultiQC report. This is used as both the report page header and filename. The remaining launch form fields will vary depending on the pipeline you have selected. Parameters required for the pipeline to run are pre-filled by default, and empty fields are optional. Once you've filled the necessary launch form details, select **Launch**. Your new run will be displayed at the top of the list in the **Runs** tab with a **submitted** status. Select the run name to navigate to the run detail page and view the configuration, parameters, status of individual tasks, and run report. ## Run your own pipelines To run pipelines on your own infrastructure, you first need to create your own organization. * [Organizations](../orgs-and-teams/organizations) are the top-level structure in Platform. They contain the building blocks of your organizational infrastructure. * [Workspaces](../orgs-and-teams/workspace-management) are where resources are managed. All team members can access the organization workspace. In addition to this, each user has a unique personal workspace to manage resources such as pipelines, compute environments, and credentials. * [Teams](../orgs-and-teams/organizations) are collections of members. * [Members](../orgs-and-teams/organizations#members) belong to an organization and can have different levels of access across workspaces. You can create multiple workspaces within an organization context and associate each of these workspaces with dedicated teams of users, while providing fine-grained access control for each of the teams. See [Workspaces](../orgs-and-teams/workspace-management) for more information. --- ## Protein structure prediction This guide details how to perform best-practice analysis for protein 3D structure prediction on an AWS Batch compute environment in Platform. It includes: - Creating AWS Batch compute environments to run your pipeline and downstream analysis - Adding the *nf-core/proteinfold* pipeline to your workspace - Importing your pipeline input data - Launching the pipeline and monitoring execution from your workspace - Setting up a custom analysis environment with Studios :::info[**Prerequisites**] You will need the following to get started: - [Admin](../orgs-and-teams/roles) permissions in an existing organization workspace. See [Set up your workspace](./workspace-setup) to create an organization and workspace from scratch. - An existing AWS cloud account with access to the AWS Batch service. - Existing access credentials with permissions to create and manage resources in your AWS account. See [IAM](../compute-envs/aws-batch#required-platform-iam-permissions) for guidance to set up IAM permissions for Platform. ::: ## Compute environment The compute and storage requirements for protein structure prediction depend on the number and length of protein sequences being analyzed and the size of the database used for prediction by the deep learning models, such as AlphaFold2 and ColabFold. Input sequences typically range from a few kilobytes for single proteins to several megabytes for large datasets, and reference databases can be extremely large, from 100 GB to several TB. Protein folding pipelines generate intermediate files during execution, such as for alignments and feature representations, the sizes of which vary based on the number of sequences and the complexity of the analysis. Given the data sizes and computational intensity, production pipelines perform best with NVIDIA A10 or larger GPUs and low-latency, high-throughput cloud storage file handling. ### GPUs The *nf-core/proteinfold* pipeline performs protein folding prediction using one of three deep learning models: AlphaFold2, ColabFold, or ESMFold. The computationally intensive tasks for protein structure prediction perform better on GPUs due to their ability to handle large matrix operations efficiently and perform parallel computations. GPUs can dramatically reduce the time required for protein structure predictions, making it feasible to analyze larger datasets or perform more complex simulations. Platform supports the allocation of both CPUs and GPUs in the same compute environment. For example, specify `m6id`, `c6id`, `r6id`, `g5`, `p3` instance families in the **Instance types** field when creating your AWS Batch compute environment. See [Create compute environment](#create-compute-environment) below. When you launch *nf-core/proteinfold* in Platform, enable **use_gpu** to instruct Nextflow to run GPU-compatible pipeline processes on GPU instances. See [Launch pipeline](#launch-pipeline) below. ### Fusion file system The [Fusion](../supported_software/fusion/overview) file system enables seamless read and write operations to cloud object stores, leading to simpler pipeline logic and faster, more efficient execution. While Fusion is not required to run *nf-core/proteinfold*, it significantly enhances I/O-intensive tasks and eliminates the need for intermediate data copies, which is particularly beneficial when working with the large databases used by deep learning models for prediction. Fusion works best with AWS NVMe instances (fast instance storage) as this delivers the fastest performance when compared to environments using only AWS EBS (Elastic Block Store). Batch Forge selects instances automatically based on your compute environment configuration, but you can optionally specify instance types. To enable fast instance storage, you must select EC2 instances with NVMe SSD storage (`g4dn`, `g5`, or `P3` families or greater). :::note Fusion requires a license for use in Seqera Platform compute environments or directly in Nextflow. See [Fusion licensing](https://docs.seqera.io/fusion/licensing) for more information. ::: ### Create compute environment :::info The same compute environment can be used for pipeline execution and running your Studios notebook environment, but Studios does not support AWS Fargate. To use this compute environment for both *nf-core/proteinfold* execution and your Studio, leave **Enable Fargate for head job** disabled and include a CPU-based EC2 instance family (`c6id`, `r6id`, etc.) in your **Instance types**. Alternatively, create a second basic AWS Batch compute environment and a Studio with at least 2 CPUs and 8192 MB of RAM. ::: From the **Compute Environments** tab in your organization workspace, select **Add compute environment** and complete the following fields: | **Field** | **Description** | |---------------------------------------|------------------------------------------------------------| | **Name** | A unique name for the compute environment. | | **Platform** | AWS Batch | | **Credentials** | Select existing credentials, or **+** to create new credentials.| | **Access Key** | AWS access key ID. | | **Secret Key** | AWS secret access key. | | **Region** | The target execution region. | | **Work directory** | An S3 bucket path in the same execution region. | | **Enable Wave Containers** | Use the Wave containers service to provision containers. | | **Enable Fusion v2** | Access your S3-hosted data via the Fusion v2 file system. | | **Enable fast instance storage** | Use NVMe instance storage to speed up I/O and disk access. Requires Fusion v2.| | **Config Mode** | Batch Forge | | **Provisioning Model** | Choose between Spot and On-demand instances. | | **Max CPUs** | Sensible values for production use range between 2000 and 5000.| | **Enable Fargate for head job** | Run the Nextflow head job using the Fargate container service to speed up pipeline launch. Requires Fusion v2. Do not enable for Studios compute environments. | | **Use Amazon-recommended GPU-optimized ECS AMI** | When enabled, Batch Forge specifies the most current AWS-recommended GPU-optimized ECS AMI as the EC2 fleet AMI when creating the compute environment. | | **Allowed S3 buckets** | Additional S3 buckets or paths to be granted read-write permission for this compute environment. For the purposes of this guide, add `s3://proteinfold-dataset` to grant compute environment access to the DB and params used for prediction by AlphaFold2 and ColabFold. | | **Instance types** | Specify the instance types to be used for computation. You must include GPU-enabled instance types (`g4dn`, `g5`) when the Amazon-recommended GPU-optimized ECS AMI is in use. Include CPU-based instance families for Studios compute environments. | | **Resource labels** | `name=value` pairs to tag the AWS resources created by this compute environment.| ![Create AWS Batch compute environment](./_images/pf-ce.gif) ## Add pipeline to Platform :::info The [nf-core/proteinfold](https://github.com/nf-core/proteinfold) pipeline is a bioinformatics best-practice analysis pipeline for Protein 3D structure prediction. ![nf-core/proteinfold subway map](./_images/nf-core-proteinfold_metro_map_1.1.0.png) ::: [Seqera Pipelines](https://seqera.io/pipelines) is a curated collection of quality open source pipelines that can be imported directly to your workspace Launchpad in Platform. Each pipeline includes a curated test dataset to use in a test run to confirm compute environment compatibility in just a few steps. To use Seqera Pipelines to import the *nf-core/proteinfold* pipeline to your workspace: ![Seqera Pipelines add to Launchpad](./_images/pipelines-add-pf.gif) 1. Search for *nf-core/proteinfold* and select **Launch** next to the pipeline name in the list. In the **Add pipeline** tab, select **Cloud** or **Enterprise** depending on your Platform account type, then provide the information needed for Seqera Pipelines to access your Platform instance: - **Seqera Cloud**: Paste your Platform **Access token** and select **Next**. - **Seqera Enterprise**: Specify the **Seqera Platform URL** (hostname) and **Base API URL** for your Enterprise instance, then paste your Platform **Access token** and select **Next**. :::tip If you do not have a Platform access token, select **Get your access token from Seqera Platform** to open the Access tokens page in a new browser tab. ::: 1. Select your Platform **Organization**, **Workspace**, and **Compute environment** for the imported pipeline. 1. (Optional) Customize the **Pipeline Name** and **Pipeline Description**. 1. Select **Add Pipeline**. :::info To add a custom pipeline not listed in Seqera Pipelines to your Platform workspace, see [Add pipelines](./quickstart-demo/add-pipelines#) for manual Launchpad instructions. ::: ## Pipeline input data The [nf-core/proteinfold](https://github.com/nf-core/proteinfold) pipeline works with input datasets (samplesheets) containing sequence names and FASTA file locations (paths to FASTA files in cloud or local storage). The pipeline includes an example samplesheet that looks like this:
**nf-core/proteinfold example samplesheet** | sequence | fasta | | -------- | ----- | | T1024 | https://raw.githubusercontent.com/nf-core/test-datasets/proteinfold/testdata/sequences/T1024.fasta | | T1026 | https://raw.githubusercontent.com/nf-core/test-datasets/proteinfold/testdata/sequences/T1026.fasta |
In Platform, samplesheets and other data can be made easily accessible in one of two ways: - Use **Data Explorer** to browse and interact with remote data from AWS S3, Azure Blob Storage, and Google Cloud Storage repositories, directly in your organization workspace. - Use **Datasets** to upload structured data to your workspace in CSV (Comma-Separated Values) or TSV (Tab-Separated Values) format.
**Add a cloud bucket via Data Explorer** Private cloud storage buckets accessible with the credentials in your workspace are added to Data Explorer automatically by default. However, you can also add custom directory paths within buckets to your workspace to simplify direct access. For example, to add the proteinfold open database to your workspace: ![Add public bucket](./_images/data-explorer-add-proteinfold.gif) 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - The cloud **Provider**: AWS - An existing cloud **Bucket path**: `s3://proteinfold-dataset` - A unique **Name** for the bucket: "proteinfold-dataset" - The **Credentials** used to access the bucket: select **Public**. - An optional bucket **Description**. 1. Select **Add**. You can now select data directly from this bucket as input when launching your pipeline, without the need to interact with cloud consoles or CLI tools.
**Add a dataset** From the **Datasets** tab, select **Add Dataset**. ![Add a dataset](./_images/proteinfold-dataset.gif) Specify the following dataset details: - A **Name** for the dataset, such as `proteinfold_samplesheet`. - A **Description** for the dataset. - Select the **First row as header** option to prevent Platform from parsing the header row of the samplesheet as sample data. - Select **Upload file** and browse to your CSV or TSV samplesheet file in local storage, or simply drag and drop it into the box. The dataset is now listed in your organization workspace datasets and can be selected as input when launching your pipeline. :::info Platform does not store the data used for analysis in pipelines. The dataset must specify the locations of data stored on your own infrastructure. :::
## Launch pipeline :::note This guide is based on [version 1.1.1](https://nf-co.re/proteinfold/1.1.1) of the nf-core/proteinfold pipeline. Launch form parameters and tools may differ in other versions. ::: With your compute environment created, *nf-core/proteinfold* added to your workspace Launchpad, and your samplesheet accessible in Platform, you are ready to launch your pipeline. Navigate to the Launchpad and select **Launch** next to *nf-core-proteinfold* to open the launch form. The launch form consists of **General config**, **Run parameters**, and **Advanced options** sections to specify your run parameters before execution, and an execution summary. Use section headings or select the **Previous** and **Next** buttons at the bottom of the page to navigate between sections. ### General config - **Pipeline to launch**: The pipeline Git repository name or URL: `https://github.com/nf-core/proteinfold`. For saved pipelines, this is prefilled and cannot be edited. - **Revision**: A valid repository commit ID, tag, or branch name: `1.1.1`. For saved pipelines, this is prefilled and cannot be edited. - **Config profiles**: One or more [configuration profile](https://docs.seqera.io/nextflow/config#config-profiles) names to use for the execution. Config profiles must be defined in the `nextflow.config` file in the pipeline repository. Benchmarking runs for this guide used nf-core profiles with included test datasets — `test_full_alphafold2_multimer` for Alphafold2 and `test_full_alphafold2_multimer` for Colabfold. - **Workflow run name**: An identifier for the run, pre-filled with a random name. This can be customized. - **Labels**: Assign new or existing [labels](../labels/overview) to the run. - **Compute environment**: Your AWS Batch compute environment. - **Work directory**: The cloud storage path where pipeline scratch data is stored. Platform will create a scratch sub-folder if only a cloud bucket location is specified. :::note The credentials associated with the compute environment must have access to the work directory. ::: ![General config tab](./_images/proteinfold-lf1.gif) ### Run parameters There are three ways to enter **Run parameters** prior to launch: - The **Input form view** displays form fields to enter text or select attributes from lists, and browse input and output locations with [Data Explorer](../data/data-explorer). - The **Config view** displays raw configuration text that you can edit directly. Select JSON or YAML format from the **View as** list. - **Upload params file** allows you to upload a JSON or YAML file with run parameters. Platform uses the `nextflow_schema.json` file in the root of the pipeline repository to dynamically create a form with the necessary pipeline parameters. ![Run parameters](./_images/proteinfold-lf2.gif) Specify your pipeline input and output and modify other pipeline parameters as needed.
**input** Use **Browse** to select your pipeline input data: - In the **Data Explorer** tab, select the existing cloud bucket that contains your samplesheet, browse or search for the samplesheet file, and select the chain icon to copy the file path before closing the data selection window and pasting the file path in the input field. - In the **Datasets** tab, search for and select your existing dataset.
**outdir** Use the `outdir` parameter to specify where the pipeline outputs are published. `outdir` must be unique for each pipeline run. Otherwise, your results will be overwritten. **Browse** and copy cloud storage directory paths using Data Explorer, or enter a path manually.
- The **mode** menu allows you to select the deep learning model used for structure prediction (`alphafold2`, `colabfold`, or `esmfold`). - Enable **use_gpu** to run GPU-compatible tasks on GPUs. This requires **Use Amazon-recommended GPU-optimized ECS AMI** to be enabled and GPU-enabled instances to be specified under **Instance types** in your compute environment. ![Mode options](./_images/proteinfold-mode.gif) :::info For the purposes of this guide, run the pipeline in both `alphafold2` and `colabfold` modes. Specify unique directory paths for the `outdir` parameter (such as "Alphafold2" and "ColabFold") to ensure output data is kept separate and not overwritten. Predicted protein structures for each model will be visualized side-by-side in the [Interactive analysis](#interactive-analysis-with-studios) section. ::: ### Advanced settings - Use [resource labels](../resource-labels/overview) to tag the computing resources created during the workflow execution. While resource labels for the run are inherited from the compute environment and pipeline, workspace admins can override them from the launch form. Applied resource label names must be unique. - [Pipeline secrets](../secrets/overview) store keys and tokens used by workflow tasks to interact with external systems. Enter the names of any stored user or workspace secrets required for the workflow execution. - See [Advanced options](../launch/advanced) for more details. After you have filled the necessary launch details, select **Launch**. The **Runs** tab shows your new run in a **submitted** status at the top of the list. Select the run name to navigate to the [**View Workflow Run**](../monitoring/overview) page and view the configuration, parameters, status of individual tasks, and run report.
**Run monitoring** Select your new run from the **Runs** tab list to view the run details. #### Run details page As the pipeline runs, run details will populate with the following tabs: - **Command-line**: The Nextflow command invocation used to run the pipeline. This includes details about the pipeline version (`-r` flag) and profile, if specified (`-profile` flag). - **Parameters**: The exact set of parameters used in the execution. This is helpful for reproducing the results of a previous run. - **Resolved Nextflow configuration**: The full Nextflow configuration settings used for the run. This includes parameters, but also settings specific to task execution (such as memory, CPUs, and output directory). - **Execution Log**: A summarized Nextflow log providing information about the pipeline and the status of the run. - **Datasets**: Link to datasets, if any were used in the run. - **Reports**: View pipeline outputs directly in the Platform. ![View the nf-core/rnaseq run](./_images/pf-run-details.gif) #### View reports Most Nextflow pipelines generate reports or output files which are useful to inspect at the end of the pipeline execution. Reports can contain quality control (QC) metrics that are important to assess the integrity of the results. The paths to report files point to a location in cloud storage (in the `outdir` directory specified during launch), but you can view the contents directly and download each file without navigating to the cloud or a remote filesystem. :::info See [Reports](../reports/overview) for more information. ::: #### View general information The run details page includes general information about who executed the run, when it was executed, the Git commit ID and/or tag used, and additional details about the compute environment and Nextflow version used. ![General run information](./_images/pf-run-details-general.gif) #### View details for a task Scroll down the page to view: - The progress of individual pipeline **Processes** - **Aggregated stats** for the run (total walltime, CPU hours) - **Workflow metrics** (CPU efficiency, memory efficiency) - A **Task details** table for every task in the workflow The task details table provides further information on every step in the pipeline, including task statuses and metrics. #### Task details Select a task in the task table to open the **Task details** dialog. The dialog has three tabs: - The **About** tab contains extensive task execution details. - The **Execution log** tab provides a real-time log of the selected task's execution. Task execution and other logs (such as stdout and stderr) are available for download from here, if still available in your compute environment. - The **Data Explorer** tab allows you to view the task working directory directly in Platform. ![Task details window](./_images/pf-task-details.gif) Nextflow hash-addresses each task of the pipeline and creates unique directories based on these hashes. Data Explorer allows you to view the log files and output files generated for each task in its working directory, directly within Platform. You can view, download, and retrieve the link for these intermediate files in cloud storage from the **Data Explorer** tab to simplify troubleshooting.
## Interactive analysis with Studios [Studios](../studios/overview) streamlines the process of creating interactive analysis environments for Platform users. With built-in templates for platforms like Jupyter Notebook, RStudio, and VS Code, creating a data studio is as simple as adding and sharing pipelines or datasets. The Studio URL can also be shared with any user with the [Connect role](../orgs-and-teams/roles) for real-time access and collaboration. For the purposes of this guide, a Jupyter notebook environment will be used for interactive visualization of the predicted protein structures, optionally comparing AlphaFold2 and Colabfold structures for the same sequence data. ### Create a Jupyter Notebook studio From the **Studios** tab, select **Add a Studio** and complete the following: - In the **Compute & Data** tab: - Select your AWS Batch compute environment. :::info The same compute environment can be used for pipeline execution and running your Studio, but Studios does not support AWS Fargate and data studio sessions must run on CPUs. To use one compute environment for both *nf-core/proteinfold* execution and your Studio, leave **Enable Fargate for head job** disabled and include at least one CPU-based EC2 instance family (`c6id`, `r6id`, etc.) in your **Instance types**. Alternatively, create a second basic AWS Batch compute environment with at least 2 CPUs and 8192 MB of RAM for your data studio. ::: - Optional: Enter CPU and memory allocations. The default values are 2 CPUs and 8192 MB memory (RAM). :::note Studios compete for computing resources when sharing compute environments. Ensure your compute environment has sufficient resources to run both your pipelines and studio sessions. ::: - Mount data using Data Explorer: Mount the S3 bucket or directory path that contains the work directory of your Proteinfold run. - In the **General config** tab: - Select the latest **Jupyter** container image template from the list. - Optional: Enter a unique name and description for the Studio. - Check **Install Conda packages** and paste the following Conda environment YAML snippet: ```yaml channels: - bioconda - conda-forge dependencies: - python=3.10 - conda-forge::biopython=1.84 - conda-forge::nglview=3.1.2 - conda-forge::ipywidgets=8.1.5 ``` - Confirm the Studio details in the **Summary** tab - Select **Add** and choose whether to add and start the Studio immediately. - When the Studio is created and in a running state, **Connect** to it. ![Add Studio](./_images/add-s-pf.gif) ### Visualize protein structures The Jupyter environment can be configured with the packages and scripts you need for interactive analysis. For the purposes of this guide, run the following scripts in individual code cells to install the necessary packages and perform visualization: 1. Import libraries and check versions: ```python print(f"Python version: {sys.version}") print(f"Jupyter version: {jupyter_core.__version__}") print(f"nglview version: {nglview.__version__}") print(f"ipywidgets version: {ipywidgets.__version__}") print(f"Biopython version: {Bio.__version__}") print(f"Operating system: {sys.platform}") print("All required libraries imported successfully.") ``` 1. Define visualization functions: ```python from IPython.display import display, HTML def visualize_protein(pdb_file, width='400px', height='400px'): view = nglview.show_structure_file(pdb_file) view.add_representation('cartoon', selection='protein', color='residueindex') view.add_representation('ball+stick', selection='hetero') view._remote_call('setSize', target='Widget', args=[width, height]) # Set initial view view._remote_call('autoView') view._remote_call('centerView') # Adjust zoom level (you may need to adjust this value) view._remote_call('zoom', target='stage', args=[0.8]) return view def compare_proteins(pdb_files): views = [] for method, file_path in pdb_files.items(): if os.path.exists(file_path): view = visualize_protein(file_path) label = widgets.Label(method) views.append(widgets.VBox([label, view])) return widgets.HBox(views, layout=widgets.Layout(width='100%')) print("Visualization functions defined successfully.") ``` 1. Set up file paths and create file dictionary: ```python # Replace with the actual paths to your AlphaFold2 and ColabFold PDB files alphafold_pdb = "data/path/to/your/alphafold/output.pdb" colabfold_pdb = "data/path/to/your/colabfold/output.pdb" # Create a dictionary of files pdb_files = { "AlphaFold": alphafold_pdb, "ColabFold": colabfold_pdb } print("File paths set up successfully.") ``` 1. Display file information: ```python display(HTML("Protein Structure Prediction Output Files:")) for method, file_path in pdb_files.items(): if os.path.exists(file_path): display(HTML(f"{method}: {file_path}")) else: display(HTML(f"{method}: File not found at {file_path}")) ``` 1. Visualize structures: ```python valid_pdb_files = {method: file_path for method, file_path in pdb_files.items() if os.path.exists(file_path)} if valid_pdb_files: display(HTML("Protein Structure Visualization:")) comparison = compare_proteins(valid_pdb_files) display(comparison) else: display(HTML("No valid PDB files found. Please check the file paths and ensure that the files exist.")) ``` 1. Add interactive elements: ```python if valid_pdb_files: method_drop-down = widgets.Drop-down( options=[method for method, file in valid_pdb_files.items()], description='Select method:', disabled=False, ) info_output = widgets.Output() def on_change(change): with info_output: info_output.clear_output() selected_method = change['new'] selected_file = valid_pdb_files[selected_method] print(f"Selected method: {selected_method}") print(f"File path: {selected_file}") print(f"File size: {os.path.getsize(selected_file) / 1024:.2f} KB") method_drop-down.observe(on_change, names='value') display(HTML("Structure Information:")) display(widgets.VBox([method_drop-down, info_output])) ``` 1. Display usage instructions: ```python display(HTML(""" How to use this visualization: The protein structures from AlphaFold and ColabFold are shown side-by-side above. You can interact with each structure independently: Click and drag to rotate the structure. Scroll to zoom in and out. Right-click and drag to translate the structure. Use the drop-down to select a specific method and view its file information. """)) ``` ![Protein structure visualization](./_images/protein-structure-visualization.gif) --- ## Add data Most bioinformatics pipelines require input data, typically a samplesheet where each row consists of a sample, the location of files for that sample (such as FASTQ files), and other sample details. Reliable shared access to pipeline input data simplifies data management, reduces data-input errors, and supports reproducible workflows. In Platform, you can make samplesheets and other data accessible in two ways: - Use **Data Explorer** to browse and interact with remote data from AWS S3, Azure Blob Storage, and Google Cloud Storage repositories, directly in your organization workspace. - Use **Datasets** to upload structured data to your workspace in CSV (Comma-Separated Values) or TSV (Tab-Separated Values) format. ## Data Explorer For pipeline runs in the cloud, users typically need access to buckets or blob storage to upload files (such as samplesheets and reference data) and to view pipeline results. Managing credentials and permissions for multiple users, and training them to navigate cloud consoles and CLIs, adds overhead. Data Explorer lets you view your data directly in Platform instead. ### Add a cloud bucket Private cloud storage buckets accessible by the [credentials](../../credentials/overview) in your workspace are added to Data Explorer automatically by default. However, you can also add custom directory paths within buckets to your workspace to simplify direct access. To add individual buckets (or directory paths within buckets): 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - The cloud **Provider**. - An existing cloud **Bucket path**. - A unique **Name** for the bucket. - The **Credentials** used to access the bucket. For public cloud buckets, select **Public** from the drop-down. - An optional bucket **Description**. 1. Select **Add**. You can now use this data in your analysis without interacting with cloud consoles or CLI tools. #### Public data sources Select **Public** from the credentials drop-down to add public cloud storage buckets from resources such as: - [The Cancer Genome Atlas (TCGA)](https://registry.opendata.aws/tcga/) - [1000 Genomes Project](https://registry.opendata.aws/1000-genomes/) - [NCBI SRA](https://registry.opendata.aws/ncbi-sra/) - [Genome in a Bottle Consortium](https://registry.opendata.aws/giab/) - [MSSNG Database](https://research.mss.ng/) - [Genome Aggregation Database (gnomAD)](https://gnomad.broadinstitute.org/) ### View pipeline outputs In Data Explorer, you can: - **View bucket details**: Select the information icon next to a bucket in the list to view the cloud provider, bucket address, and credentials. - **View bucket contents**: Select a bucket name from the list to view the bucket contents. The file type, size, and path of objects are displayed in columns next to the object name. For example, view the outputs of your [nf-core/rnaseq](../../quickstart.md#nf-corernaseq) run. - **Preview files**: Select a file to open a preview window that includes a **Download** button. For example, view the gene counts from the salmon quantification step of your [nf-core/rnaseq](../../quickstart.md#nf-corernaseq) run. ## Datasets Datasets in Platform are CSV (comma-separated values) and TSV (tab-separated values) files stored in a workspace. You can select stored datasets as input data when launching a pipeline.
**Example: nf-core/rnaseq test samplesheet** The [*nf-core/rnaseq*](https://github.com/nf-core/rnaseq) pipeline works with input datasets (samplesheets) containing sample names, FASTQ file locations, and indications of strandedness. The Seqera Community Showcase sample dataset for *nf-core/rnaseq* specifies the paths to seven small sub-sampled FASTQ files from a yeast RNAseq dataset: **Example nf-core/rnaseq dataset** | sample | fastq_1 | fastq_2 | strandedness | | ------------------- | ------------------------------------ | ------------------------------------ | ------------ | | WT_REP1 | s3://nf-core-awsmegatests/rnaseq/... | s3://nf-core-awsmegatests/rnaseq/... | reverse | | WT_REP1 | s3://nf-core-awsmegatests/rnaseq/... | s3://nf-core-awsmegatests/rnaseq/... | reverse | | WT_REP2 | s3://nf-core-awsmegatests/rnaseq/... | s3://nf-core-awsmegatests/rnaseq/... | reverse | | RAP1_UNINDUCED_REP1 | s3://nf-core-awsmegatests/rnaseq/... | | reverse | | RAP1_UNINDUCED_REP2 | s3://nf-core-awsmegatests/rnaseq/... | | reverse | | RAP1_UNINDUCED_REP2 | s3://nf-core-awsmegatests/rnaseq/... | | reverse | | RAP1_IAA_30M_REP1 | s3://nf-core-awsmegatests/rnaseq/... | s3://nf-core-awsmegatests/rnaseq/... | reverse |
Download the nf-core/rnaseq [samplesheet_test.csv](samplesheet_test.csv). ### Add a dataset From the **Datasets** tab, select **Add Dataset**. Specify the following dataset details: - A **Name** for the dataset, such as `nf-core-rnaseq-test-dataset`. - A **Description** for the dataset. - Select the **First row as header** option to prevent Platform from parsing the header row of the samplesheet as sample data. - Select **Upload file** and browse to your CSV or TSV file in local storage, or drag and drop it into the box. The file locations in the *nf-core/rnaseq* example dataset point to a path on S3. This could also be a path to a shared filesystem if you use an HPC compute environment. Nextflow uses these paths to stage the files into the task working directory. :::info Platform does not store the data used for analysis in pipelines. The datasets must provide the locations of data that is stored on your own infrastructure. ::: --- ## Add pipelines The Launchpad lists the preconfigured Nextflow pipelines that you can run on the [compute environments](../../compute-envs/overview) in your workspace. You can import pipelines to your workspace Launchpad in two ways: directly from Seqera Pipelines, or manually with **Add pipeline** in Seqera Platform. ## Import from Seqera Pipelines [Seqera Pipelines](https://seqera.io/pipelines) is a curated collection of open-source pipelines that you can import directly to your workspace Launchpad. Each pipeline includes a dataset for a test run that confirms compute environment compatibility. To import a pipeline: 1. Select **Launch** next to the pipeline name in the list. In the **Add pipeline** tab, select **Cloud** or **Enterprise** depending on your Platform account type, then provide the information needed for Seqera Pipelines to access your Platform instance: - **Seqera Cloud**: Paste your Platform **Access token** and select **Next**. - **Seqera Enterprise**: Specify the **Seqera Platform URL** (hostname) and **Base API URL** for your Enterprise instance, then paste your Platform **Access token** and select **Next**. :::note If you do not have a Platform access token, select **Get your access token from Seqera Platform** to open the Access tokens page in a new browser window. ::: 1. Select the Platform **Organization**, **Workspace**, and **Compute environment** for the imported pipeline. 1. (Optional) Customize the **Pipeline Name** and **Pipeline Description**. :::note Pipeline names must be unique per workspace. ::: 1. Select **Add Pipeline**. ## Add from the Launchpad From your workspace Launchpad, select **Add Pipeline** and specify the following pipeline details: - (Optional) **Image**: Select the **Edit** icon on the pipeline image to open the **Edit image** window. From here, select **Upload file** to browse for an image file, or drag and drop the image file directly. Images must be in JPG or PNG format, with a maximum file size of 200 KB. :::note You can upload custom icons when adding or updating a pipeline. If no user-uploaded icon is defined, Platform retrieves and attaches a pipeline icon in the following order of precedence: 1. A valid `icon` key:value pair defined in the `manifest` object of the `nextflow.config` file. 2. The GitHub organization avatar (if the repository is hosted on GitHub). 3. If none of the above are defined, Platform auto-generates and attaches a pipeline icon. ::: - **Name**: A custom name of your choice. Pipeline names must be unique per workspace. - (Optional) **Description**: A summary of the pipeline, or any information useful to workspace participants when they select a pipeline to launch. - (Optional) **Labels**: Categorize the pipeline by criteria such as research group or reference genome version to help workspace participants select the right pipeline for their analysis. - **Compute environment**: Select an existing workspace [compute environment](../../compute-envs/overview). - **Pipeline to launch**: The URL of any public or private Git repository that contains Nextflow source code. - **Revision**: A valid repository commit ID, tag, or branch name. Determines the version of the pipeline to launch. :::tip Selecting a specific pipeline version is important for reproducibility. Each run with the same input data then generates the same results. ::: - **Commit ID**: Pin pipeline revision to the most recent HEAD commit ID. If no commit ID is pinned, the latest revision of the repository branch or tag is used. - **Pull latest**: Fetch the most recent HEAD commit ID of the pipeline revision at launch time. Unpins the **Commit ID**, if set. :::info See [Git revision management](../../pipelines/revision.md) for more information on **Commit ID**, **Pull latest**, and **Revision** behavior. ::: - (Optional) **Config profiles**: Select a predefined profile for the Nextflow pipeline. :::info nf-core pipelines include a `test` profile that is associated with a minimal test dataset. This profile runs the pipeline with heavily sub-sampled input data for the purposes of [CI/CD](https://resources.github.com/devops/ci-cd/) and to quickly confirm that the pipeline runs on your infrastructure. ::: - (Optional) **Pipeline parameters**: Set custom pipeline parameters that are prepopulated when users launch the pipeline from the Launchpad. For example, set the path to local reference genomes so users don't need to locate these files at launch. - (Optional) **Pre-run script**: Define Bash code that executes before the pipeline launches in the same environment where Nextflow runs. :::info Pre-run scripts are useful for defining executor settings, troubleshooting, and defining a specific version of Nextflow with the `NXF_VER` environment variable. ::: :::note Workspace participants with the necessary [permissions](../../orgs-and-teams/roles) can override pre-filled pipeline settings (such as compute environment, config profiles, and pipeline parameters) during pipeline launch. ::: After you fill in the fields, select **Add**. Your pipeline is now available for workspace participants to launch in the preconfigured compute environment. --- ## Automation Seqera Platform provides several programmatic interfaces to automate pipeline execution, chain pipelines together, and integrate Platform with third-party services. ## Platform API The Seqera Platform public API is the lowest-level programmatic interface. It can perform every operation available in the user interface. Use the API to launch pipelines in response to a file event (such as a file upload to a bucket) or the completion of a previous run. The API is available at `https://api.cloud.seqera.io`. The full list of endpoints is available in Seqera's [OpenAPI schema](https://cloud.seqera.io/openapi/index.html). Every API request requires an authentication token. Create one from your user menu under **Your tokens**. The token is displayed only once. Store it securely and use it to authenticate API requests.
**Example pipeline launch API request** ``` curl -X POST "https://api.cloud.seqera.io/workflow/launch?workspaceId=38659136604200" \ -H "Accept: application/json" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept-Version:1" \ -d '{ "launch": { "computeEnvId": "hjE97A8TvD9PklUb0hwEJ", "runName": "first-time-pipeline-api-byname", "pipeline": "first-time-pipeline", "workDir": "s3://nf-ireland", "revision": "master" } }' ```
### Find your organization and workspace IDs Many API endpoints take an organization ID (for example, `org/{orgId}/workspaces`) or a workspace ID (for example, the `workspaceId` query parameter). The two are different numeric values: a workspace ID used where an endpoint expects an organization ID returns a permission error. - **Organization ID**: Select your organization, then **Settings**. The organization ID is the numeric value in the page URL. - **Workspace ID**: Select your organization, then the **Workspaces** tab. Each workspace lists its ID. To retrieve these IDs from the command line, use `tw organizations list` and `tw workspaces list`. ## Platform CLI For bioinformaticians and scientists who prefer the command line, Platform provides `tw`, a command-line tool to manage resources. Use the CLI to launch pipelines, manage compute environments, retrieve run metadata, and monitor runs on Platform. It provides a Nextflow-like experience and lets you store Seqera resource configuration, such as pipelines and compute environments, as code. The CLI is built on the [Seqera Platform API](#platform-api) but is simpler to use. For example, you can refer to resources by name instead of by unique identifier. ![Seqera Platform CLI](./assets/platform-cli.png) See [CLI](https://docs.seqera.io/platform-cli) for installation and usage details.
**Example pipeline launch CLI command** ```bash tw launch hello --workspace community/showcase ```
## seqerakit `seqerakit` is a Python wrapper for Platform CLI that automates the creation of Platform entities from a single YAML configuration file. It can create everything from organizations and workspaces to pipelines and compute environments, and launch workflows. The key features are: - **Simple configuration**: Define all Platform CLI command-line options in YAML format. - **Infrastructure as code**: Manage and provision your infrastructure specifications. - **Automation**: Create entities end-to-end, from adding an organization to launching pipelines within it. See the [seqerakit GitHub repository](https://github.com/seqeralabs/seqera-kit/) for installation and usage details.
**Example pipeline launch seqerakit configuration and command** Create a YAML file called `hello.yaml`: ```yaml launch: - name: "hello-world" url: "https://github.com/nextflow-io/hello" workspace: "seqeralabs/showcase" ``` Then run seqerakit: ```bash $ seqerakit hello.yaml ```
## Resources Common use cases for these automation methods include executing a pipeline as data arrives from a sequencer, or integrating Platform into a broader user-facing application. For a step-by-step guide to setting up these automation methods, see [Workflow automation for Nextflow pipelines](https://seqera.io/blog/workflow-automation/). For examples of how to use automation methods, see [Automating pipeline execution with Nextflow and Tower](https://seqera.io/blog/automating-workflows-with-nextflow-and-tower/). --- ## Community Showcase The Community Showcase is a Seqera-managed demonstration workspace with everything you need to follow this tutorial. All [Seqera Cloud](https://cloud.seqera.io) users can access it by default. This tutorial shows you how to: - Launch, monitor, and optimize the [*nf-core/rnaseq*](https://github.com/nf-core/rnaseq) pipeline. - Select pipeline input data with [Data Explorer](../../data/data-explorer) and Platform [datasets](../../data/datasets). - Analyze pipeline results interactively with [Studios](../../studios/overview). Use the Launchpad in any workspace to create and share Nextflow pipelines that run on any supported infrastructure, including all public clouds and most high-performance computing (HPC) schedulers. A Launchpad pipeline consists of a pre-configured pipeline repository, [compute environment](../../compute-envs/overview), and launch parameters. The Community Showcase contains 15 preconfigured pipelines, including [*nf-core/rnaseq*](https://github.com/nf-core/rnaseq), a bioinformatics pipeline used to analyze RNA sequencing data. The workspace also includes three preconfigured AWS Batch compute environments to run Community Showcase pipelines, plus Platform datasets and public data sources (accessed through Data Explorer) for use as pipeline input. :::tip To skip this Community Showcase demo and start running pipelines on your own infrastructure: 1. Set up an [organization workspace](../workspace-setup). 1. Create a workspace [compute environment](../../compute-envs/overview) for your cloud or HPC compute infrastructure. 1. [Add pipelines](./add-pipelines) to your workspace. ::: ## Launch the nf-core/rnaseq pipeline :::note This guide is based on version 3.14.0 of the *nf-core/rnaseq* pipeline. Launch form parameters may differ in other versions. ::: Go to the Launchpad in the `community/showcase` workspace and select **Launch** next to the *nf-core-rnaseq* pipeline to open the launch form. ![Launch a pipeline](../_images/cs-launch-form-1.gif) The launch form consists of **General config**, **Run parameters**, and **Advanced options** sections to specify your run parameters before execution, and an execution summary. Use section headings or select the **Previous** and **Next** buttons at the bottom of the page to move between sections.
Nextflow parameter schema The launch form lets you configure the pipeline execution. The pipeline parameters in this form are rendered from a [pipeline schema](../../pipeline-schema/overview) file in the root of the pipeline Git repository. `nextflow_schema.json` is a JSON-based schema that describes pipeline parameters. Pipeline developers use it to adapt their in-house Nextflow pipelines to run in Platform. :::tip See [Best Practices for Deploying Pipelines with the Seqera Platform](https://seqera.io/blog/best-practices-for-deploying-pipelines-with-seqera-platform/) to learn how to build the parameter schema for any Nextflow pipeline automatically with tooling maintained by the nf-core community. :::
### General config Most Showcase pipeline parameters are prefilled. Specify the following fields to identify your run among other workspace runs: - **Workflow run name**: A unique identifier for the run, pre-filled with a random name. You can customize it. - **Labels**: Assign new or existing labels to the run. For example, a project ID or genome version. ### Run parameters There are three ways to enter **Run parameters** prior to launch: - The **Input form view** displays form fields to enter text, select attributes from drop-downs, and browse input and output locations with [Data Explorer](../../data/data-explorer). - The **Config view** displays a raw schema that you can edit directly. Select JSON or YAML format from the **View as** drop-down. - **Upload params file** accepts a JSON or YAML file with run parameters. #### input Most nf-core pipelines use the `input` parameter in a standardized way to specify an input samplesheet that contains paths to input files (such as FASTQ files) and any additional metadata needed to run the pipeline. Use **Browse** to select either a file path in cloud storage via **Data Explorer**, or a pre-loaded **Dataset**: - In the **Data Explorer** tab, select the `nf-tower-data` bucket, then search for and select the `rnaseq_sample_data.csv` file. - In the **Datasets** tab, search for and select `rnaseq_sample_data`. ![Input parameters](../_images/cs-launch-input.gif) :::tip See [Add data](./add-data) to learn how to add datasets and Data Explorer cloud buckets to your own workspaces. ::: #### output Most nf-core pipelines use the `outdir` parameter to specify where the pipeline publishes final results. `outdir` must be unique for each pipeline run. Otherwise, your results are overwritten. For this tutorial test run, keep the default `outdir` value (`./results`). :::tip For the `outdir` parameter in pipeline runs in your own workspace, select **Browse** to specify a cloud storage directory using Data Explorer, or enter a cloud storage directory path to publish pipeline results to manually. ::: #### Pipeline-specific parameters Modify other parameters to customize the pipeline execution through the parameters form. For example, under **Read trimming options**, change the `trimmer` to select `fastp` in the drop-down instead of `trimgalore`. ![Read trimming options](./assets/trimmer-settings.png) Select **Launch** to start the run and be directed to the **Runs** tab with your run in a **submitted** status at the top of the list. ## View run information ### Run details page As the pipeline runs, the run details populate with parameters, logs, and other execution details:
View run details - **Command-line**: The Nextflow command invocation used to run the pipeline. This contains details about the pipeline version (`-r 3.14.0` flag) and profile, if specified (`-profile test` flag). - **Parameters**: The exact set of parameters used in the execution. This is helpful for reproducing the results of a previous run. - **Resolved Nextflow configuration**: The full Nextflow configuration settings used for the run. This includes parameters, but also settings specific to task execution (such as memory, CPUs, and output directory). - **Execution Log**: A summarized Nextflow log with information about the pipeline and the status of the run. - **Datasets**: Link to datasets, if any were used in the run. - **Reports**: View pipeline outputs directly in Platform. {/* TODO (EDU-842): replace with updated screenshot of the run details page */}
### View reports Most Nextflow pipelines generate reports or output files worth inspecting at the end of a run. Reports can contain quality control (QC) metrics to assess the integrity of the results.
View run reports ![Reports tab](assets/reports-tab.png) For example, for the *nf-core/rnaseq* pipeline, view the generated [MultiQC](https://docs.seqera.io/multiqc) report. MultiQC generates aggregate statistics and summaries from bioinformatics tools. ![Reports MultiQC preview](assets/reports-preview.png) The paths to report files point to a location in cloud storage (in the `outdir` directory specified during launch), but you can view the contents directly and download each file without navigating to the cloud or a remote filesystem. #### Specify outputs in reports To tell Platform where to find the reports generated by the pipeline, include a [tower.yml](https://github.com/nf-core/rnaseq/blob/master/tower.yml) file that lists the report locations in the pipeline repository. In the *nf-core/rnaseq* pipeline, the `MULTIQC` process step generates a MultiQC report file in HTML format: ```yaml reports: multiqc_report.html: display: "MultiQC HTML report" ```
:::note See [Reports](../../reports/overview) to configure reports for pipeline runs in your own workspace. ::: ### View general information The **Run details** page includes general information about who executed the run and when, the Git hash and tag used, and additional details about the compute environment and Nextflow version used.
View general run information {/* TODO (EDU-842): replace with updated screenshot of the General run information panel */} The **General** panel displays top-level information about a pipeline run: - Unique workflow run ID - Workflow run name - Timestamp of pipeline start (timezones are based on system settings) - Pipeline version and Git commit ID - Nextflow session ID - Username of the launcher - Work directory path
### View process and task details Scroll down the page to view: - The progress of individual pipeline **Processes** - **Aggregated stats** for the run (total walltime, CPU hours) - **Workflow metrics** (CPU efficiency, memory efficiency) - A **Task details** table for every task in the workflow The task details table provides further information on every step in the pipeline, including task statuses and metrics:
View task details Select a task in the task table to open the **Task details** dialog. The dialog has three tabs: **About**, **Execution log**, and **Data Explorer**. #### About The **About** tab includes: 1. **Name**: Process name and tag 2. **Command**: Task script, defined in the pipeline process 3. **Status**: Exit code, task status, and number of attempts 4. **Work directory**: Directory where the task was executed 5. **Environment**: Environment variables that were supplied to the task 6. **Execution time**: Metrics for task submission, start, and completion time (timezones are based on system settings) 7. **Resources requested**: Metrics for the resources requested by the task 8. **Resources used**: Metrics for the resources used by the task {/* TODO (EDU-842): replace with updated screenshot of the Task details dialog */} #### Execution log The **Execution log** tab provides a real-time log of the selected task's execution. You can download task execution and other logs (such as stdout and stderr) here, if they remain in your compute environment.
### Task work directory in Data Explorer If a task fails, a good place to begin troubleshooting is the task's work directory. Nextflow hash-addresses each task of the pipeline and creates unique directories based on these hashes.
View task log and output files Instead of navigating through a bucket on the cloud console or filesystem, use the **Data Explorer** tab in the Task window to view the work directory. Data Explorer shows the log files and output files generated for each task, directly within Platform. You can view, download, and copy the link for these intermediate files to simplify troubleshooting. {/* TODO (EDU-842): replace with updated screenshot of the task Data Explorer tab */}
## Interactive analysis Interactive analysis of pipeline results often happens in platforms like Jupyter Notebooks or the [R-IDE](https://github.com/seqeralabs/r-ide). Setting up the infrastructure for these platforms, including access to pipeline data and the necessary bioinformatics packages, can be complex and time-consuming. **Studios** simplifies creating interactive analysis environments. With built-in templates, creating a Studio is much like adding and sharing pipelines or datasets. ### Analyze RNAseq data in Studios In the **Studios** tab, you can monitor the Studios in the Community Showcase workspace and view their details. Use Studios to perform custom analysis on the results of upstream pipelines. For example, in the Community Showcase workspace we ran the *nf-core/rnaseq* pipeline to quantify gene expression, followed by *nf-core/differentialabundance* to derive differential expression statistics. The workspace contains a Studio with these results mounted from cloud storage for further analysis. One of these outputs is an RShiny application, which you can deploy for interactive analysis. #### Connect to the RNAseq analysis Studio Select the *rnaseq_to_differentialabundance* Studio. This Studio consists of an R-IDE that uses an existing compute environment in the Community Showcase workspace. The Studio also contains mounted data generated from the *nf-core/rnaseq* and subsequent *nf-core/differentialabundance* pipeline runs, directly from AWS S3. ![RNAseq Studio details](assets/rnaseq-diffab-studio-details.gif) Select **Connect** to view the running R-IDE session. The *rnaseq_to_differentialabundance* Studio includes the necessary R packages for deploying a web app to visualize the RNAseq data. Deploy the RShiny app in the Studio by selecting the play button on the last chunk of the R script: ![Run RShiny app](./assets/rnaseq-diffab-run-rshiny-app.png) :::note You can specify the resources each Studio uses. When [you create your own Studios](../../studios/overview) with shared compute environment resources, you must allocate sufficient resources to the compute environment to prevent Studio or pipeline run interruptions. ::: ### Explore results The RShiny app deploys in a separate browser window with a data interface. Here you can view information about your sample data, perform QC or exploratory analysis, and view the results of differential expression analyses. ![RShiny app exploration](assets/rnaseq-diffab-rshiny-app-explore.gif)
Sample clustering with PCA plots In the **QC/Exploratory** tab, select the PCA (Principal Component Analysis) plot to visualize how the samples group together based on their gene expression profiles. In this example, we used RNA sequencing data from the publicly available ENCODE project, which includes samples from four different cell lines: - **GM12878**: a lymphoblastoid cell line - **K562**: a chronic myelogenous leukemia cell line - **MCF-7**: a breast cancer cell line - **H1-hESC**: human embryonic stem cells What to look for in the PCA plot: - **Replicate clustering**: Ideally, biological replicates of the same cell type should cluster closely together. For example, replicates of MCF-7 (breast cancer cell line) group together. This indicates consistent gene expression profiles among biological replicates. - **Cell type separation**: Different cell types should form distinct clusters. For instance, GM12878, K562, MCF-7, and H1-hESC samples should each form their own separate clusters, reflecting their unique gene expression patterns. From this PCA plot, you can assess the consistency and quality of your sequencing data, identify potential issues, and understand the major sources of variation among your samples, all directly in Platform. ![RShiny PCA plot](assets/rnaseq-diffab-rshiny-pca-plot.gif)
Gene expression changes with Volcano plots In the **Differential** tab, select **Volcano plots** to compare genes with significant changes in expression between two samples. For example, filter for `Type: H1 vs MCF-7` to view the differences in expression between these two cell lines. 1. **Identify upregulated and downregulated genes**: The x-axis of the volcano plot represents the log2 fold change in gene expression between the H1 and MCF-7 samples, while the y-axis represents the statistical significance of the changes. - **Upregulated genes in MCF-7**: Genes on the left side of the plot (negative fold change) are upregulated in the MCF-7 samples compared to H1. For example, the SHH gene, which is known to be upregulated in cancer cell lines, prominently appears here. 2. **Filtering for specific genes**: To focus on specific genes, use the filter. For example, filter for the SHH gene in the table below the plot to locate and examine it in more detail. 3. **Gene expression bar plot**: After filtering for the SHH gene, select it to open a gene expression bar plot. This plot shows the expression levels of SHH across all samples and where it is most highly expressed. - Here, SHH is most highly expressed in MCF-7, which aligns with its known role in cancer cell proliferation. The volcano plot helps you identify and explore the genes with the largest expression changes between your samples. ![RShiny volcano plot](assets/rnaseq-diffab-rshiny-volcano-plot.gif)
### Collaborate in the Studio To share your RNAseq analysis results or let colleagues run their own exploratory analysis, select the options menu for the Studio, then select **Copy Studio URL**. With this link, other authenticated users with the **Connect** [role](../../orgs-and-teams/roles) (or greater) can access the session directly. :::note See [Studios](../../studios/overview) to learn how to create Studios in your own workspace. ::: ## Pipeline optimization The task-level resource usage metrics in Seqera Platform show the resources requested for a task and what it actually used. This information helps you fine-tune your configuration. However, manually adjusting resources for every task in your pipeline is impractical. Instead, use the pipeline optimization feature on the Launchpad. Pipeline optimization analyzes resource usage data from previous runs to optimize the resource allocation for future runs. After a successful run, optimization becomes available, indicated by the lightbulb icon next to the pipeline turning black.
Optimize nf-core/rnaseq Return to the Launchpad and select the lightbulb icon next to the *nf-core/rnaseq* pipeline to view the optimized profile. You can tailor the optimization's target settings and add a retry strategy as needed. #### View optimized configuration When you select the lightbulb, you can access an optimized configuration profile in the second tab of the **Customize optimization profile** window. This profile consists of Nextflow configuration settings for each process and each resource directive (where applicable): **cpus**, **memory**, and **time**. The optimized setting for a given process and resource directive is based on the maximum use of that resource across all tasks in that process. Once you select optimization, subsequent runs of that pipeline inherit the optimized configuration profile, indicated by the black lightbulb icon with a checkmark. :::note Optimization profiles are generated from one run at a time, defaulting to the most recent run, and _not_ an aggregation of previous runs. ::: ![Optimized configuration](assets/optimize-configuration.gif) Verify the optimized configuration of a given run by inspecting the resource usage plots for that run and these fields in the run's task table: | Description | Key | | ------------ | ---------------------- | | CPU usage | `pcpu` | | Memory usage | `peakRss` | | Runtime | `start` and `complete` |
--- ## Launch pipelines From the Launchpad in every workspace, you can create and share Nextflow pipelines that run on any supported infrastructure, including all public clouds and most HPC schedulers. A Launchpad pipeline consists of a preconfigured workflow Git repository, [compute environment](../../compute-envs/overview), and launch parameters. This tutorial walks you through launching the nf-core/rnaseq pipeline. :::info[**Prerequisites**] You need the following: - An organization and workspace. See [Set up an organization and workspace](../workspace-setup). - A workspace [compute environment](../../compute-envs/overview) for your cloud or HPC compute infrastructure. - A [pipeline](./add-pipelines) added to your workspace. - [Pipeline input data](./add-data) added to your workspace. ::: ## Launch a pipeline Navigate to the Launchpad and select **Launch** next to your pipeline to open the launch form. The launch form consists of **General config**, **Run parameters**, and **Advanced options** sections to specify your run parameters before execution, and an execution summary. Use section headings or select the **Previous** and **Next** buttons at the bottom of the page to navigate between sections.
Nextflow parameter schema The launch form configures the pipeline run. Platform renders the pipeline parameters in this form from a [pipeline schema](../../pipeline-schema/overview) file in the root of the pipeline Git repository. `nextflow_schema.json` is a JSON-based schema that describes pipeline parameters. Pipeline developers use it to adapt their in-house Nextflow pipelines to run in Platform. :::tip See [Best Practices for Deploying Pipelines with the Seqera Platform](https://seqera.io/blog/best-practices-for-deploying-pipelines-with-seqera-platform/) to learn how to build the parameter schema for any Nextflow pipeline automatically with tooling maintained by the nf-core community. :::
### General config - **Pipeline to launch**: The pipeline Git repository name or URL. For saved pipelines, this is prefilled and cannot be edited. - **Version name**: The version that will be selected as default for this pipeline. - **Version ID**: The ID of the pipeline version. - **Revision**: A valid repository commit ID, tag, or branch name. Determines the version of the pipeline to launch. - **Commit ID**: Pin pipeline revision to the most recent HEAD commit ID. If no commit ID is pinned, the latest revision of the repository branch or tag is used. - **Pull latest**: Fetch the most recent HEAD commit ID of the pipeline revision at launch time. Unpins the **Commit ID**, if set. :::info See [Git revision management](../../pipelines/revision.md) for more information on **Commit ID**, **Pull latest**, and **Revision** behavior. ::: - **Main script**: The script file to execute (default: `main.nf`). Config profiles suggestions may update when this field changes. - **Config profiles**: One or more [configuration profile](https://docs.seqera.io/nextflow/config#config-profiles) names to use for the execution. - **Workflow run name**: An identifier for the run, pre-filled with a random name. This can be customized. - **Labels**: Assign new or existing [labels](../../labels/overview) to the run. - **Compute environment**: Select an existing workspace [compute environment](../../compute-envs/overview). - **Work directory**: The (cloud or local) file storage path where pipeline scratch data is stored. If you specify only a cloud bucket location, Platform creates a scratch subfolder. :::note The credentials associated with the compute environment must have access to the work directory. ::: - **Schema**: The schema to validate pipeline parameters and prevent runtime failures. - **Repository default**: The default schema provided by the pipeline repository. - **Repository path**: A schema at a specific path in the repository. - **Seqera Platform schema**: A schema stored in Seqera Platform. ### Run parameters There are three ways to enter **Run parameters** prior to launch: - The **Input form view** displays form fields to enter text or select attributes from lists, and browse input and output locations with [Data Explorer](../../data/data-explorer). - The **Config view** displays raw configuration text that you can edit directly. Select JSON or YAML format from the **View as** list. - **Upload params file** allows you to upload a JSON or YAML file with run parameters. Specify your pipeline input and output and modify other pipeline parameters as needed: #### input Use **Browse** to select your pipeline input data: - In the **Data Explorer** tab, select the existing cloud bucket that contains your samplesheet, browse or search for the samplesheet file, and select the chain icon to copy the file path before closing the data selection window and pasting the file path in the input field. - In the **Datasets** tab, search for and select your existing dataset. #### outdir Use the `outdir` parameter to specify where the pipeline publishes outputs. `outdir` must be unique for each run to avoid overwriting results from a previous run. **Browse** and copy cloud storage directory paths using Data Explorer, or enter a path manually. #### Pipeline-specific parameters Modify other parameters to customize the pipeline execution through the parameters form. For example, in [nf-core/rnaseq](https://github.com/nf-core/rnaseq) (version 3.15.1), change the `trimmer` under **Read trimming options** to `fastp` instead of `trimgalore`. ![Read trimming options](./assets/trimmer-settings.png) ### Advanced settings - Use [resource labels](../../resource-labels/overview) to tag the computing resources created during the workflow execution. While resource labels for the run are inherited from the compute environment and pipeline, workspace admins can override them from the launch form. Applied resource label names must be unique. - Use [Pipeline secrets](../../secrets/overview) to store keys and tokens used by workflow tasks to interact with external systems. Enter the names of any stored user or workspace secrets required for the workflow execution. - See [Advanced options](../../launch/advanced) for more details. After you fill in the launch details, select **Launch**. The **Runs** tab shows your new run in a **submitted** status at the top of the list. Select the run name to open the [**View Workflow Run**](../../monitoring/overview) page, where you can view the configuration, parameters, status of individual tasks, and run report. --- ## Monitor runs After you [launch a pipeline](./launch-pipelines), Seqera Platform provides three views to monitor the progress and status of your runs: - The [**Runs** page](#runs) lists the runs in a single workspace. - The [**All runs** page](#all-runs) lists runs across all your organizations and workspaces. - The [**Dashboard**](#dashboard) summarizes run status totals across all your organizations and workspaces. ## Runs Select **Runs** in the left-hand navigation to view the full run history of a workspace. Each row corresponds to one run and displays its status. Select a run to view its [run details](../../monitoring/run-details), including the tasks, jobs, metrics, configuration, inputs, outputs, containers, and run info. ## All runs Access the **All runs** page from the user menu. This page lists runs across the entire Platform instance. The default view includes all organizations and workspaces you can access. To limit the view to specific workspaces, select the drop-down next to **View**. Filter the list with free text and one or more `keyword:value` terms in the search field: - `status`: Runs with a given status: `submitted`, `running`, `succeeded`, `failed`, `cancelled`, or `unknown`. - `label`: Runs with a given label. Repeat the keyword to filter by multiple labels. - `workflowId`: The run with a given workflow ID. - `runName`: Runs with a given run name. - `username`: Runs launched by a given user. - `projectName`: Runs of a given pipeline project. - `after`: Runs submitted on or after a date, in `YYYY-MM-DD` format. - `before`: Runs submitted on or before a date, in `YYYY-MM-DD` format. - `sessionId`: Runs with a given Nextflow session ID. - `is:starred`: Runs you have starred. Keyword terms use exact matches and combine with AND logic. Free text matches partially against the run name, project name, session ID, and manifest name. For example, to list the successful runs launched by `johndoe` after January 1, 2024 that match `rnaseq`: ```console rnaseq username:johndoe status:succeeded after:2024-01-01 ``` See [All runs view](../../monitoring/overview#all-runs-view) for the full search syntax. ## Dashboard Access the **Dashboard** from the user menu. This page displays run totals across the Platform instance, grouped by run status. The default view includes all organizations and workspaces you can access: - To limit the view to specific workspaces, select the drop-down next to **View**. - To filter by time, select a preset period or a custom date range of up to 12 months. Times are displayed in the local timezone defined in your device's system settings. - To download the displayed data as a CSV file, select **Export data**. See [Dashboard](../../monitoring/dashboard) for the Studios, Fusion, and resource usage views. --- ## Pipeline optimization Seqera Platform's task-level resource usage metrics allow you to determine the resources requested for a task and what was actually used. This information helps you fine-tune your configuration more accurately. However, manually adjusting resources for every task in your pipeline is impractical. Instead, you can leverage the pipeline optimization feature available on the Launchpad. Pipeline optimization analyzes resource usage data from previous runs to optimize the resource allocation for future runs. After a successful run, optimization becomes available, indicated by the lightbulb icon next to the pipeline turning black. ### Optimize nf-core/rnaseq Navigate back to the Launchpad and select the lightbulb icon next to the *nf-core/rnaseq* pipeline to view the optimized profile. You have the flexibility to tailor the optimization's target settings and incorporate a retry strategy as needed. ### View optimized configuration When you select the lightbulb, you can access an optimized configuration profile in the second tab of the **Customize optimization profile** window. This profile consists of Nextflow configuration settings for each process and each resource directive (where applicable): **cpus**, **memory**, and **time**. The optimized setting for a given process and resource directive is based on the maximum use of that resource across all tasks in that process. Once optimization is selected, subsequent runs of that pipeline will inherit the optimized configuration profile, indicated by the black lightbulb icon with a checkmark. :::note Optimization profiles are generated from one run at a time, defaulting to the most recent run, and _not_ an aggregation of previous runs. ::: ![Optimized configuration](assets/optimize-configuration.gif) Verify the optimized configuration of a given run by inspecting the resource usage plots for that run and these fields in the run's task table: | Description | Key | | ------------ | ---------------------- | | CPU usage | `pcpu` | | Memory usage | `peakRss` | | Runtime | `start` and `complete` | --- ## Studios :::info This guide provides an introduction to Studios using a demo Studio in the Community Showcase workspace. See [Studios](../../studios/overview) to learn how to create Studios in your own workspace. ::: Interactive analysis of pipeline results is often performed in platforms like Jupyter Notebook or an [R-IDE](https://github.com/seqeralabs/r-ide). Setting up the infrastructure for these platforms, including accessing pipeline data and the necessary bioinformatics packages, can be complex and time-consuming. Studios streamlines the process of creating interactive analysis environments for Platform users. With built-in templates, creating a Studio is as simple as adding and sharing pipelines or datasets. Platform manages all the details, enabling you to easily select your preferred interactive tool and analyze your data. In the **Studios** tab, you can monitor and see the details of the Studios in the Community Showcase workspace. ![Studios overview](./assets/studios-overview.png) Select the options menu next to a Studio to: - See Studio details - Start or stop the Studio, and connect to a running Studio - Copy the Studio URL to share it with collaborators ### Analyze RNAseq data in Studios Studios is used to perform bespoke analysis on the results of upstream workflows. For example, in the Community Showcase workspace we have run the *nf-core/rnaseq* workflow to quantify gene expression, followed by *nf-core/differentialabundance* to derive differential expression statistics. The workspace contains a Studio with these results from cloud storage mounted into the Studio to perform further analysis. One of these outputs is an RShiny application, which can be deployed for interactive analysis. ### Open the RNAseq analysis Studio Select the *rnaseq_to_differentialabundance* Studio. This Studio consists of an R-IDE that uses an existing compute environment available in the Community Showcase workspace. The Studio also contains mounted data generated from the *nf-core/rnaseq* and subsequent *nf-core/differentialabundance* pipeline runs, directly from AWS S3. ![RNAseq Studio details](assets/rnaseq-diffab-studio-details.gif) :::info Studios allows you to specify the resources each Studio will use. When [creating your own Studios](../../studios/overview) with shared compute environment resources, you must allocate sufficient resources to the compute environment to prevent Studio or pipeline run interruptions. ::: ### Connect to the Studio This Studio will start an R-IDE which already contains the necessary R packages for deploying a web app to interact with various visualizations of the RNAseq data. The Studio also contains an R Markdown document with the commands in place to generate the application. Deploy the app in the Studio by selecting the play button on the last chunk of the R script: ![Run RShiny app](./assets/rnaseq-diffab-run-rshiny-app.png) ### Explore results in the RShiny app The RShiny app will deploy in a separate browser window, providing a data interface. Here you can view information about your sample data, perform QC or exploratory analysis, and view the differential expression analyses. ![RShiny app exploration](assets/rnaseq-diffab-rshiny-app-explore.gif) #### Sample clustering with PCA plots In the **QC/Exploratory** tab, select the PCA (Principal Component Analysis) plot to visualize how the samples group together based on their gene expression profiles. In this example, we used RNA sequencing data from the publicly-available ENCODE project, which includes samples from four different cell lines: - **GM12878** — a lymphoblastoid cell line - **K562** — a chronic myelogenous leukemia cell line - **MCF-7** — a breast cancer cell line - **H1-hESC** — a human embryonic stem cell line What to look for in the PCA plot: - **Replicate clustering**: Ideally, replicates of the same cell type should cluster closely together. For example, replicates of the MCF-7 cells group together. This indicates consistent gene expression profiles among replicates. - **Cell type separation**: Different cell types should form distinct clusters. For instance, GM12878, K562, MCF-7, and H1-hESC cells should each form their own separate clusters, reflecting their unique gene expression patterns. From this PCA plot, you can gain insights into the consistency and quality of your sequencing data, identify any potential issues, and understand the major sources of variation among your samples - all directly in Platform. ![RShiny PCA plot](assets/rnaseq-diffab-rshiny-pca-plot.gif) #### Gene expression changes with Volcano plots In the **Differential** tab, select **Volcano plots** to compare genes with significant changes in expression between two samples. For example, filter for `Type: H1 vs MCF-7` to view the differences in expression between these two cell lines. 1. **Identify upregulated and downregulated genes**: The x-axis of the volcano plot represents the log2 fold change in gene expression between the H1 and MCF-7 cell lines, while the y-axis represents the statistical significance of the changes. - **Upregulated genes in MCF-7**: Genes on the left side of the plot (negative fold change) are upregulated in the MCF-7 samples compared to H1. For example, the _SHH_ gene, which is known to be upregulated in cancer cell lines, prominently appears here. 2. **Filtering for specific genes**: If you are interested in specific genes, use the filter function. For example, filter for the _SHH_ gene in the table below the plot. This allows you to quickly locate and examine this gene in more detail. 3. **Gene expression bar plot**: After filtering for the _SHH_ gene, select it to navigate to a gene expression bar plot. This plot will show you the expression levels of _SHH_ across all samples, allowing you to see in which samples it is most highly expressed. - Here, _SHH_ is most highly expressed in MCF-7, which aligns with its known role in cancer cell proliferation. Using the volcano plot, you can effectively identify and explore the genes with the most significant changes in expression between your samples, providing a deeper understanding of the molecular differences. ![RShiny volcano plot](assets/rnaseq-diffab-rshiny-volcano-plot.gif) ### Collaborate in the Studio To share the results of your RNAseq analysis or allow colleagues to perform exploratory analysis, share a link to the Studio by selecting the options menu for the Studio you want to share, then select **Copy Studio URL**. With this link, other authenticated users with the **Connect** [role](../../orgs-and-teams/roles) (or greater) can access the session directly. --- ## View run information When you launch a pipeline, you are directed to the **Runs** tab which contains all executed workflows, with your submitted run at the top of the list. Each new or resumed run is given a random name, which can be customized prior to launch. Each row corresponds to a specific run. As a job executes, it can transition through the following states: - **submitted**: Pending execution - **running**: Running - **succeeded**: Completed successfully - **failed**: Successfully executed, where at least one task failed with a terminate error strategy - **cancelled**: Stopped forcibly during execution - **unknown**: Indeterminate status ![View runs](assets/sp-cloud-view-all-runs.gif) ### View run details for nf-core/rnaseq The pipeline launched [previously](./launch-pipelines) is listed on the **Runs** tab. Select it from the list to view the run details. #### Run details page As the pipeline runs, run details will populate with the following tabs: - **Command-line**: The Nextflow command invocation used to run the pipeline. This contains details about the pipeline version (`-r 3.14.0` flag) and profile, if specified (`-profile test` flag). - **Parameters**: The exact set of parameters used in the execution. This is helpful for reproducing the results of a previous run. - **Configuration**: The full Nextflow configuration settings used for the run. This includes parameters, but also settings specific to task execution (such as memory, CPUs, and output directory). - **Datasets**: Link to datasets, if any were used in the run. - **Execution Log**: A summarized Nextflow log providing information about the pipeline and the status of the run. - **Reports**: View pipeline outputs directly in the Platform. ![View the nf-core/rnaseq run](assets/sp-cloud-run-info.gif) ### View reports Most Nextflow pipelines generate reports or output files which are useful to inspect at the end of the pipeline execution. Reports can contain quality control (QC) metrics that are important to assess the integrity of the results. ![Reports tab](assets/reports-tab.png) For example, for the nf-core/rnaseq pipeline, view the [MultiQC](https://docs.seqera.io/multiqc) report generated. MultiQC is a helpful reporting tool to generate aggregate statistics and summaries from bioinformatics tools. ![Reports MultiQC preview](assets/reports-preview.png) The paths to report files point to a location in cloud storage (in the `outdir` directory specified during launch), but you can view the contents directly and download each file without navigating to the cloud or a remote filesystem. #### Specify outputs in reports To customize and instruct Platform where to find reports generated by the pipeline, a [tower.yml](https://github.com/nf-core/rnaseq/blob/master/tower.yml) file that contains the locations of the generated reports must be included in the pipeline repository. In the nf-core/rnaseq pipeline, the MULTIQC process step generates a MultiQC report file in HTML format: ```yaml reports: multiqc_report.html: display: "MultiQC HTML report" ``` :::info See [Reports](../../reports/overview) to configure reports for pipeline runs in your own workspace. ::: ### View general information The run details page includes general information about who executed the run and when, the Git hash and tag used, and additional details about the compute environment and Nextflow version used. ![General run information](assets/general-run-details.gif) The **General** panel displays top-level information about a pipeline run: - Unique workflow run ID - Workflow run name - Timestamp of pipeline start (the time displayed is based on your local timezone defined in your device's system settings) - Pipeline version and Git commit ID - Nextflow session ID - Username of the launcher - Work directory path ### View details for a task Scroll down the page to view: - The progress of individual pipeline **Processes** - **Aggregated stats** for the run (total walltime, CPU hours) - A **Task details** table for every task in the workflow - **Workflow metrics** (CPU efficiency, memory efficiency) The task details table provides further information on every step in the pipeline, including task statuses and metrics. ### Task details Select a task in the task table to open the **Task details** dialog. The dialog has three tabs: **About**, **Execution log**, and **Data Explorer**. #### About The **About** tab includes: 1. **Name**: Process name and tag 2. **Command**: Task script, defined in the pipeline process 3. **Status**: Exit code, task status, and number of attempts 4. **Work directory**: Directory where the task was executed 5. **Environment**: Environment variables that were supplied to the task 6. **Execution time**: Metrics for task submission, start, and completion time (the time displayed is based on your local timezone defined in your device's system settings) 7. **Resources requested**: Metrics for the resources requested by the task 8. **Resources used**: Metrics for the resources used by the task ![Task details window](assets/task-details.gif) #### Execution log The **Execution log** tab provides a real-time log of the selected task's execution. Task execution and other logs (such as stdout and stderr) are available for download from here, if still available in your compute environment. ### Task work directory in Data Explorer If a task fails, a good place to begin troubleshooting is the task's work directory. Nextflow hash-addresses each task of the pipeline and creates unique directories based on these hashes. Instead of navigating through a bucket on the cloud console or filesystem to find the contents of this directory, use the **Data Explorer** tab in the Task window to view the work directory. Data Explorer allows you to view the log files and output files generated for each task in its working directory, directly within Platform. You can view, download, and retrieve the link for these intermediate files in cloud storage from the **Data Explorer** tab to simplify troubleshooting. ![Task data explorer](assets/sp-cloud-task-data-explorer.gif) ### Resume a pipeline Platform uses [Nextflow resume](../../launch/cache-resume) to resume a failed or cancelled workflow run with the same parameters, using the cached results of previously completed tasks and only executing failed and pending tasks. ![Resume a run](assets/sp-cloud-resume-a-run.gif) :::info To resume a run in your own workspace: - Select **Resume** from the options menu next to the run. - Edit the parameters before launch, if needed. - If you have the appropriate [permissions](../../orgs-and-teams/roles), you may edit the compute environment if needed. ::: --- ## RNA-Seq This guide details how to run bulk RNA sequencing (RNA-Seq) data analysis, from quality control to differential expression analysis, on an AWS Batch compute environment in Platform. It includes: - Creating an AWS Batch compute environment to run your pipeline and analysis environment - Adding pipelines to your workspace - Importing your pipeline input data - Launching the pipeline and monitoring execution from your workspace - Setting up a custom analysis environment with Studios - Resource allocation guidance for RNA-Seq data :::info[**Prerequisites**] You will need the following to get started: - [Admin](../orgs-and-teams/roles) permissions in an existing organization workspace. See [Set up your workspace](./workspace-setup) to create an organization and workspace from scratch. - An existing AWS cloud account with access to the AWS Batch service. - Existing access credentials with permissions to create and manage resources in your AWS account. See [IAM](../compute-envs/aws-batch#required-platform-iam-permissions) for guidance to set up IAM permissions for Platform. ::: ## Compute environment Compute and storage requirements for RNA-Seq analysis are dependent on the number of samples and the sequencing depth of your input data. See [RNA-Seq data and requirements](#rna-seq-data-and-requirements) for details on RNA-Seq datasets and the CPU and memory requirements for important steps of RNA-Seq pipelines. In this guide, you will create an AWS Batch compute environment with sufficient resources allocated to run the [nf-core/rnaseq](https://github.com/nf-core/rnaseq) pipeline with a large dataset. This compute environment will also be used to run a Studios R-IDE environment for interactive analysis of the resulting pipeline data. :::note The compute recommendations below are based on internal benchmarking performed by Seqera. See [RNA-Seq data and requirements](#rna-seq-data-and-requirements) for more information. ::: ### Recommended compute environment resources The following compute resources are recommended for production RNA-Seq pipelines, depending on the size of your input dataset: | **Setting** | **Value** | |--------------------------------|---------------------------------------| | **Instance Types** | `m5,r5` | | **vCPUs** | 2 - 8 | | **Memory (GiB)** | 8 - 32 | | **Max CPUs** | >500 | | **Min CPUs** | 0 | #### Fusion file system The [Fusion](../supported_software/fusion/overview) file system enables seamless read and write operations to cloud object stores, leading to simpler pipeline logic and faster, more efficient execution. While Fusion is not required to run *nf-core/rnaseq*, it is recommended for optimal performance. See [nf-core/rnaseq performance in Platform](#nf-corernaseq-performance-in-platform) at the end of this guide. Fusion works best with AWS NVMe instances (fast instance storage) as this delivers the fastest performance when compared to environments using only AWS EBS (Elastic Block Store). Batch Forge selects instances automatically based on your compute environment configuration, but you can optionally specify instance types. To enable fast instance storage (see Create compute environment below), you must select EC2 instances with NVMe SSD storage (`m5d` or `r5d` families). :::note Fusion requires a license for use in Seqera Platform compute environments or directly in Nextflow. Fusion can be trialed at no cost. [Contact Seqera](https://seqera.io/contact-us/) for more details. ::: ### Create compute environment ![Add Platform compute environment](./_images/create-ce.gif) From the **Compute Environments** tab in your organization workspace, select **Add compute environment** and complete the following fields: | **Field** | **Description** | |---------------------------------------|------------------------------------------------------------| | **Name** | A unique name for the compute environment. | | **Platform** | AWS Batch | | **Credentials** | Select existing credentials, or **+** to create new credentials:| | **Access Key** | AWS access key ID. | | **Secret Key** | AWS secret access key. | | **Region** | The target execution region. | | **Work directory** | An S3 bucket path in the same execution region. | | **Enable Wave Containers** | Use the Wave containers service to provision containers. | | **Enable Fusion v2** | Access your S3-hosted data via the Fusion v2 file system. | | **Enable fast instance storage** | Use NVMe instance storage to speed up I/O and disk access. Requires Fusion v2.| | **Config Mode** | Batch Forge | | **Provisioning Model** | Choose between Spot and On-demand instances. | | **Max CPUs** | Sensible values for production use range between 2000 and 5000.| | **Enable Fargate for head job** | Run the Nextflow head job using the Fargate container service to speed up pipeline launch. Requires Fusion v2.| | **Allowed S3 buckets** | Additional S3 buckets or paths to be granted read-write permission for this compute environment. Add data paths to be mounted in your data studio here, if different from your work directory.| | **Resource labels** | `name=value` pairs to tag the AWS resources created by this compute environment.| ## Add pipeline to Platform :::info The [*nf-core/rnaseq*](https://github.com/nf-core/rnaseq) pipeline is a highly configurable and robust workflow designed to analyze RNA-Seq data. It performs quality control, alignment and quantification. ![*nf-core/rnaseq* subway map](./_images/nf-core-rnaseq_metro_map_grey_static.svg) ::: [Seqera Pipelines](https://seqera.io/pipelines) is a curated collection of quality open-source pipelines that can be imported directly to your workspace Launchpad in Platform. Each pipeline includes a dataset to use in a test run to confirm compute environment compatibility in just a few steps. To use Seqera Pipelines to import the *nf-core/rnaseq* pipeline to your workspace: ![Seqera Pipelines add to Launchpad](./_images/pipelines-add.gif) 1. Search for *nf-core/rnaseq* and select **Launch** next to the pipeline name in the list. In the **Add pipeline** tab, select **Cloud** or **Enterprise** depending on your Platform account type, then provide the information needed for Seqera Pipelines to access your Platform instance: - **Seqera Cloud**: Paste your Platform **Access token** and select **Next**. - **Seqera Enterprise**: Specify the **Seqera Platform URL** (hostname) and **Base API URL** for your Enterprise instance, then paste your Platform **Access token** and select **Next**. :::tip If you do not have a Platform access token, select **Get your access token from Seqera Platform** to open the Access tokens page in a new browser tab. ::: 1. Select your Platform **Organization**, **Workspace**, and **Compute environment** for the imported pipeline. 1. (Optional) Customize the **Pipeline Name** and **Pipeline Description**. 1. Select **Add Pipeline**. :::info To add a custom pipeline not listed in Seqera Pipelines to your Platform workspace, see [Add pipelines](./quickstart-demo/add-pipelines#) for manual Launchpad instructions. ::: ## Pipeline input data The [*nf-core/rnaseq*](https://github.com/nf-core/rnaseq) pipeline works with input datasets (samplesheets) containing sample names, FASTQ file locations (paths to FASTQ files in cloud or local storage), and strandedness. For example, the dataset used in the `test_full` profile is derived from the publicly available iGenomes collection of datasets, commonly used in bioinformatics analyses. This dataset represents RNA-Seq samples from various human cell lines (GM12878, K562, MCF7, and H1) with biological replicates, stored in an AWS S3 bucket (`s3://ngi-igenomes`) as part of the iGenomes resource. These RNA-Seq datasets consist of paired-end sequencing reads, which can be used to study gene expression patterns in different cell types.
**nf-core/rnaseq test_full profile dataset** | sample | fastq_1 | fastq_2 | strandedness | |--------|---------|---------|--------------| | GM12878_REP1 | s3://ngi-igenomes/test-data/rnaseq/SRX1603629_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX1603629_T1_2.fastq.gz | reverse | | GM12878_REP2 | s3://ngi-igenomes/test-data/rnaseq/SRX1603630_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX1603630_T1_2.fastq.gz | reverse | | K562_REP1 | s3://ngi-igenomes/test-data/rnaseq/SRX1603392_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX1603392_T1_2.fastq.gz | reverse | | K562_REP2 | s3://ngi-igenomes/test-data/rnaseq/SRX1603393_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX1603393_T1_2.fastq.gz | reverse | | MCF7_REP1 | s3://ngi-igenomes/test-data/rnaseq/SRX2370490_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX2370490_T1_2.fastq.gz | reverse | | MCF7_REP2 | s3://ngi-igenomes/test-data/rnaseq/SRX2370491_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX2370491_T1_2.fastq.gz | reverse | | H1_REP1 | s3://ngi-igenomes/test-data/rnaseq/SRX2370468_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX2370468_T1_2.fastq.gz | reverse | | H1_REP2 | s3://ngi-igenomes/test-data/rnaseq/SRX2370469_T1_1.fastq.gz | s3://ngi-igenomes/test-data/rnaseq/SRX2370469_T1_2.fastq.gz | reverse |
In Platform, samplesheets and other data can be made easily accessible in one of two ways: - Use **Data Explorer** to browse and interact with remote data from AWS S3, Azure Blob Storage, and Google Cloud Storage repositories, directly in your organization workspace. - Use **Datasets** to upload structured data to your workspace in CSV (Comma-Separated Values) or TSV (Tab-Separated Values) format.
**Add a cloud bucket via Data Explorer** Private cloud storage buckets accessible with the credentials in your workspace are added to Data Explorer automatically by default. However, you can also add custom directory paths within buckets to your workspace to simplify direct access. To add individual buckets (or directory paths within buckets): ![Add public bucket](./quickstart-demo/assets/data-explorer-add-bucket.gif) 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - The cloud **Provider**. - An existing cloud **Bucket path**. - A unique **Name** for the bucket. - The **Credentials** used to access the bucket. For public cloud buckets, select **Public**. - An optional bucket **Description**. 1. Select **Add**. You can now select data directly from this bucket as input when launching your pipeline, without the need to interact with cloud consoles or CLI tools.
**Add a dataset** From the **Datasets** tab, select **Add Dataset**. ![Add a dataset](./quickstart-demo/assets/sp-cloud-add-a-dataset.gif) Specify the following dataset details: - A **Name** for the dataset, such as `nf-core-rnaseq-dataset`. - A **Description** for the dataset. - Select the **First row as header** option to prevent Platform from parsing the header row of the samplesheet as sample data. - Select **Upload file** and browse to your CSV or TSV samplesheet file in local storage, or drag and drop it into the box. The dataset is now listed in your organization workspace datasets and can be selected as input when launching your pipeline. :::info Platform does not store the data used for analysis in pipelines. The dataset must specify the locations of data stored on your own infrastructure. :::
## Launch pipeline :::note This guide is based on version 3.15.1 of the *nf-core/rnaseq* pipeline. Launch form parameters and tools may differ in other versions. ::: With your compute environment created, *nf-core/rnaseq* added to your workspace Launchpad, and your samplesheet accessible in Platform, you are ready to launch your pipeline. Navigate to the Launchpad and select **Launch** next to **nf-core-rnaseq** to open the launch form. The launch form consists of **General config**, **Run parameters**, and **Advanced options** sections to specify your run parameters before execution, and an execution summary. Use section headings or select the **Previous** and **Next** buttons at the bottom of the page to navigate between sections. ### General config ![General config tab](./_images/launch-form-2.gif) - **Pipeline to launch**: The pipeline Git repository name or URL. For saved pipelines, this is prefilled and cannot be edited. - **Revision**: A valid repository commit ID, tag, or branch name. For saved pipelines, this is prefilled and cannot be edited. - **Config profiles**: One or more [configuration profile](https://docs.seqera.io/nextflow/config#config-profiles) names to use for the execution. Config profiles must be defined in the `nextflow.config` file in the pipeline repository. - **Workflow run name**: An identifier for the run, pre-filled with a random name. This can be customized. - **Labels**: Assign new or existing [labels](../labels/overview) to the run. - **Compute environment**: Your AWS Batch compute environment. - **Work directory**: The cloud storage path where pipeline scratch data is stored. Platform will create a scratch sub-folder if only a cloud bucket location is specified. :::note The credentials associated with the compute environment must have access to the work directory. ::: ### Run parameters ![Run parameters](./_images/launch-form-3.gif) There are three ways to enter **Run parameters** prior to launch: - The **Input form view** displays form fields to enter text or select attributes from lists, and browse input and output locations with [Data Explorer](../data/data-explorer). - The **Config view** displays raw configuration text that you can edit directly. Select JSON or YAML format from the **View as** list. - **Upload params file** allows you to upload a JSON or YAML file with run parameters. Platform uses the `nextflow_schema.json` file in the root of the pipeline repository to dynamically create a form with the necessary pipeline parameters. Specify your pipeline input and output and modify other pipeline parameters as needed.
**input** Use **Browse** to select your pipeline input data: - In the **Data Explorer** tab, select the existing cloud bucket that contains your samplesheet, browse or search for the samplesheet file, and select the chain icon to copy the file path before closing the data selection window and pasting the file path in the input field. - In the **Datasets** tab, search for and select your existing dataset.
**outdir** Use the `outdir` parameter to specify where the pipeline outputs are published. `outdir` must be unique for each pipeline run. Otherwise, your results will be overwritten. **Browse** and copy cloud storage directory paths using Data Explorer, or enter a path manually.
Modify other parameters to customize the pipeline execution through the parameters form. For example, under **Read trimming options**, change the `trimmer` and select `fastp` instead of `trimgalore`. ![Read trimming options](./quickstart-demo/assets/trimmer-settings.png) ### Advanced settings - Use [resource labels](../resource-labels/overview) to tag the computing resources created during the workflow execution. While resource labels for the run are inherited from the compute environment and pipeline, workspace admins can override them from the launch form. Applied resource label names must be unique. - [Pipeline secrets](../secrets/overview) store keys and tokens used by workflow tasks to interact with external systems. Enter the names of any stored user or workspace secrets required for the workflow execution. - See [Advanced options](../launch/advanced) for more details. After you have filled the necessary launch details, select **Launch**. The **Runs** tab shows your new run in a **submitted** status at the top of the list. Select the run name to navigate to the [**View Workflow Run**](../monitoring/overview) page and view the configuration, parameters, status of individual tasks, and run report.
**Run monitoring** Select your new run from the **Runs** tab list to view the run details. #### Run details page As the pipeline runs, run details will populate with the following tabs: - **Command-line**: The Nextflow command invocation used to run the pipeline. This includes details about the pipeline version (`-r` flag) and profile, if specified (`-profile` flag). - **Parameters**: The exact set of parameters used in the execution. This is helpful for reproducing the results of a previous run. - **Resolved Nextflow configuration**: The full Nextflow configuration settings used for the run. This includes parameters, but also settings specific to task execution (such as memory, CPUs, and output directory). - **Execution Log**: A summarized Nextflow log providing information about the pipeline and the status of the run. - **Datasets**: Link to datasets, if any were used in the run. - **Reports**: View pipeline outputs directly in the Platform. ![View the nf-core/rnaseq run](./quickstart-demo/assets/sp-cloud-run-info.gif) #### View reports Most Nextflow pipelines generate reports or output files which are useful to inspect at the end of the pipeline execution. Reports can contain quality control (QC) metrics that are important to assess the integrity of the results. ![Reports tab](./quickstart-demo/assets/reports-tab.png) For example, for the *nf-core/rnaseq* pipeline, view the [MultiQC](https://docs.seqera.io/multiqc) report generated. MultiQC is a helpful reporting tool to generate aggregate statistics and summaries from bioinformatics tools. ![Reports MultiQC preview](./quickstart-demo/assets/reports-preview.png) The paths to report files point to a location in cloud storage (in the `outdir` directory specified during launch), but you can view the contents directly and download each file without navigating to the cloud or a remote filesystem. :::info See [Reports](../reports/overview) for more information. ::: #### View general information The run details page includes general information about who executed the run, when it was executed, the Git commit ID and/or tag used, and additional details about the compute environment and Nextflow version used. ![General run information](./quickstart-demo/assets/general-run-details.gif) #### View details for a task Scroll down the page to view: - The progress of individual pipeline **Processes** - **Aggregated stats** for the run (total walltime, CPU hours) - **Workflow metrics** (CPU efficiency, memory efficiency) - A **Task details** table for every task in the workflow The task details table provides further information on every step in the pipeline, including task statuses and metrics. #### Task details Select a task in the task table to open the **Task details** dialog. The dialog has three tabs: ![Task details window](./quickstart-demo/assets/task-details.gif) - The **About** tab contains extensive task execution details. - The **Execution log** tab provides a real-time log of the selected task's execution. Task execution and other logs (such as stdout and stderr) are available for download from here, if still available in your compute environment. - The **Data Explorer** tab allows you to view the task working directory directly in Platform. Nextflow hash-addresses each task of the pipeline and creates unique directories based on these hashes. Data Explorer allows you to view the log files and output files generated for each task in its working directory, directly within Platform. You can view, download, and retrieve the link for these intermediate files in cloud storage from the **Data Explorer** tab to simplify troubleshooting. ![Task Data Explorer](./quickstart-demo/assets/sp-cloud-task-data-explorer.gif)
## Interactive analysis with Studios **Studios** streamline the process of creating interactive analysis environments for Platform users. With built-in templates for platforms like Jupyter Notebook, R-IDE, and VS Code, creating a Studio is as simple as adding and sharing pipelines or datasets. The Studio URL can also be shared with any user with the [Connect role](../orgs-and-teams/roles) for real-time access and collaboration. For the purposes of this guide, an RStudio environment will be used to normalize the pipeline output data, perform differential expression analysis, and visualize the data with exploratory plots. ### Prepare your data #### Gene counts Salmon is the default tool used during the `pseudo-aligner` step of the *nf-core/rnaseq* pipeline. In the pipeline output data, the `/salmon` directory contains the tool's output, including a `salmon.merged.gene_counts_length_scaled.tsv` file. #### Sample info The analysis script provided in this section requires a sample information file to parse the counts data in the `salmon.merged.gene_counts_length_scaled.tsv` file. *nf-core/rnaseq* does not produce this sample information file automatically. See below to create a sample information file based on the genes in your `salmon.merged.gene_counts_length_scaled.tsv` file.
**Create a sample info file** 1. Note the names of the columns (excluding the first column, which typically contains gene IDs) in your `salmon.merged.gene_counts_length_scaled.tsv` file. These are your sample names. 1. Identify the group or condition that each sample belongs to. This information should come from your experimental design. 1. Create a new text file named `sampleinfo.txt`, with two columns: - First column header: Sample - Second column header: Group 1. For each sample in your `salmon.merged.gene_counts_length_scaled.tsv` file: - In the **Sample** column, write the exact sample name as it appears in the gene counts file. - In the **Group** column, write the corresponding group name. For example, for the dataset used in a `test_full` run of `nf-core/rnaseq`, the `sampleinfo.txt` looks like this: ``` Sample Group GM12878_REP1 GM12878 GM12878_REP2 GM12878 H1_REP1 H1 H1_REP2 H1 K562_REP1 K562 K562_REP2 K562 MCF7_REP1 MCF7 MCF7_REP2 MCF7 ``` To make your `sampleinfo.txt` file accessible to the Studio, upload it to the directory that contains your pipeline output data. Select this bucket or directory when you **Mount data** during Studio setup.
### Create an R-IDE analysis environment with Studios ![Add data studio](./_images/create-ds.gif) From the **Studios** tab, select **Add a studio** and complete the following: - Select the latest **R-IDE** container image template from the list. - Select your AWS Batch compute environment. :::note Studio sessions compete for computing resources when sharing compute environments. Ensure your compute environment has sufficient resources to run both your pipelines and sessions. The default CPU and memory allocation for a Studio is 2 CPUs and 8192 MB RAM. ::: - Mount data using Data Explorer: Mount the S3 bucket or directory path that contains the work directory of your RNA-Seq run. - Optional: Enter CPU and memory allocations. The default values are 2 CPUs and 8192 MB memory (RAM). - Select **Add**. - Once the Studio has been created, select the options menu next to it and select **Start**. - When the Studio is in a running state, **Connect** to it. ### Perform the analysis and explore results The R-IDE environment can be configured with the packages you wish to install and the R script you wish to run. For the purposes of this guide, run the following scripts to install the necessary packages and perform the analysis: 1. Install and load the necessary packages and libraries: ```r # Install required packages if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager") BiocManager::install(c("limma", "edgeR", "ggplot2", "gplots")) # Load required libraries library(limma) library(edgeR) library(ggplot2) library(gplots) ``` 1. Read and convert the count data and sample information: :::info Replace `` and `` with the paths to your `salmon.merged.gene_counts_length_scaled.tsv` and `sampleinfo.txt` files. ::: ```r # Read in the count data counts <- read.delim(file = "/workspace/data/", row.names = 1) # Remove the gene_name column if it exists if ("gene_name" %in% colnames(counts)) { counts <- counts[, -which(colnames(counts) == "gene_name")] } # Convert to matrix counts <- as.matrix(counts) # Read in the sample information targets <- read.table( file = "/workspace/data/", header = TRUE, stringsAsFactors = FALSE, sep = "", check.names = FALSE ) # Ensure column names are correct colnames(targets) <- c("Sample", "Group") ``` 1. Create a DGEList object and filter out low-count genes: ```r # Create a DGEList object y <- DGEList(counts, group = targets$Group) # Calculate CPM (counts per million) values mycpm <- cpm(y) # Filter low count genes thresh <- mycpm > 0.5 keep <- rowSums(thresh) >= 2 y <- y[keep, , keep.lib.sizes = FALSE] ``` 1. Normalize the data: ```r # Normalize the data y <- calcNormFactors(y) ``` 1. Print a summary of the filtered data: ```r # Print summary of filtered data print(dim(y)) print(y$samples) ``` 1. Create an MDS plot, displayed in RStudio plots viewer (`a`) and saved as a PNG file (`b`): :::info MDS plots are used to visualize the overall similarity between RNA-Seq samples based on their gene expression profiles, helping to identify sample clusters and potential batch effects. ::: ```r # Create MDS plot # a. Display in RStudio plotMDS(y, col = as.numeric(factor(targets$Group)), labels = targets$Group) legend( "topright", legend = levels(factor(targets$Group)), col = 1:nlevels(factor(targets$Group)), pch = 20 ) # b. Save MDS plot to file (change `png` to `pdf` to create a PDF file) png("MDS_plot.png", width = 800, height = 600) plotMDS(y, col = as.numeric(factor(targets$Group)), labels = targets$Group) legend( "topright", legend = levels(factor(targets$Group)), col = 1:nlevels(factor(targets$Group)), pch = 20 ) dev.off() ``` 1. Perform differential expression analysis: ```r # Design matrix design <- model.matrix( ~ 0 + group, data = y$samples) colnames(design) <- levels(y$samples$group) # Estimate dispersion y <- estimateDisp(y, design) # Fit the model fit <- glmQLFit(y, design) # Define contrasts my.contrasts <- makeContrasts( GM12878vsH1 = GM12878 - H1, GM12878vsK562 = GM12878 - K562, GM12878vsMCF7 = GM12878 - MCF7, H1vsK562 = H1 - K562, H1vsMCF7 = H1 - MCF7, K562vsMCF7 = K562 - MCF7, levels = design ) # Perform differential expression analysis for each contrast results <- lapply(colnames(my.contrasts), function(contrast) { qlf <- glmQLFTest(fit, contrast = my.contrasts[, contrast]) topTags(qlf, n = Inf) }) names(results) <- colnames(my.contrasts) ``` :::info This script is written for the analysis of human data, based on *nf-core/rnaseq*'s `test_full` dataset. To adapt the script for your data, modify the contrasts based on the comparisons you want to make between your sample groups: ```r my.contrasts <- makeContrasts( Sample1vsSample2 = Sample1 - Sample2, Sample2vsSample3 = Sample2 - Sample3, ... levels = design ) ``` ::: 1. Print the number of differentially expressed genes for each comparison and save the results to CSV files: ```r # Print the number of differentially expressed genes for each comparison for (name in names(results)) { de_genes <- sum(results[[name]]$table$FDR < 0.05) print(paste("Number of DE genes in", name, ":", de_genes)) } # Save results for (name in names(results)) { write.csv(results[[name]], file = paste0("DE_genes_", name, ".csv")) } ``` 1. Create volcano plots for each differential expression comparison, displayed in the plots viewer and saved as PNG files: :::info Volcano plots in RNA-Seq analysis display the magnitude of gene expression changes (log2 fold change) against their statistical significance. This allows for quick identification of significantly up- and down-regulated genes between two conditions. ::: ```r # Create volcano plots for differential expression comparisons # Function to create a volcano plot create_volcano_plot <- function(res, title) { ggplot(res$table, aes(x = logFC, y = -log10(FDR))) + geom_point(aes(color = FDR < 0.05 & abs(logFC) > 1), size = 0.5) + scale_color_manual(values = c("black", "red")) + labs(title = title, x = "Log2 Fold Change", y = "-Log10 FDR") + theme_minimal() } # Create volcano plots for each comparison for (name in names(results)) { p <- create_volcano_plot(results[[name]], name) # Display in RStudio print(p) # Save to file (change `.png` to `.pdf` to create PDF files) ggsave( paste0("volcano_plot_", name, ".png"), p, width = 8, height = 6, dpi = 300 ) } ``` 1. Create a heatmap of the top 50 differentially expressed genes: :::info Heatmaps in RNA-Seq analysis provide a color-coded representation of gene expression levels across multiple samples or conditions, enabling the visualization of expression patterns and sample clustering based on similarity. ::: ```r # Create a heatmap of top 50 differentially expressed genes # Get top 50 DE genes from each comparison top_genes <- unique(unlist(lapply(results, function(x) rownames(x$table)[1:50]))) # Get log-CPM values for these genes log_cpm <- cpm(y, log = TRUE) top_gene_expr <- log_cpm[top_genes, ] # Print dimensions of top_gene_expr print(dim(top_gene_expr)) # Create a color palette my_palette <- colorRampPalette(c("blue", "white", "red"))(100) # Create a heatmap using heatmap.2 # Display in RStudio heatmap.2( as.matrix(top_gene_expr), scale = "row", col = my_palette, trace = "none", dendrogram = "column", margins = c(5, 10), labRow = FALSE, ColSideColors = rainbow(length(unique(y$samples$group)))[factor(y$samples$group)], main = "Top DE Genes Across Samples" ) # Save heatmap to file (change `png` to `pdf` to create a PDF file) png("heatmap_top_DE_genes.png", width = 1000, height = 1200) heatmap.2( as.matrix(top_gene_expr), scale = "row", col = my_palette, trace = "none", dendrogram = "column", margins = c(5, 10), labRow = FALSE, ColSideColors = rainbow(length(unique(y$samples$group)))[factor(y$samples$group)], main = "Top DE Genes Across Samples" ) dev.off() # Print the number of top genes in the heatmap print(paste("Number of top DE genes in heatmap:", length(top_genes))) ``` ![RStudio plots](./_images/rstudio.gif) ### Collaborate in the Studio To share your results or allow colleagues to perform exploratory analysis, share a link to the Studio by selecting the options menu for the Studio you want to share, then select **Copy Studio URL**. With this link, other authenticated users with the **Connect** [role](../orgs-and-teams/roles) (or greater) can access the session directly. ## RNA-Seq data and requirements RNA-Seq data typically consists of raw sequencing reads from high-throughput sequencing technologies. These reads are used to quantify gene expression levels and discover novel transcripts. A typical RNA-Seq dataset can range from a few GB to several hundred GB, depending on the number of samples and the sequencing depth. ### *nf-core/rnaseq* performance in Platform The compute recommendations in this guide are based on internal benchmarking performed by Seqera. Benchmark runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files (8 paired-end samples) and a total size of approximately 123.5 GB. This benchmark compares pipeline run metrics between single *nf-core/rnaseq* runs in an AWS Batch compute environment with Fusion file system and fast instance storage enabled (**Fusion** group) and an identical AWS Batch compute environment using S3 storage without Fusion (**AWS S3** group). ### Pipeline steps and computing resource requirements The *nf-core/rnaseq* pipeline involves several key steps, each with distinct computational requirements. Resource needs in this table are based on the `test_full` runs detailed previously: | **Pipeline step** | **Tools** | **Resource needs** | **Description** | |-------------------------------------|---------------------------|------------------------------|---------------------------------------------------------------------------------------------------| | **Quality Control (QC)** | FastQC, MultiQC | Low-moderate CPU (50-200% single-core usage), low memory (1-7 GB peak) | Initial quality checks of raw reads to assess sequencing quality and identify potential issues. | | **Read Trimming** | Trim Galore! | High CPU (up to 700% single-core usage), low memory (6 GB peak) | Removal of adapter sequences and low-quality bases to prepare reads for alignment. | | **Read Alignment** | HISAT2, STAR | Moderate-high CPU (480-600% single-core usage), high memory (36 GB peak) | Alignment of trimmed reads to a reference genome, typically the most resource-intensive step. | | **Pseudoalignment** | Salmon, Kallisto | Moderate-high CPU (420% single-core usage), moderate memory (18 GB peak) | A faster, more accurate method of gene expression quantification than alignment using read compatibility. | | **Quantification** | featureCounts, Salmon | Moderate-high CPU (500-600% single-core usage), moderate memory (18 GB peak) | Counting the number of reads mapped to each gene or transcript to measure expression levels. | | **Differential Expression Analysis**| DESeq2, edgeR | High CPU (650% single-core usage), low memory (up to 2 GB peak ) | Statistical analysis to identify genes with significant changes in expression between conditions. | #### Overall run metrics **Total pipeline run cost (USD)**: - Fusion file system with fast instance storage: $34.90 - Plain S3 storage without Fusion: $58.40 **Pipeline runtime**: The Fusion file system used with NVMe instance storage contributed to a 34% improvement in total pipeline runtime and a 49% reduction in CPU hours. ![Run metrics overview](./_images/cpu-table-2.png) #### Process run time The Fusion file system demonstrates significant performance improvements for most processes in the *nf-core/rnaseq* pipeline, particularly for I/O-intensive tasks: - The most time-consuming processes see improvements of 36.07% to 70.15%, saving hours of runtime in a full pipeline execution. - Most processes show significant performance improvements with Fusion, with time savings ranging from 35.57% to 99.14%. - The most substantial improvements are seen in I/O-intensive tasks like `SAMTOOLS_FLAGSTAT` (95.20% faster) and `SAMTOOLS_IDXSTATS` (99.14% faster). - `SALMON_INDEX` shows a notable 70.15% improvement, reducing runtime from 102.18 minutes to 30.50 minutes. - `STAR_ALIGN_IGENOMES`, one of the most time-consuming processes, is 53.82% faster with Fusion, saving nearly an hour of runtime. ![Average runtime of `nf-core/rnaseq` processes for eight samples using the Fusion file system and plain S3 storage. Error bars = standard deviation of the mean.](./_images/process-runtime-2.png) | Process | S3 Runtime (min) | Fusion Runtime (min) | Time Saved (min) | Improvement (%) | |---------|------------------|----------------------|------------------|-----------------| | SAMTOOLS_IDXSTATS | 18.54 | 0.16 | 18.38 | 99.14% | | SAMTOOLS_FLAGSTAT | 22.94 | 1.10 | 21.84 | 95.20% | | SAMTOOLS_STATS | 22.54 | 3.18 | 19.36 | 85.89% | | SALMON_INDEX | 102.18 | 30.50 | 71.68 | 70.15% | | BEDTOOLS_GENOMECOV_FW | 19.53 | 7.10 | 12.43 | 63.64% | | BEDTOOLS_GENOMECOV_REV | 18.88 | 7.35 | 11.53 | 61.07% | | PICARD_MARKDUPLICATES | 102.15 | 41.60 | 60.55 | 59.27% | | STRINGTIE | 17.63 | 7.60 | 10.03 | 56.89% | | RSEQC_READDISTRIBUTION | 16.33 | 7.19 | 9.14 | 55.97% | | STAR_ALIGN_IGENOMES | 106.42 | 49.15 | 57.27 | 53.82% | | SALMON_QUANT | 30.83 | 15.58 | 15.25 | 49.46% | | RSEQC_READDUPLICATION | 19.42 | 12.15 | 7.27 | 37.44% | | QUALIMAP_RNASEQ | 141.40 | 90.40 | 51.00 | 36.07% | | TRIMGALORE | 51.22 | 33.00 | 18.22 | 35.57% | | DUPRADAR | 49.04 | 77.81 | -28.77 | -58.67% |
**Pipeline optimization** Seqera Platform's task-level resource usage metrics allow you to determine the resources requested for a task and what was actually used. This information helps you fine-tune your configuration more accurately. However, manually adjusting resources for every task in your pipeline is impractical. Instead, you can leverage the pipeline optimization feature on the Launchpad. Pipeline optimization analyzes resource usage data from previous runs to optimize the resource allocation for future runs. After a successful run, optimization becomes available, indicated by the lightbulb icon next to the pipeline turning black. #### Optimize *nf-core/rnaseq* Select the lightbulb icon next to *nf-core/rnaseq* in your workspace Launchpad to view the optimized profile. You have the flexibility to tailor the optimization's target settings and incorporate a retry strategy as needed. #### View optimized configuration When you select the lightbulb, you can access an optimized configuration profile in the second tab of the **Customize optimization profile** window. This profile consists of Nextflow configuration settings for each process and each resource directive (where applicable): **cpus**, **memory**, and **time**. The optimized setting for a given process and resource directive is based on the maximum use of that resource across all tasks in that process. Once optimization is selected, subsequent runs of that pipeline will inherit the optimized configuration profile, indicated by the black lightbulb icon with a checkmark. :::info Optimization profiles are generated from one run at a time, defaulting to the most recent run, and _not_ an aggregation of previous runs. ::: ![Optimized configuration](./quickstart-demo/assets/optimize-configuration.gif) Verify the optimized configuration of a given run by inspecting the resource usage plots for that run and these fields in the run's task table: | Description | Key | | ------------ | ---------------------- | | CPU usage | `pcpu` | | Memory usage | `peakRss` | | Runtime | `start` and `complete` |
--- ## Studios for interactive analysis [Studios](../studios/overview) allows users to host a variety of container images directly in Seqera Platform compute environments for analysis using popular environments including [Jupyter](https://jupyter.org/) (Python) and an [R-IDE](https://github.com/seqeralabs/r-ide) (R), [Visual Studio Code](https://code.visualstudio.com/) IDEs, and [Xpra](https://xpra.org/index.html) remote desktops. Each Studio session provides a dedicated interactive environment that encapsulates the live environment. This guide explores how Studios integrates with your existing workflows, bridging the gap between pipeline execution and interactive analysis. It details how to set up and use each type of Studio, demonstrating a practical use case for each. :::info[**Prerequisites**] You will need the following to get started: - At least the **Maintain** workspace [user role](../orgs-and-teams/roles) to create and configure Studios. - An [AWS Batch compute environment](../compute-envs/aws-batch#create-a-seqera-aws-batch-compute-environment) (**without Fargate**) with sufficient resources (minimum: 2 CPUs, 8192 MB RAM). - Valid [credentials](../credentials/overview) for your cloud storage account and compute environment. - [Data Explorer](../data/data-explorer) enabled in your workspace. ::: :::note The scripts and instructions provided in this guide were tested on 24 February 2025. Library and package versions recommended here may become outdated and lead to unexpected results over time. ::: ## Jupyter: Python-based visualization of protein structure prediction data Jupyter notebooks enable interactive analysis using Python libraries and tools. For example, Py3DMol is a tool used for visualizing and comparing structures produced by workflows such as [nf-core/proteinfold](https://nf-co.re/proteinfold/1.1.1), a bioinformatics best-practice analysis pipeline for protein 3D structure prediction. This section demonstrates how to create an AWS Batch compute environment, add the nf-core AWS megatests public proteinfold data to your workspace, create a Jupyter Studio, and run the provided Python script to produce interactive composite 3D images of the [H1065 sequence](https://predictioncenter.org/casp14/multimer_results.cgi?target=H1065). :::note This script and instructions can also be used to visualize the structures from *nf-core/proteinfold* runs performed with your own public or private data. ::: #### Create an AWS Batch compute environment Studios require an AWS Batch compute environment. If you do not have an existing compute environment available, [create one](../compute-envs/aws-batch#create-a-seqera-aws-batch-compute-environment) with the following attributes: - **Region**: To minimize costs, your compute environment should be in the same region as your data. To browse the nf-core AWS megatests public data optimally, select **eu-west-1**. - **Provisioning model**: Use **On-demand** EC2 instances. - Studios does not support AWS Fargate. Do not enable **Use Fargate for head job**. - At least 2 available CPUs and 8192 MB of RAM. #### Add data using Data Explorer For the purposes of this guide, add the proteinfold results (H1065 sequence) from the nf-core AWS megatests S3 bucket to your workspace using Data Explorer: 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - **Provider**: AWS - **Bucket path**: `s3://nf-core-awsmegatests/proteinfold/results-9bea0dc4ebb26358142afbcab3d7efd962d3a820` - A unique **Name** for the bucket, such as `nf-core-awsmegatests-proteinfold-h1065` - **Credentials**: **Public** - An optional bucket **Description** 1. Select **Add**. :::info To use your own pipeline data for interactive visualization, add the cloud bucket that contains the results of your *nf-core/proteinfold* pipeline run. See [Add a cloud bucket](./quickstart-demo/add-data#add-a-cloud-bucket) for more information. ::: ### Create a Jupyter Studio session From the **Studios** tab, select **Add a Studio** and complete the following: - In the **Compute & Data** tab: - Select your AWS Batch compute environment. :::note Studio sessions compete for computing resources when sharing compute environments. Ensure your shared compute environment has sufficient resources to run both your pipelines and Studio sessions. ::: - Optional: Enter CPU and memory allocations. The default values are 2 CPUs and 8192 MB memory (RAM). - Mount data using Data Explorer: Mount the S3 bucket or directory path that contains the nf-core AWS megatests proteinfold data, or the work directory of your *nf-core/proteinfold* run. - In the **General config** tab: - Select the latest **Jupyter** container image template from the list. - Optional: Enter a unique name and description for the Studio. - Check **Install Conda packages** and paste the following into the YAML textfield: ```yaml channels: - schrodinger - conda-forge - bioconda dependencies: - python=3.10 - conda-forge::libgl - pip - pip: - biopython==1.85 - mdtraj==1.10.3 - py3dmol==2.4.2 ``` - Select **Add** or choose to **Add and start** a Studio session immediately. - If you chose to **Add** the Studio in the preceding step, select **Connect** in the options menu to open a Studio session in a new browser tab. ### Visualize protein structures The following Python script visualizes and compares protein structures produced by Alphafold 2 and ESMFold, creating a composite interactive 3D image of the two structures with contrasting colors. The script aligns mobile structures to reference structures, retrieves lists of C-alpha atoms from both structures, creates views for individual and combined structures, and creates an interactive view of the individual and combined structures using Py3DMol. Run the following script in your Jupyter notebook to install the necessary packages and perform visualization:
Full Python script ```python from IPython.display import display from Bio import PDB from Bio.PDB import Superimposer # Keep file paths unchanged to visualize structures of the H1065 sequence in nf-core AWS megatests. # Update file paths (to PDB files) to visualize structures of your own nf-core/proteinfold output data. alphafold2_multimer_standard = "/workspace/data/nf-core-awsmegatests-proteinfold-h1065/mode_alphafold2_multimer/alphafold2/standard/H1065.alphafold.pdb" esmfold_multimer = "/workspace/data/nf-core-awsmegatests-proteinfold-h1065/mode_esmfold_multimer/esmfold/H1065.pdb" def align_structures(ref_pdb_path, mobile_pdb_path): """Align mobile structure to reference structure and return aligned coordinates""" # Set up parser parser = PDB.PDBParser() # Load structures ref_structure = parser.get_structure("reference", ref_pdb_path) mobile_structure = parser.get_structure("mobile", mobile_pdb_path) # Get lists of C-alpha atoms from both structures ref_atoms = [] mobile_atoms = [] for model in ref_structure: for chain in model: for residue in chain: if 'CA' in residue: ref_atoms.append(residue['CA']) for model in mobile_structure: for chain in model: for residue in chain: if 'CA' in residue: mobile_atoms.append(residue['CA']) # Align structures using Superimposer super_imposer = Superimposer() super_imposer.set_atoms(ref_atoms, mobile_atoms) super_imposer.apply(mobile_structure.get_atoms()) # Save aligned structure io = PDB.PDBIO() io.set_structure(mobile_structure) aligned_pdb_path = "./"+mobile_pdb_path.split("/")[-1].replace('.pdb', '_aligned.pdb') io.save(aligned_pdb_path) return aligned_pdb_path def create_structure_view(pdb_path, color, width=400, height=400, label=None): """Create a view for a single structure""" view = py3Dmol.view(width=width, height=height) with open(pdb_path, 'r') as f: pdb_data = f.read() view.addModel(pdb_data, "pdb") view.setStyle({'model': -1}, {'cartoon': {'color': color}}) view.zoomTo() if label: view.addLabel(label, { 'position': {'x': 0, 'y': 0, 'z': 0}, 'backgroundColor': color, 'fontColor': 'white' }) return view def visualize_structures(pdb1_path, pdb2_path): # Align the second structure to the first aligned_pdb2_path = align_structures(pdb1_path, pdb2_path) # Create three separate views view1 = create_structure_view(pdb1_path, 'blue', label="AlphaFold2") view2 = create_structure_view(aligned_pdb2_path, 'darkgrey', label="ESMFold") # Create combined view view3 = py3Dmol.view(width=800, height=400) # Load and display first structure (AlphaFold2) with open(pdb1_path, 'r') as f: pdb1_data = f.read() view3.addModel(pdb1_data, "pdb") view3.setStyle({'model': -1}, {'cartoon': {'color': 'blue'}}) # Load and display aligned second structure (ESMFold) with open(aligned_pdb2_path, 'r') as f: pdb2_data = f.read() view3.addModel(pdb2_data, "pdb") view3.setStyle({'model': 1}, {'cartoon': {'color': 'darkgrey'}}) # Set up the combined view view3.zoomTo() # Add labels for combined view view3.addLabel("AlphaFold2", {'position': {'x': -20, 'y': 0, 'z': 0}, 'backgroundColor': 'blue', 'fontColor': 'white'}) view3.addLabel("ESMFold", {'position': {'x': 20, 'y': 0, 'z': 0}, 'backgroundColor': 'darkgrey', 'fontColor': 'white'}) return view1, view2, view3 # Visualize the structures view1, view2, view3 = visualize_structures(alphafold2_multimer_standard, esmfold_multimer) # Display all views print("AlphaFold2 Structure:") view1.show() print("\nESMFold Structure:") view2.show() print("\nAligned Structures:") view3.show() ```
Python script individual steps 1. Import libraries: ```python from IPython.display import display from Bio import PDB from Bio.PDB import Superimposer ``` 1. Set up PDB file paths: ```python # Keep file paths unchanged to visualize structures of the H1065 sequence in nf-core AWS megatests. # Update file paths (to PDB files) to visualize structures of your own nf-core/proteinfold output data. alphafold2_multimer_standard = "/workspace/data/nf-core-awsmegatests-proteinfold-h1065/mode_alphafold2_multimer/alphafold2/standard/H1065.alphafold.pdb" esmfold_multimer = "/workspace/data/nf-core-awsmegatests-proteinfold-h1065/mode_esmfold_multimer/esmfold/H1065.pdb" ``` 1. Load structures from the PDB files and retrieve lists of C-alpha atoms from both structures: ```python def align_structures(ref_pdb_path, mobile_pdb_path): """Align mobile structure to reference structure and return aligned coordinates""" # Set up parser parser = PDB.PDBParser() # Load structures ref_structure = parser.get_structure("reference", ref_pdb_path) mobile_structure = parser.get_structure("mobile", mobile_pdb_path) # Get lists of C-alpha atoms from both structures ref_atoms = [] mobile_atoms = [] for model in ref_structure: for chain in model: for residue in chain: if 'CA' in residue: ref_atoms.append(residue['CA']) for model in mobile_structure: for chain in model: for residue in chain: if 'CA' in residue: mobile_atoms.append(residue['CA']) ``` 1. Align structures using Superimposer: ```python # Align structures using Superimposer super_imposer = Superimposer() super_imposer.set_atoms(ref_atoms, mobile_atoms) super_imposer.apply(mobile_structure.get_atoms()) # Save aligned structure io = PDB.PDBIO() io.set_structure(mobile_structure) aligned_pdb_path = "./"+mobile_pdb_path.split("/")[-1].replace('.pdb', '_aligned.pdb') io.save(aligned_pdb_path) return aligned_pdb_path ``` 1. Create a view for a single structure: ```python def create_structure_view(pdb_path, color, width=400, height=400, label=None): """Create a view for a single structure""" view = py3Dmol.view(width=width, height=height) with open(pdb_path, 'r') as f: pdb_data = f.read() view.addModel(pdb_data, "pdb") view.setStyle({'model': -1}, {'cartoon': {'color': color}}) view.zoomTo() if label: view.addLabel(label, { 'position': {'x': 0, 'y': 0, 'z': 0}, 'backgroundColor': color, 'fontColor': 'white' }) return view ``` 1. Create individual and combined structure views: ```python def visualize_structures(pdb1_path, pdb2_path): # Align the second structure to the first aligned_pdb2_path = align_structures(pdb1_path, pdb2_path) # Create three separate views view1 = create_structure_view(pdb1_path, 'blue', label="AlphaFold2") view2 = create_structure_view(aligned_pdb2_path, 'darkgrey', label="ESMFold") # Create combined view view3 = py3Dmol.view(width=800, height=400) # Load and display first structure (AlphaFold2) with open(pdb1_path, 'r') as f: pdb1_data = f.read() view3.addModel(pdb1_data, "pdb") view3.setStyle({'model': -1}, {'cartoon': {'color': 'blue'}}) # Load and display aligned second structure (ESMFold) with open(aligned_pdb2_path, 'r') as f: pdb2_data = f.read() view3.addModel(pdb2_data, "pdb") view3.setStyle({'model': 1}, {'cartoon': {'color': 'darkgrey'}}) # Set up the combined view view3.zoomTo() # Add labels for combined view view3.addLabel("AlphaFold2", {'position': {'x': -20, 'y': 0, 'z': 0}, 'backgroundColor': 'blue', 'fontColor': 'white'}) view3.addLabel("ESMFold", {'position': {'x': 20, 'y': 0, 'z': 0}, 'backgroundColor': 'darkgrey', 'fontColor': 'white'}) return view1, view2, view3 ``` 1. Display interactive 3D structure views: ```python # Visualize the structures view1, view2, view3 = visualize_structures(alphafold2_multimer_standard, esmfold_multimer) # Display all views print("AlphaFold2 Structure:") view1.show() print("\nESMFold Structure:") view2.show() print("\nAligned Structures:") view3.show() ```
![Visualize predicted protein structures in a Jupyter notebook Studio](./_images/protein-vis-short-gif-1080p-cropped.gif) #### Interactive collaboration To share a link to the running Studio session with collaborators inside your workspace, select the options menu for your Jupyter Studio session, then select **Copy Studio URL**. Using this link, other authenticated users can access the session directly to collaborate in real time. ## R-IDE: Analyze RNASeq data and differential expression statistics An R-IDE enables interactive analysis using R libraries and tools. For example, Shiny for R enables you to render functions in a reactive application and build a custom user interface to explore your data. The public data used in this section consists of RNA sequencing data that was processed by the *nf-core/rnaseq* pipeline to quantify gene expression, followed by *nf-core/differentialabundance* to derive differential expression statistics. This section demonstrates how to create a Studio to perform further analysis with these results from cloud storage. One of these outputs is web app that can be deployed for interactive analysis. #### Create an AWS Batch compute environment Studios require an AWS Batch compute environment. If you do not have an existing compute environment available, [create one](../compute-envs/aws-batch#create-a-seqera-aws-batch-compute-environment) with the following attributes: - **Region**: To minimize costs, your compute environment should be in the same region as your data. To browse the nf-core AWS megatests public data optimally, select **eu-west-1**. - **Provisioning model**: Use **On-demand** EC2 instances. - Studios does not support AWS Fargate. Do not enable **Use Fargate for head job**. - At least 2 available CPUs and 8192 MB of RAM. #### Add data using Data Explorer For the purposes of this guide, add the nf-core AWS megatests S3 bucket to your workspace using Data Explorer: 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - **Provider**: AWS - **Bucket path**: `s3://nf-core-awsmegatests` - A unique **Name** for the bucket, such as `nf-core-awsmegatests` - **Credentials**: **Public** - An optional bucket **Description** 1. Select **Add**. :::info To use your own pipeline data for interactive analysis, add the cloud bucket that contains the results of your *nf-core/differentialabundance* pipeline run. See [Add a cloud bucket](./quickstart-demo/add-data#add-a-cloud-bucket) for more information. ::: ### Create an R-IDE Studio session From the **Studios** tab, select **Add a Studio** and complete the following: - In the **Compute & Data** tab: - Select your AWS Batch compute environment. :::note Studio sessions compete for computing resources when sharing compute environments. Ensure your compute environment has sufficient resources to run both your pipelines and Studio sessions. ::: - Optional: Enter CPU and memory allocations. The default values are 2 CPUs and 8192 MB memory (RAM). - Mount data using Data Explorer: Mount the nf-core AWS megatests S3 bucket, or the directory path that contains the results of your *nf-core/differentialabundance* pipeline run. - In the **General config** tab: - Select the latest **R-IDE** container image template from the list. - Optional: Enter a unique name and description for the Studio. - Select **Add** or choose to **Add and start** a Studio session immediately. - If you chose to **Add** the Studio in the preceding step, select **Start** in the options menu, then **Connect** to open a Studio session in a new browser tab when it is running. ### Configure environment and explore data in a web app The following R script installs and configures the prerequisite packages and libraries to deploy ShinyNGS, a web application created by members of the nf-core community to explore genomic data. The script also downloads the RDS file from nf-core AWS megatests to use as input data for the app's various plots, heatmaps, and tables. To use your own *nf-core/rnaseq* and *nf-core/differentialabundance* results, modify the script as instructed in step 2 below:
R script individual steps 1. Configure the R-IDE session with installed packages, including [ShinyNGS](https://github.com/pinin4fjords/shinyngs): ```r if (!require("BiocManager", quietly = TRUE)) install.packages("BiocManager") BiocManager::install(version = "3.20", ask = FALSE) BiocManager::install(c("SummarizedExperiment", "GSEABase", "limma")) install.packages(c("devtools", "matrixStats", "rmarkdown", "markdown")) install.packages("shiny", repos = "https://cran.rstudio.com/") devtools::install_version("cpp11", version = "0.2.1", repos = "http://cran.us.r-project.org") devtools::install_github('pinin4fjords/shinyngs', upgrade_dependencies = FALSE) ``` 1. Download the RDS file from nf-core AWS megatests or your own *nf-core/differentialabundance* results (see [Shiny app](https://nf-co.re/differentialabundance/1.5.0/docs/output/#shiny-app) from the nf-core documentation for file details): ```r # For nf-core AWS megatests download.file("https://nf-core-awsmegatests.s3-eu-west-1.amazonaws.com/differentialabundance/results-3dd360fed0dca1780db1bdf5dce85e5258fa2253/shinyngs_app/study/data.rds", 'data.rds') # For your nf-core/differentialabundance results, replace the URL with your RDS file URL) download.file("https://bucket.s3-region.amazonaws.com/differentialabundance/results/shinyngs_app/study-name/data.rds", 'data.rds') ``` 1. Import libraries, read your RDS data, and launch the app: ```r library(shinyngs) library(markdown) esel <- readRDS("data.rds") app <- prepareApp("rnaseq", esel) shiny::shinyApp(app$ui, app$server) ```
![Explore the RShiny app](./quickstart-demo/assets/rnaseq-diffab-rshiny-app-explore.gif) #### Interactive collaboration To share a link to the running session with collaborators inside your workspace, select the options menu for your R-IDE session, then select **Copy Studio URL**. Using this link, other authenticated users can access the session directly to collaborate in real time. ## Xpra: Visualize genetic variants with IGV Xpra provides remote desktop functionality that enables many interactive analysis and troubleshooting workflows. One such workflow is to perform genetic variant visualization using IGV desktop, a powerful open-source tool for the visual exploration of genomic data. This section demonstrates how to add public data from the [1000 Genomes project](https://www.coriell.org/1/NHGRI/Collections/1000-Genomes-Project-Collection/1000-Genomes-Project) to your workspace, set up an Xpra environment with IGV desktop pre-installed, and explore a variant of interest. #### Create an AWS Batch compute environment Studios require an AWS Batch compute environment. If you do not have an existing compute environment available, [create one](../compute-envs/aws-batch#create-a-seqera-aws-batch-compute-environment) with the following attributes: - **Region**: To minimize costs, your compute environment should be in the same region as your data. To browse the 1000 Genomes public data optimally, select **us-east-1**. - **Provisioning model**: Use **On-demand** EC2 instances. - Studios does not support AWS Fargate. Do not enable **Use Fargate for head job**. - At least 2 available CPUs and 8192 MB of RAM. #### Add data using Data Explorer Add the 1000 Genomes S3 bucket to your workspace using Data Explorer: 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - **Provider**: AWS - **Bucket path**: `s3://1000genomes` - A unique **Name** for the bucket, such as `1000G` - **Credentials**: **Public** - An optional bucket **Description** 1. Select **Add**. :::info To use your own data for interactive analysis, see [Add a cloud bucket](./quickstart-demo/add-data#add-a-cloud-bucket) for instructions to add your own public or private cloud bucket. ::: ### Create an Xpra Studio session From the **Studios** tab, select **Add a Studio** and complete the following: - In the **Compute & Data** tab: - Select your AWS Batch compute environment. :::note Studio sessions compete for computing resources when sharing compute environments. Ensure your compute environment has sufficient resources to run both your pipelines and Studio sessions. ::: - Optional: Enter CPU and memory allocations. - Mount the 1000 Genomes S3 bucket you added previously using Data Explorer. - In the **General config** tab: - Select the latest **Xpra** container image template from the list. - Optional: Enter a unique name and description for the Studio. - Check **Install Conda packages** and paste the following into the YAML textfield: ```yaml channels: - conda-forge - bioconda dependencies: - igv - samtools ``` - Select **Add** or choose to **Add and start** a session immediately. - If you chose to **Add** the Studio in the preceding step, select **Connect** in the options menu to open a session in a new browser tab. ### View variants in IGV desktop 1. In the Xpra terminal, run `igv` to open IGV desktop. 1. In IGV, change the genome version to hg19. 1. Select **File**, then **Load from file**, then navigate to `/workspace/data/xpra-1000Genomes/phase3/data/HG00096/high_coverage_alignment` and select the `.bai` file, as shown below: ![Load BAM file in IGV desktop](./_images/xpra-data-studios-IGV-load-bam.png) 1. Search for PCSK9 and zoom into one of the exons of the gene. A coverage graph and reads should be shown, as below: ![BAM file view](./_images/xpra-data-studios-IGV-view-bam.png) #### Interactive collaboration To share a link to the running session with collaborators inside your workspace, select the options menu for your Xpra session, then select **Copy Studio URL**. Using this link, other authenticated users can access the session directly to collaborate in real time. ## VS Code: Create an interactive Nextflow development environment Using Studios and Visual Studio Code allows you to create a portable and interactive Nextflow development environment with all the tools you need to develop and run Nextflow pipelines. This section demonstrates how to set up a VS Code Studio with Conda and nf-core tools, add public data and run the *nf-core/fetchngs* pipeline with the `test` profile, and create a VS Code project to start coding your own Nextflow pipelines. The Studio includes the [Nextflow VS Code extension](https://marketplace.visualstudio.com/items?itemName=nextflow.nextflow), which makes use of the Nextflow language server to provide syntax highlighting, code navigation, code completion, and diagnostics for Nextflow scripts and configuration files. #### Create an AWS Batch compute environment Studios require an AWS Batch compute environment. If you do not have an existing compute environment available, [create one](../compute-envs/aws-batch#create-a-seqera-aws-batch-compute-environment) with the following attributes: - **Region**: To minimize costs, your compute environment should be in the same region as your data. To use the iGenomes public data bucket that contains the *nf-core/fetchngs* `test` profile data, select **eu-west-1**. - **Provisioning model**: Use **On-demand** EC2 instances. - Studios does not support AWS Fargate. Do not enable **Use Fargate for head job**. - At least 4 available CPUs and 16384 MB of RAM. #### Add data using Data Explorer The *nf-core/fetchngs* pipeline uses data from the NGI iGenomes public dataset for its `test` profile. To add this data to your workspace: 1. From the **Data Explorer** tab, select **Add cloud bucket**. 1. Specify the bucket details: - **Provider**: AWS - **Bucket path**: `s3://ngi-igenomes/test-data/` - A unique **Name** for the bucket, such as `ngi-igenomes-test-data` - **Credentials**: **Public** - An optional bucket **Description** 1. Select **Add**. ### Create a VS Code Studio session From the **Studios** tab, select **Add a Studio** and complete the following: - In the **Compute & Data** tab: - Select your AWS Batch compute environment. :::note Studio sessions compete for computing resources when sharing compute environments. Shared compute environments must have sufficient resources to run both your pipelines and Studio sessions. ::: - Allocate at least 4 CPUs and 16384 MB RAM. - Mount data using Data Explorer: To run *nf-core/fetchngs* with the `test` profile, mount the NGI iGenomes S3 bucket you added previously. Mount any other data directories you need to run and code your own Nextflow pipelines. - In the **General config** tab: - Select the latest **VS Code** container image template from the list. - Optional: Enter a unique name and description for the Studio. - Check **Install Conda packages** and paste the following into the YAML textfield: ```yaml channels: - conda-forge - bioconda - anaconda dependencies: - nf-core - conda ``` - Select **Add** or choose to **Add and start** a Studio session immediately. - If you chose to **Add** the Studio in the preceding step, select **Connect** in the options menu to open a Studio session in a new browser tab. - Once inside the Studio session, run `code .` to use the clipboard. :::tip See [User and workspace settings](https://code.visualstudio.com/docs/editor/settings) if you wish to import existing VS Code configuration and preferences to your Studio session's VS Code environment. ::: ### Run *nf-core/fetchngs* with Conda Run the following Nextflow command to run *nf-core/fetchngs* with Conda: ```shell nextflow run nf-core/fetchngs -profile test,conda --outdir ./nf-core-fetchngs-conda-out -resume ``` ### Write a Nextflow pipeline with nf-core tools - Run `nf-core pipelines create` to create a new pipeline. Choose which parts of the nf-core template you want to use. - Run `code [your new pipeline]` to open the new pipeline as a project in VSCode. This allows you to code your pipeline with the help of the Nextflow language server and nf-core tools. ![VS Code Studio session](./_images/guide-vs-code-studio-nf-env-1080p-cropped.gif) #### Interactive collaboration To share a link to the running session with collaborators inside your workspace, select the options menu for your VS Code Studio session, then select **Copy Studio URL**. Using this link, other authenticated users can access the session directly to collaborate in real time. --- ## Set up your workspace Workspaces in Seqera Platform contain the resources to run your analyses and manage your computing infrastructure. Each workspace participant has an access role that determines how they interact with the pipelines, compute environments, and data in the workspace. While each Platform user has a personal workspace, resource sharing and access management happen in organization workspaces. To set up an organization workspace, first create the organization that contains it. ### Create an organization Organizations are the top-level structure and contain workspaces, members, and teams. You can also add external collaborators to an organization. For more information, see [Organization management](../orgs-and-teams/organizations). 1. Expand the **Organization | Workspace** drop-down and select **Add organization**. 1. Complete the organization details: - **Name**: The organization name displayed in Platform. - **Full name**: The full name of the organization. - **Description**: A description of the organization for other organization members. - **Location**: The organization's location. - **Website URL**: The organization's website. - **Logo**: Drag and drop or upload an image. 1. Select **Add**. You are the first **Owner** of each organization you create. Add other organization owners and members from the organization's **Members** tab. ### Create a workspace 1. From the organization's **Workspaces** tab, select **Add Workspace**. 1. Complete the workspace details: - **Name**: The workspace name displayed in Platform. - **Full name**: The full name of the workspace. - **Description**: A description of the workspace for other workspace participants. - **Visibility**: Whether the workspace's pipelines are visible to all organization members (**Shared**) or only to workspace participants (**Private**). 1. Select **Add**. Your new workspace is listed in the organization's **Workspaces** tab. 1. Select your new workspace, then select the **Participants** tab to **Add Participants**. 1. Enter the names of existing organization members or teams and select **Add**. 1. Update a participant's access **Role** from the drop-down, if needed. ### Manage workspace access with teams Teams group organization members for workspace role-based access control (RBAC). All team members inherit the per-workspace access roles you assign to the team. Create a team, add team members, and add the team to workspaces from the **Teams** tab on your organization page: 1. Select **Add Team**, enter the team's details and an optional team avatar image, then select **Add**. 1. Select **Edit** next to the team name in the list, then select the **Members of team** tab to add new members by name or email. :::note Team members must be existing organization members. ::: 1. From the team edit screen's **Workspaces** tab, add workspaces by name and select an access **Role** from the drop-down next to each workspace in the list. --- ## Git integration Data pipelines are composed of many assets, including pipeline scripts, configuration files, dependency descriptors (such as for Conda or Docker), documentation, etc. When you manage complex data pipelines as Git repositories, all assets can be versioned and deployed with a specific tag, release, or commit ID. Version control and containerization are crucial to enable reproducible pipeline executions, and provide the ability to continuously test and validate pipelines as the code evolves over time. Seqera products have built-in support for [Git](https://git-scm.com) and several Git-hosting platforms. This page covers Git integration for both **Seqera Platform** and [**Co-Scientist**](#co-scientist). ## Seqera Platform Seqera Platform enables launching pipelines directly from Git repositories. Pipelines can be pulled remotely from both public and private Git providers, including the most popular platforms: GitHub, GitLab, and BitBucket. ### Public repositories Launch a public Nextflow pipeline by entering its Git repository URL in the pipeline to launch field. When you specify the revision number, the list of available revisions are automatically pulled using the Git provider's API. By default, the default branch (usually `main` or `master`) will be used. :::tip [nf-core](https://nf-co.re/pipelines) is a great resource for public Nextflow pipelines. ::: :::info The GitHub API imposes [rate limits](https://docs.github.com/en/developers/apps/building-github-apps/rate-limits-for-github-apps) on API requests. You can increase your rate limit by adding [GitHub credentials](#github) to your workspace as shown below. ::: ### Private repositories To access private Nextflow pipelines, add the credentials for your private Git hosting provider to Platform. :::info Credentials are encrypted with the AES-256 cypher before secure storage and are never exposed in an unencrypted way by any Platform API. ::: ### Multiple credential filtering When you have multiple stored credentials, Platform selects the most relevant credential for your repository in the following order: 1. Platform evaluates all the stored credentials available to the current workspace. 2. Credentials are filtered by Git provider (GitHub, GitLab, Bitbucket, etc.) 3. Platform selects the credential with a repository base URL most similar to the target repository. 4. If no repository base URL values are specified in the workspace credentials, the most long-lived credential is selected. #### Credential filtering example Workspace A contains four credentials: **Credential A** - Type: GitHub - Repository base URL: **Credential B** - Type: GitHub - Repository base URL: `https://github.com/` **Credential C** - Type: GitHub - Repository base URL: `https://github.com/pipeline-repo` **Credential D** - Type: GitLab - Repository base URL: `https://gitlab.com/repo-a` If you launch a pipeline with a Nextflow workflow in the `https://github.com/pipeline-repo`, Platform will use Credential C. For the application to select the most appropriate credential for your repository, we recommend that you: - Specify the repository base URL values as completely as possible for each Git credential used in the workspace. - Favor the use of service account type credentials where possible (such as GitLab group access tokens). - Avoid storing multiple user-based tokens with similar permissions. ## Co-Scientist [Co-Scientist](https://ai.seqera.io) integrates with your pipeline GitHub repositories to provide intelligent assistance with pipeline development and modification. To fully utilize the power of Co-Scientist, it needs access to your pipeline codebase to analyze, suggest changes, and even create pull requests on your behalf. ### Set up GitHub access To enable Co-Scientist to interact with your pipeline GitHub repositories: 1. **Generate a personal access token** - Navigate to [GitHub Personal Access Tokens](https://github.com/settings/personal-access-tokens) - Create a new token with the following permissions: - **Pull Requests**: Read & Write - **Contents**: Read & Write - Your token value will be displayed only once. Copy it before navigating away from the tokens page. 2. **Add the token to Co-Scientist** - Open [Co-Scientist](https://ai.seqera.io). - In the bottom-left user menu, select **Add token**. - Enter your personal access token in the field provided, then select **Set token**. ### Capabilities With proper GitHub access configured, Co-Scientist can: - Access and analyze your pipeline codebase - Create feature branches for proposed changes - Generate pull requests for your review - Suggest improvements based on your existing code patterns :::tip Co-Scientist respects your repository's branch protection rules and will create pull requests for review rather than directly modifying protected branches. ::: ## Seqera Platform Git provider credentials The following sections detail how to configure credentials for specific Git providers in Platform. These credentials enable access to private repositories for pipeline execution. ### Azure DevOps repositories You can authenticate to Azure DevOps repositories using a [personal access token (PAT)](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows#about-pats). Once you have created and copied your access token, create a new credential in Platform using these steps: #### Create Azure DevOps credentials 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 2. Enter a **Name** for the new credentials. 3. Select **Azure DevOps** as the **Provider**. 4. Enter your **Username** and **Access token**. 5. (Recommended) Enter the **Repository base URL** for which the credentials should be applied. This option is used to apply the provided credentials to a specific repository, e.g., `https://dev.azure.com//`. ### GitHub Use an access token to connect Platform to a private [GitHub](https://github.com/) repository. Personal (classic) or fine-grained access tokens can be used. :::info A user's personal access token (classic) can access every repository that the user has access to. GitHub recommends using fine-grained personal access tokens (currently in beta) instead, which you can restrict to specific repositories. Fine-grained personal access tokens also enable you to specify granular permissions instead of broad scopes. ::: For personal (classic) tokens, you must grant access to the private repository by selecting the main `repo` scope when the token is created. See [Creating a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic) for instructions to create your personal access token (classic). For fine-grained tokens, the repository's organization must [opt in](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) to the use of fine-grained tokens. Tokens can be restricted by resource owner (organization), repository access, and permissions. See [Creating a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) for instructions to create your fine-grained access token. After you've created and copied your access token, create a new credential in Seqera: #### Create GitHub credentials 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 1. Enter a **Name** for the new credentials. 1. Select **GitHub** as the **Provider**. 1. Enter your **Username** and **Access token**. 1. (Recommended) Enter the **Repository base URL** for which the credentials should be applied. This option is used to apply the provided credentials to a specific repository, e.g., `https://github.com/seqeralabs`. #### Create a new GitHub App from Platform To create and install a GitHub App from Platform with the manifest flow: 1. Go to the credentials page: - Organization workspace: Select **Credentials > Add Credentials**. - Personal workspace: Select your user menu, then select **Your credentials > Add credentials**. 1. Enter a **Name** for the new credentials, for example, `my-github-app`. :::note Underscores in the credential name are replaced with spaces in the resulting GitHub App name (e.g., `Seqera Platform - my github app`). :::: 1. Select **GitHub** as the **Provider**, set the **GitHub credential type** to **GitHub App**, then select **Create and add**. 1. Enter the **GitHub URL**: - For GitHub.com, leave the default value (`https://github.com`). - For a GitHub Enterprise Server instance, enter the base URL of your instance (e.g., `https://github.example.com`). HTTPS is required. Private or loopback addresses are rejected. 1. (Optional) Enter the **GitHub repository URL** to scope access to a single repository, for example, `https://github.com/seqeralabs/nf-tower`. Leave this field empty to create credentials that are not bound to a specific repository. 1. Select the **App scope**: - **Organization**: App owned by an organization (requires admin access). Enter the **GitHub organization name** (case-sensitive). You must be an **owner** of the target organization to create an app on its behalf. - **Personal**: App owned by your personal GitHub account. The **GitHub organization name** field is hidden. 1. Select **Create app on GitHub**. Seqera redirects you to GitHub: - For personal scope: `https://github.com/settings/apps/new` - For organization scope: `https://github.com/organizations//settings/apps/new` - For GitHub Enterprise Server, the equivalent path on your instance. The manifest is pre-filled with the app name, callback URL, webhook URL, and the required permissions (`contents: read`, `metadata: read`). ![GitHub "Create GitHub App" page with the manifest pre-filled, showing the app name "Seqera Platform - new github app"](./_images/credentials-github-mainfest-page.png) 1. On GitHub, review the requested permissions and select **Create GitHub App**. GitHub redirects you back to Seqera, which exchanges the temporary code for the app credentials and stores them in your workspace or personal credentials. 1. After the redirect, install the app on the repositories you want Seqera to access: - Open the new app on GitHub: **Settings > Developer settings > GitHub Apps** > **[your app]** > **Install App**. - For an organization-owned app, select the organization. - For a personal app, select your user account. - Choose **Only select repositories** and add the specific repositories Seqera should access, or select **All repositories** to grant access to all current and future repositories. - Select **Install** to complete installation. ![GitHub App installation page showing "Only select repositories" with one or more repositories selected](./_images/credentials-github-install-app.png) The new credential appears in your **Credentials** list with the GitHub App icon. Credentials created from your workspace credentials page are scoped to that workspace; credentials created from your personal credentials page are scoped to your user and are not visible to any workspace. :::note If you cancel the manifest flow on GitHub or close the browser tab before approving the app, no credentials are created in Platform. The temporary state that protects the redirect against CSRF expires after 10 minutes and cannot be reused. To try again, restart the flow from the credentials form. ::: #### Add an existing GitHub App To register an existing GitHub App in Platform: 1. Set the **GitHub credential type** to **GitHub App** and select **Add preexisting** 1. Enter the **GitHub URL**, **App scope**, and, if required, the **GitHub repository URL** described above. 1. Enter the app's security keys. To find these values, go to **Settings > Developer settings > GitHub Apps** > **[your app]** on GitHub: - App ID - Installation ID - App slug - Private key - Client secret - Webhook secret 1. Select **Add** to save the credentials. #### Handling duplicate credentials Seqera enforces uniqueness of GitHub App credentials by **Repository URL** within the same workspace or user context. If a GitHub App credential already exists for a given repository URL, any attempt to create another (through either the manifest flow or the existing-app flow) fails with a duplicate error. No new credential is stored. To resolve a duplicate: - **Reuse the existing credential**: In most cases the existing credential already grants Platform the access it needs. Open it from the **Credentials** list to confirm the association between the installed app and the repository. - **Delete the obsolete credential first**: If the existing credential is stale (e.g., the app has been uninstalled or the private key was rotated outside of Platform), delete it from the **Credentials** list and then re-run the creation flow. - **Use a different repository URL or leave the field empty**: If you need a second credential covering a broader scope, omit the **Repository URL** or use a different one. Platform's [credential filtering](#multiple-credential-filtering) then selects the most specific match at launch time. ### GitLab GitLab supports [Personal](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), [Group](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html#group-access-tokens), and [Project](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) access tokens for authentication. Your access token must have the `api`, `read_api`, and `read_repository` scopes to work with Seqera. For all three token types, use the token value in both the **Password** and **Access token** fields in the Seqera credential creation form. After you have created and copied your access token, create a new credential in Seqera with these steps: #### Create GitLab credentials 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 1. Enter a **Name** for the new credentials. 1. Select **GitLab** as the **Provider**. 1. Enter your **Username**. For Group and Project access tokens, the username can be any non-empty value. 1. Enter your token value in both the **Password** and **Access token** fields. 1. Enter the **Repository base URL** (recommended). This option is used to apply the credentials to a specific repository, e.g. `https://gitlab.com/seqeralabs`. ### Gitea To connect to a private [Gitea](https://gitea.io/) repository, use your Gitea user credentials to create a new credential in Platform with these steps: #### Create Gitea credentials 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 1. Enter a **Name** for the new credentials. 1. Select **Gitea** as the **Provider**. 1. Enter your **Username**. 1. Enter your **Password**. 1. Enter your **Repository base URL** (required). ### Bitbucket To connect to a private BitBucket repository, see [API tokens](https://support.atlassian.com/bitbucket-cloud/docs/api-tokens/) to learn how to create a BitBucket API token (the API token must have at least `read:repository:bitbucket` scope). Then, create a new credential in Seqera with these steps: :::warning API tokens are tied to users. This differs from access tokens, which are tied to a specific resource. While Seqera supports API tokens, access tokens are not supported for accessing BitBucket repositories. API tokens replace [app passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/), which can no longer be created after September 9, 2025 and will be phased out June 9, 2026. While app passwords are still supported, they are not recommended. See [Bitbucket Cloud transitions to API tokens](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation) for more information. ::: #### Create BitBucket credentials 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 1. Enter a **Name** for the new credentials. 1. Select **BitBucket** as the **Provider**. 1. Enter your **Username** (account email) and **Token**. 1. Enter the **Repository base URL** (recommended). This option can be used to apply the credentials to a specific repository, e.g., `https://bitbucket.org/seqeralabs`. ### AWS CodeCommit To connect to a private AWS CodeCommit repository, see the [AWS documentation](https://docs.aws.amazon.com/codecommit/latest/userguide/auth-and-access-control-iam-identity-based-access-control.html) to learn more about IAM permissions for CodeCommit. Then, use your IAM account access key and secret key to create a credential in Seqera with these steps: #### Create AWS CodeCommit credentials 1. From an organization workspace: Select **Credentials > Add Credentials**. From your personal workspace: Go to the user menu and select **Your credentials > Add credentials**. 1. Enter a **Name** for the new credentials. 1. Select **CodeCommit** as the **Provider**. 1. Enter the **Access key** and **Secret key** of the AWS IAM account that will be used to access the target CodeCommit repository. 1. Enter the **Repository base URL** for which the credentials should be applied (recommended). This option can be used to apply the credentials to a specific region, e.g., `https://git-codecommit.eu-west-1.amazonaws.com`. --- ## Labels Labels are workspace-specific free-text annotations that can be applied to pipelines, actions, or workflow runs, either during or after creation. Use labels to organize your work and filter key information. Labels aren't propagated to Nextflow during workflow execution. ### Limits :::caution Label names must contain a minimum of 2 and a maximum of 39 alphanumeric characters, separated by dashes or underscores, and must be unique in each workspace. ::: - Label names cannot begin or end with dashes `-` or underscores `_`. - Label names cannot contain a consecutive combination of `-` or `_` characters (`--`, `__`, `-_`, etc.) - A maximum of 25 labels can be applied to each resource. - A maximum of 1000 labels can be used in each workspace. ### Create and apply labels Labels can be created, applied, and edited by a workspace owner, admin, or maintainer. When applying a label, users can select from existing labels or add new ones on the fly. ### Labels applied to a pipeline :::caution Labels are applied to elements in a workspace-specific context. This means that labels applied to a shared pipeline in `workspace A` will not be shown when viewing the pipeline from `workspace B`. ::: The labels applied to each pipeline are displayed in both list and card views on the **Launchpad**. Select a pipeline to view all applied labels. Apply a label when adding a new pipeline or editing an existing pipeline. If a label is applied to a pipeline, all workflow runs of that pipeline will inherit the label. If the labels applied to the pipeline are changed, this change will only be applied to future runs, not past runs. ### Labels applied to an action Apply a label when adding a new action or editing an existing action. Labels applied to an action are displayed in the action card on the **Actions** screen. Hover over labels with **+** to see all labels. If a label is applied to an action, all workflow runs triggered by this action inherit the label. If the labels applied to the action are changed, this change will only be applied to future runs, not past runs. ### Labels applied to a workflow run Labels applied to a workflow run are displayed on the **Runs** list screen and on the workflow run detail screen. Hover over labels with **+** to see all labels. Apply a label to a workflow run during launch, on the workflow runs list screen, or on the run detail screen. ### Search and filter with labels You can search and filter pipelines and workflow runs using one or more labels — filter and search are complementary. ### Overview of labels in a workspace All labels used in a workspace can be viewed, added, edited, and deleted by a workspace owner, admin, or maintainer in the workspace **Settings** tab. If a label is edited or deleted on this screen, the change is propagated to all items where the label was used. :::caution You cannot undo editing or deleting a label. ::: --- ## Advanced options Advanced options modify pipeline configuration and execution beyond the standard run setup. They appear in the **Advanced options** section of the launch form. See [Advanced settings](./launchpad#advanced-settings) for their location in the launch form. Each section below documents one advanced option. Most runs do not need them. Use an option when you have a specific configuration or execution requirement. ## Nextflow config file Add additional or modified Nextflow configuration settings. Use the same syntax as the [Nextflow configuration file](https://docs.seqera.io/nextflow/config#config-syntax). ### Nextflow configuration order of priority When launching pipelines in Platform, Nextflow configuration is resolved from four sources. If the same parameter is defined in more than one source, the highest-priority source is used: | Priority | Nextflow configuration | Source | |----------|----------------------------------------------------------|----------------------------------------------------------------------------------------------------| | Highest | The pipeline launch form **Nextflow config file** field | User-defined at launch | | | Platform-managed compute settings | Derived from CE definition (see [Platform-managed configuration](#platform-managed-configuration)) | | | The compute environment **Global Nextflow config** field | User-defined during CE creation | | Lowest | The pipeline repository `nextflow.config` file | Pipeline Git repository | :::note **Global Nextflow config** values are pre-filled in the launch form's **Nextflow config file** field, but also apply independently at the priority level shown above. Clearing the launch form field does not remove the **Global Nextflow config** values. ::: For example, if: 1. The pipeline repository `nextflow.config` file contains this manifest: ```ini title="Pipeline repository nextflow.config" manifest { name = 'A' description = 'Pipeline description A' } ``` 2. Your compute environment **Global Nextflow config** field contains this manifest: ```ini title="Compute environment Global Nextflow config field" manifest { name = 'B' description = 'Pipeline description B' } ``` 3. You specify this manifest in the **Nextflow config file** field on the pipeline launch form: ```ini title="Pipeline launch form Nextflow config file field" manifest { name = 'C' description = 'Pipeline description C' } ``` The resolved configuration will contain the **Nextflow config file** field's manifest: ```ini title="Resolved configuration" manifest { name = 'C' description = 'Pipeline description C' } ``` ### Platform-managed configuration Platform generates a configuration file from the compute environment definition. For any property defined in both this file and the pipeline repository `nextflow.config`, the Platform-generated value takes precedence. There is no warning repository config values are replaced. ### Pre-launch configuration preview The configuration preview shown on the launch form reflects the **Nextflow config file** field and the compute environment's **Global Nextflow config** field only. Platform-managed compute settings and the pipeline repository `nextflow.config` are not visible in the preview. Both are resolved at launch time. :::tip{title="Best practices"} To ensure compute-specific settings are applied consistently: - Define compute-specific settings in the compute environment's **Global Nextflow config** field or the launch form's **Nextflow config file** field to make settings visible in the pre-launch preview and ensure they apply regardless of what the repository config contains. - Use the launch form's **Nextflow config file** field for settings that must take precedence over everything else. ::: ## Seqera Cloud config file Configure per-pipeline Seqera reporting behavior. Settings specified here override the default configuration for this execution. Use the `reports` key to specify report paths, titles, and MIME types: ```yml reports: reports/multiqc/index.html: display: "MultiQC Reports" mimeType: "text/html" ``` ## Pre and post-run scripts Run custom code either before or after the execution of the Nextflow script. These fields allow you to enter shell commands. Pre-run scripts are executed in the nf-launch script prior to invoking Nextflow processes. Pre-run scripts are useful for: - Executor setup, such as loading a private CA certificate. - Troubleshooting. For example, add `sleep 3600` to your pre-run script to instruct Nextflow to wait 3600 seconds (60 minutes) before process execution after the nf-launcher container is started, to create a window in which to test connectivity and other issues before your Nextflow processes execute. Post-run scripts are executed after all Nextflow processes have completed. The scripts have access to the following environment variables: | Environment variable | Description | |----------------------|----------------------------------------------| | `TOWER_WORKFLOW_ID` | The unique workflow run identifier | | `TOWER_WORKSPACE_ID` | The workspace identifier | | `NXF_UUID` | The Nextflow session ID | | `NXF_OUT_FILE` | Path to the Nextflow console output file | | `NXF_LOG_FILE` | Path to the Nextflow log file | | `NXF_TML_FILE` | Path to the timeline report HTML file | | `NXF_EXIT_STATUS` | The exit code of the workflow execution | | `TOWER_ACCESS_TOKEN` | Platform API access token for authentication | | `TOWER_REFRESH_TOKEN`| Platform API refresh token | | `NXF_WORK` | The work directory path used by the workflow | | `TOWER_CONFIG_FILE` | Path to the Tower configuration file | Post-run scripts are also useful for triggering a third party service via API request. :::note Post-run script failures do not affect the workflow exit status. Post-run scripts have a maximum size limit of 1 KB. ::: ## Stub run Replace Nextflow process commands with command [stubs](https://docs.seqera.io/nextflow/process#stub), where defined, before execution. ## Nextflow version Select the Nextflow version for the run. The selector lists the versions available in your installation and maps your choice to the launch container image that runs the workflow. The default version is: - **Pipeline advanced options**: the system default version, or the compute environment type's minimum version when that minimum is higher. - **Launch advanced options**: the version saved on the pipeline, when it is compatible with the selected compute environment. If the pipeline's saved version is below the minimum required by the compute environment, no version is preselected and you must choose a compatible version before launching. Version availability depends on the compute environment: - **Cloud and Kubernetes** compute environments (AWS Batch, Azure Batch, Google Batch, Kubernetes) support version selection. You cannot select versions below the compute environment's minimum. Platform rejects any launch submitted with a lower or unknown version through any channel (UI, API, or CLI) before execution. - **Grid/HPC** compute environments (Slurm, LSF, Grid Engine, Altair PBS Pro, Moab) run a pre-installed Nextflow and have no launch container. The version selector does not appear for them, and a version carried over from a pipeline default has no effect when you launch on a grid environment. Changing only the Nextflow version registers a new pipeline version, because the version determines the runtime that runs the workflow. :::note Use the **Nextflow version** selector instead of setting `NXF_VER` in a pre-run script or the pipeline configuration. If `NXF_VER` is set in the pipeline configuration, it overrides the version selected here. ::: ## Enable Nextflow syntax parser v2 Use the v2 Nextflow language parser. Requires Nextflow 25.02.0-edge or later. Older runtimes ignore this setting. The v2 parser implements Nextflow's [strict syntax](https://nextflow.io/docs/latest/strict-syntax.html). Platform selects it by exporting `NXF_SYNTAX_PARSER` to the launch environment: - **Off (default)**: Workflows run with the v1 parser. Platform exports `NXF_SYNTAX_PARSER=v1`. - **On**: Workflows run with the v2 parser. Platform exports `NXF_SYNTAX_PARSER=v2`. The toggle only selects the parser. It does not change the Nextflow runtime version, the pipeline source, or any pipeline parameters. The v2 parser becomes the default in Nextflow 26.04: - **Before Nextflow 26.04**: v1 is the runtime default. Turn the toggle on to opt in to v2. - **From Nextflow 26.04**: v2 is the runtime default. Turn the toggle off to pin a pipeline to v1. A [pre-run script](#pre-and-post-run-scripts) that exports `NXF_SYNTAX_PARSER` overrides this toggle. :::note The launch form inherits this setting from the pipeline. You can override it per launch without changing the stored value. Changing the toggle on the pipeline edit form creates a new pipeline version. ::: ## Main script Nextflow will attempt to run the script named `main.nf` in the root of the project repository by default. You can configure a custom script path and/or filename in `manifest.mainScript`, or you can provide the script path and filename in this field. In a pipeline repository set up with subdirectories containing multiple main script files, enter the path name to your desired custom script in **Main script**. For example: `/custom-pipeline/custom-script.nf` If you point to a custom script using this field, Platform also looks for a `nextflow.config` in the same directory as the custom script, and if none exists, it defaults to the `nextflow.config` in the repository root. :::note If you specify a custom script filename, the root of the default branch in your pipeline repository must still contain a `main.nf` file, even if blank. See [Nextflow configuration](../troubleshooting_and_faqs/nextflow) for more information on this known Nextflow behavior. ::: ## Workflow entry name Nextflow DSL2 provides the ability to launch workflows with specific names. Enter the name of the workflow to be executed in this field. ## Schema name Specify the name of a pipeline schema file in the workflow repository root folder to override the default `nextflow_schema.json`. ## Head job CPUs and memory Specify the compute resources allocated to the Nextflow head job. These fields are only displayed for runs executing on [AWS Batch](../compute-envs/aws-batch) and [Azure Batch](../compute-envs/azure-batch) compute environments. --- ## Nextflow cache and resume Nextflow maintains a [cache](https://docs.seqera.io/nextflow/cache-and-resume) directory where it stores the intermediate results and metadata from workflow runs. Workflows executed in Seqera Platform use this caching mechanism to enable users to relaunch or resume failed or otherwise interrupted runs as needed. This eliminates the need to re-execute successfully completed tasks when a workflow is executed again due to task failures or other interruptions. ## Cache directory Nextflow stores all task executions to the task cache automatically, whether or not the resume or relaunch option is used. This makes it possible to resume or relaunch runs later if needed. Platform HPC and local compute environments use the default Nextflow cache directory (`.nextflow/cache`) to store the task cache. Cloud compute environments use the [cloud cache](https://docs.seqera.io/nextflow/cache-and-resume#cache-stores) mechanism to store the task cache in a sub-folder of the pipeline work directory. To override the default cloud cache location in cloud compute environments, specify an alternate directory with the [cache](https://docs.seqera.io/nextflow/process#process-cache) directive in your Nextflow configuration file (either in the **Advanced options > Nextflow config file** field on the launch form, or in the `nextflow.config` file in your pipeline repository). To customize the cache location used in your AWS Batch and Amazon EKS compute environments, specify an alternate cache directory in your Nextflow configuration: ```groovy cloudcache { enabled = true path = 's3://your-bucket/.cache' } ``` The new cache directory must be accessible with the credentials associated with your compute environment. An alternate cloud storage location can be specified if you include the necessary credentials for that location in your Nextflow configuration. **This is not recommended for production environments**. To customize the cache location used in your Azure Batch compute environments, specify an alternate cache directory in your Nextflow configuration: ```groovy cloudcache { enabled = true path = 'az://your-container/.cache' } ``` The new cache directory must be accessible with the credentials associated with your compute environment. An alternate cloud storage location can be specified if you include the necessary credentials for that location in your Nextflow configuration. **This is not recommended for production environments**. To customize the cache location used in your Google Cloud Batch and Google Kubernetes Engine compute environments, specify an alternate cache directory in your Nextflow configuration: ```groovy cloudcache { enabled = true path = 'gs://your-bucket/.cache' } ``` The new cache directory must be accessible with the credentials associated with your compute environment. An alternate cloud storage location can be specified if you include the necessary credentials for that location in your Nextflow configuration. **This is not recommended for production environments**. Kubernetes compute environments do not use cloud cache by default. To specify a cloud storage cache directory, include the cloud cache path and necessary credentials for that location in your Nextflow configuration. **This is not recommended for production environments**.
AWS S3 ```groovy // Specify cloud storage credentials aws { accessKey = '' secretKey = '' region = '' } // Set the cloud cache path cloudcache { enabled = true path = 's3://your-bucket/.cache' } ```
Azure Blob Storage ```groovy // Specify cloud storage credentials azure { storage { accountName = '' accountKey = '' } } // Set the cloud cache path cloudcache { enabled = true path = 'az://your-container/.cache' } ```
Google Cloud Storage 1. See [these instructions](../compute-envs/google-cloud-batch#iam) to set up IAM and create a JSON key file for the custom service account with permissions to your Google Cloud storage account. 2. If you run the [gcloud CLI authentication flow](https://docs.seqera.io/nextflow/google#credentials) with `gcloud auth application-default login`, your Application Default Credentials are written to `$HOME/.config/gcloud/application_default_credentials.json` and picked up by Nextflow automatically. Otherwise, declare the `GOOGLE_APPLICATION_CREDENTIALS` environment variable explicitly with the local path to your service account credentials file created in the previous step. 3. Add the following to the **Nextflow Config file** field when you [launch](../launch/launchpad#launch-pipelines) your pipeline: ```groovy // Specify cloud storage credentials google { location = '' project = '' batch.serviceAccountEmail = '' } // Set the cloud cache path cloudcache { enabled = true path = 'gs://your-bucket/.cache' } ```
## Relaunch a workflow run An effective way to troubleshoot a workflow execution is to **Relaunch** it with different parameters. Select the **Runs** tab, open the options menu to the right of the run, and select **Relaunch**. You can edit parameters, such as **Pipeline to launch** and **Revision** before launch. Select **Launch** to execute the run from scratch. :::note The **Relaunch** option is only available for runs launched from the Seqera Platform interface. ::: ## Resume a workflow run Seqera uses Nextflow's **resume** functionality to resume a workflow run with the same parameters, using the cached results of previously completed tasks and only executing failed and pending tasks. Select **Resume** from the options menu to the right of the run of your choice to launch a resumed run of the same workflow, with the option to edit some parameters before launch. Unlike a relaunch, you cannot edit the pipeline to launch or the work directory during a run resume. :::note The **Resume** option is only available for runs launched from the Seqera Platform interface. ::: :::tip For a detailed explanation of the Nextflow resume feature, see _Demystifying Nextflow resume_ ([Part 1](https://www.nextflow.io/blog/2019/demystifying-nextflow-resume.html) and [Part 2](https://www.nextflow.io/blog/2019/troubleshooting-nextflow-resume.html)) in the Nextflow blog. ::: #### Change compute environment during run resume Users with appropriate permissions can change the compute environment when resuming a run. The new compute environment must have access to the original run work directory. This means that the new compute environment must have a work directory that matches the root path of the original pipeline work directory. For example, if the original pipeline work directory is `s3://foo/work/12345`, the new compute environment must have access to `s3://foo/work`. --- ## Launch pipelines(Launch) Use the Seqera Platform **Launchpad** to launch pre-configured pipelines, add new pipelines, or quick-launch unsaved pipelines. ## Sort and filter pipelines Select the **Sort by:** drop-down to sort pipelines by name or by most-recently updated. Select the filter icon to filter by workspace and labels. The list layout is the default **Launchpad** view. Select the tiles icon to switch between the list and tile layout. Both views display the compute environment of each pipeline. :::note A pipeline is a repository containing a Nextflow workflow, a compute environment, and pipeline parameters. ::: ## Launch pipelines Use the launch form to launch pipelines and add pipelines to the **Launchpad**. Select **Launch** next to a saved pipeline in the list, or select **Quick launch** to quick-launch an unsaved pipeline. The launch form consists of [General config](#general-config), [Run parameters](#run-parameters), [Advanced settings](#advanced-settings), and [Summary](#summary) tabs to configure and view your run before execution. Use section headings or select **Previous** or **Next** at the bottom of the page to navigate between sections. For saved pipelines, **General config** and **Run parameters** fields are prefilled and can be edited before launch. :::info The launch form accepts URL query parameters. See [URL query parameters](#url-query-parameters) for more information. ::: ### General config Configure the core settings for your run, including the pipeline source, compute environment, and work directory: #### Run setup - **Pipeline to launch**: A Git repository name or URL. For saved pipelines, this is prefilled and cannot be edited. Private repositories require [access credentials][credentials]. :::note Nextflow pipelines are Git repositories that can reside on any public or private Git-hosting platform. See [Git integration][git] in the Seqera docs and [Pipeline sharing][pipeline-sharing] in the Nextflow docs for more details. ::: - **Version name**: The pipeline version name selected as the default for this run. See [Pipeline versioning][pipeline-version] for details. - **Version ID**: The pipeline version ID selected as the default for this run. See [Pipeline versioning][pipeline-versioning] for details. - **Revision**: A valid repository commit ID, tag, or branch name. Determines the version of the pipeline to launch. - **Commit ID**: The pipeline revision commit ID. If no commit ID is pinned, the latest revision of the repository branch or tag is used. - **Pull latest**: Pull the most recent HEAD commit ID of the pipeline revision at launch time. Unpins the **Commit ID**, if set. :::info See [Git revision management][pipeline-revision] for more information on **Revision**, **Commit ID**, and **Pull latest**, behavior. ::: - **Main script**: The script file to execute (default: `main.nf`). Config profile suggestions may update when this field changes. See [Main script](./advanced#main-script) for custom script paths. - **Config profiles**: One or more [configuration profile][nextflow-config-profile] names to use for the execution. Config profiles must be defined in the `nextflow.config` file in the pipeline repository.
How config profiles are detected Seqera Platform populates the **Config profiles** drop-down by statically analyzing the pipeline's Nextflow configuration. The analysis detects profiles in the main configuration and in `includeConfig` statements that match any of these patterns: - A static string: ```groovy includeConfig 'conf/profiles.config' includeConfig 'http://...' ``` - A dynamic string that depends on parameters defined in the config: ```groovy includeConfig params.custom_config includeConfig "${params.custom_config_base}/nfcore_custom.config" ``` - A ternary expression (only the `true` branch is inspected): ```groovy includeConfig params.custom_config_base ? "${params.custom_config_base}/nfcore_custom.config" : "/dev/null" ``` - An include within a try-catch statement: ```groovy try { includeConfig "${params.custom_config_base}/nfcore_custom.config" } catch (Exception e) { // ... } ```
- **Workflow run name**: A unique identifier for the run, pre-filled with a random name that you can customize. - **Labels**: Assign new or existing [labels][labels] to the run. - **Compute environment**: The [compute environment][compute-envs] where the run launches. - **Work directory**: The cloud storage or file system path where pipeline scratch data is stored. Seqera Platform creates a scratch sub-folder if you specify only a cloud bucket location. Use file system paths for local or high-performance computing (HPC) compute environments. :::note The credentials associated with the compute environment must have access to the work directory. ::: - **Schema**: The [pipeline schema][pipeline-schema] to validate pipeline parameters and prevent runtime failures. Options include **Repository default**, **Repository path**, and **Seqera Platform schema**. #### Output directory Set an optional **Output directory** to override the default location for your pipeline's [workflow outputs][nextflow-workflow-outputs]. This is distinct from your pipeline's own output parameter (such as `outdir`) under [Run parameters](#run-parameters). - Enter an absolute cloud storage path, such as `s3://my-bucket/results`, or select **Browse** to choose a location with [Data Explorer][data-explorer]. Select a **Compute environment** before you browse. - Platform passes this value to Nextflow as `-output-dir`. - **Output directory** is optional and is not carried over on relaunch. Set it for each launch. :::note The **Output directory** field requires Nextflow 24.10.0 or later and a pipeline that uses the [workflow outputs syntax][nextflow-workflow-outputs]. For older pipelines, use your pipeline output parameter (for example, `params.outdir`) instead. ::: ### Run parameters Enter **Run parameters** in one of four ways before launch: - The **Input form view** displays form fields to enter text, select attributes from drop-downs, and browse input and output locations with [Data Explorer][data-explorer]. - The **Params file view** displays a raw schema that you can edit directly. Select JSON or YAML format from the **View as** drop-down. - Use **Upload params file** to upload a JSON or YAML file with run parameters. - Specify run parameters with query parameters in the launch URL. See [URL query parameters](#url-query-parameters) for more information. If the pipeline includes a `nextflow_schema.json` file in its repository root, Seqera Platform uses it to dynamically generate a form with that pipeline's parameters. The fields shown vary by pipeline, depending on the parameters defined in the schema. Common parameters include: - **Input data**: If the pipeline defines an input parameter, specify compatible [datasets][datasets] manually or from the drop-down. Select **Browse** to view the available datasets or browse for files in [Data Explorer][data-explorer]. Use the Data Explorer tab to select input datasets that match your [pipeline schema][pipeline-schema] `mimetype` criteria (`text/csv` for CSV files, or `text/tsv` for TSV files). - **Output directory**: Your pipeline's own output directory parameter (for example, `outdir`), if defined in the pipeline schema. Specify it manually or select **Browse** to choose a cloud storage directory using [Data Explorer][data-explorer]. This is separate from the [**Output directory**](#output-directory) field in **General config**, which sets the Nextflow `-output-dir` value for workflow outputs. ### Advanced settings Configure platform resources, pipeline secrets, and advanced Nextflow options before launch. #### Platform config - **Resource labels**: [Resource labels][resource-labels] to tag the computing resources created during a run. The run inherits resource labels from the compute environment and pipeline, but admins can override them from the launch form. Applied resource label names must be unique. #### Pipeline secrets - **Workspace's pipeline secrets**: [Secrets][pipeline-secrets] defined in the current workspace, available to all members. - **User's pipeline secrets**: [Secrets][pipeline-secrets] defined in your personal account. :::note In AWS Batch compute environments, Seqera Platform passes stored secrets to jobs as part of the job definition it creates. You cannot use Seqera secrets in Nextflow processes that use a [custom job definition][custom-job-definition]. ::: #### Advanced options - **Nextflow config file**: Additional Nextflow configuration settings. - **Seqera Cloud config file**: Additional Seqera Cloud configuration settings to override the `tower.yml` file. - **Pre-run scripts**: Custom shell commands to run before the execution. - **Post-run scripts**: Custom shell commands to run after the execution. - **Stub run**: Replace process commands with [stubs](https://docs.seqera.io/nextflow/process#stub), where defined, before execution. - **Enable Nextflow syntax parser v2**: Run the pipeline with the v2 Nextflow language parser. - **Workflow entry name**: A named DSL2 workflow other than the default. - **Schema name**: The name of a pipeline schema file in the workflow repository root folder to override the default `nextflow_schema.json`. - **Head job CPUs**: The number of CPUs for the Nextflow head job. Fields are only displayed for runs executing on [AWS Batch](../compute-envs/aws-batch) and [Azure Batch](../compute-envs/azure-batch) compute environments. - **Head job memory**: The memory for the Nextflow head job, in MiB. Fields are only displayed for runs executing on [AWS Batch](../compute-envs/aws-batch) and [Azure Batch](../compute-envs/azure-batch) compute environments. See [Advanced options][advanced-options] for detailed guidance. ### Summary Review your [General config](#general-config) and [Run parameters](#run-parameters) settings, then select **Launch**. The **Runs** tab shows your new run in a **submitted** status at the top of the list. Select the run name to open the [View Workflow Run][monitoring-overview] page and view the configuration, parameters, status of individual tasks, and run report. :::tip You can receive email notifications when a run completes or fails. Select **Manage your account** from the user menu, then toggle **Send notification email on workflow completion** at the bottom of the page. ::: ## Add new pipelines From the **Launchpad**, select **Add pipeline** to add a new pipeline with pre-saved parameters to your workspace. The fields on the new pipeline form are similar to the pipeline launch form. See [Add pipelines][add-pipelines] for instructions to add pipelines to your workspace via [Seqera Pipelines][seqera-pipelines] or the Launchpad. :::note Pipeline names must be unique per workspace. ::: ## Edit pipelines Workspace maintainers can edit existing pipeline details. Select the options menu next to the pipeline in the **Launchpad** list, then select **Edit** to open the pipeline parameters form, pre-filled with the pipeline's existing details. See [Add from the Launchpad][add-from-launchpad] for more information on the pipeline parameters form fields. Select **Update** to save the updated pipeline. ## URL query parameters The launch form can populate fields with values passed as URL query parameters. For example, append `?revision=master` to your launch URL to prefill the **Revision** field with `master`. Platform administrators can use custom launch URLs to hard-code required run and pipeline parameters for every run. Seqera Platform validates run parameters passed in the launch URL as follows: - Parameter names are **not** validated. You must provide valid and supported parameters to populate launch form fields without error. See supported parameter names in the following section. - Seqera Platform validates parameter values and shows warnings for any invalid values. - Disabled launch form fields, such as the `pipeline` field when launching a pre-saved pipeline, cannot be populated by URL. For parameters that accept arrays (multiple values), specify the parameter name for each value. For example: ``` ?labelIds=&labelIds= ``` Pass pipeline-specific run parameters with the `paramsText` query parameter. Include the name and value for any parameter defined in your [pipeline schema][pipeline-schema], in JSON format: ``` ?paramsText={"key1": "value1", "key2": "value2"} ``` :::note When you submit JSON-formatted `paramsText` input, Seqera Platform percent-encodes spaces, brackets, and other non-standard URL characters. For example: ``` ?paramsText={"key1": "value1", "key2": "value2"} ``` is formatted and added to the relevant launch form fields with this syntax: ``` %7B"key1":%20"value1",%20"key2":%20"value2"%7D ``` Seqera Platform ignores the added percent-encoding characters in form fields. You do not need to remove them manually before submitting your pipeline launch. ::: The following table lists the supported URL query parameters and their corresponding launch form fields: | **Launch form field** | **Query parameter name** | |------------------------------------------------|-----------------------------| | **Run setup** | | | Pipeline to launch | `pipeline` | | Revision number | `revision` | | Config profiles | `configProfiles` | | Workflow run name | `runName` | | Labels | `labelIds` | | Compute environment | `computeEnvId` | | Work directory | `workDir` | | **Run parameters** | | | Pipeline-specific run parameters | `paramsText` | | **Advanced settings** | | | Resource labels | `resourceLabelIds` | | Nextflow config file | `configText` | | Seqera Cloud config file | `towerConfig` | | Pull latest | `pullLatest` | | Stub run | `stubRun` | | Main script | `mainScript` | | Workflow entry name | `entryName` | | Schema name | `schemaName` | | Head job CPUs | `headJobCpus` | | Head job memory | `headJobMemoryMb` | | Workspace's pipeline secrets | `workspaceSecrets` | | User's pipeline secrets | `userSecrets` | | Pre-run script | `preRunScript` | | Post-run script | `postRunScript` | {/* links */} [credentials]: ../credentials/overview [pipeline-sharing]: https://docs.seqera.io/nextflow/sharing [git]: ../git/overview [pipeline-versioning]: ../pipelines/versioning [pipeline-revision]: ../pipelines/revision [nextflow-config-profile]: https://docs.seqera.io/nextflow/config#config-profiles [nextflow-workflow-outputs]: https://docs.seqera.io/nextflow/workflow#outputs [labels]: ../labels/overview [compute-envs]: ../compute-envs/overview [pipeline-schema]: ../pipeline-schema/overview [data-lineage]: ../data/data-lineage [workspace-settings-lineage]: ../orgs-and-teams/workspace-management#lineage [data-explorer]: ../data/data-explorer [datasets]: ../data/datasets [resource-labels]: ../resource-labels/overview [pipeline-secrets]: ../secrets/overview [advanced-options]: ../launch/advanced [custom-job-definition]: https://docs.seqera.io/nextflow/aws#custom-job-definition [monitoring-overview]: ../monitoring/overview [cache-resume]: ./cache-resume.mdx [add-pipelines]: ../getting-started/quickstart-demo/add-pipelines [seqera-pipelines]: https://seqera.io/pipelines [add-from-launchpad]: ../getting-started/quickstart-demo/add-pipelines#add-from-the-launchpad --- ## Usage limits Seqera Platform features have default limits per organization and workspace. :::info Seqera applies custom usage limits to academic institutions and commercial organizations evaluating Seqera Platform. [Contact us](https://seqera.io/contact-us/) for more information. ::: ## Organizations | Description | Basic | Cloud Pro + Enterprise | | ------------------------- | ----- | ---------------------- | | Members | 3 | 50, or per license | | Workspaces | 50 | 50, or per license | | Teams | 20 | 20, or per license | | Run history | 250 | 250, or per license | | Active runs | 3 | 100, or per license | | Running Studio sessions | 1 | 1000, or per license | | Seqera Compute: Storage | 25 GB per month | Unlimited | | Seqera Compute: CPU cores | 100 | 1000 | :::note Studios data egress is throttled at 100 GB per 24 hours per IP address, and 1 TB per `user_id` per month. ::: ## Workspaces | Description | Basic | Cloud Pro + Enterprise | | --------------------------- | ----- | ---------------------- | | Participants | 3 | 50, or per license | | Pipelines | 100 | 100, or per license | | Datasets | 100 | 1000, or per license | | Labels | 1000 | 1000, or per license | | Seqera Compute environments | 5 | 20 | :::note Some Enterprise instances on older licenses are limited to 100 labels per workspace. [Contact support](mailto:support@seqera.io) to upgrade your license. ::: ## Datasets | Description | Default limit | | -------------------- | ------------- | | File size | 10 MB | | Versions per dataset | 100 | If you need higher limits, [contact us](https://seqera.io/contact-us/) to discuss your requirements. --- ## Monitoring cloud costs Monitor cloud costs to manage resources effectively and prevent unexpected expenses when running pipelines in Seqera Platform. ## Resource labels Use [Resource labels](../resource-labels/overview) in your compute environments to annotate and track the actual cloud resources consumed by a pipeline run. Resource labels are applied to the resources spawned during a run and sent to your cloud provider in `key=value` format. For full cost accounting — including storage and networking — combine resource labels with your cloud provider's native cost tools rather than custom wrapper scripts that dedicate whole instances to single jobs. See [Include Seqera resource labels in AWS billing reports](../resource-labels/overview#include-seqera-resource-labels-in-aws-billing-reports). ## Seqera cost estimate The [run details](../monitoring/run-details) page includes an **Estimated cost** display on the **Metrics** tab. This is the total estimated compute cost of all tasks in the pipeline run. Per-task cost — along with the machine type, price model, and requested CPU and memory used to derive it — is shown in each task's **Metrics** details. The Seqera cost estimator should only be used for at-a-glance heuristic purposes. For accounting and legal cost reporting, use resource labels and leverage your compute platform's native cost reporting tools. :::tip Per-task metrics, including estimated cost, are also available programmatically through the Platform API for building custom cost dashboards across runs. See the [describe workflow task](https://docs.seqera.io/platform-api/describe-workflow-task) and [list workflow tasks](https://docs.seqera.io/platform-api/list-workflow-tasks) API endpoints. ::: The compute cost of a task is computed as follows: $$ \text{Task cost} = \text{VM hourly rate} \times \text{VM fraction} \times \text{Task runtime} $$ $$ \quad \text{VM fraction} = \text{max} ( \frac{\text{Task CPUs}}{\text{VM CPUs}}, \frac{\text{Task memory}}{\text{VM memory}} ) $$ $$ \quad \text{Task runtime} = ( \text{Task complete} - \text{Task start} ) $$ See also: **cost**, **start**, **complete**, **cpus**, and **memory** in the task table. Seqera uses a database of prices for AWS, Azure, and Google Cloud, across all instance types, regions, and zones, to fetch the VM price for each task. This database is updated periodically to reflect the most recent prices. :::note Prior to version 22.4.x, the cost estimate used `realtime` instead of `complete` and `start` to measure the task runtime. The `realtime` metric tends to underestimate the billable runtime because it doesn't include the time required to stage input and output files. ::: The estimated cost is subject to several limitations: - It doesn't account for the cost of storage, network, the head job, or how tasks are mapped to VMs. As a result, it tends to underestimate the true cost of a pipeline run. - On a resumed pipeline run, the cost of cached tasks is included in the estimated cost. This estimate is an aggregation of all compute costs associated with the run. As a result, the total cost of multiple attempts of a pipeline run tends to overestimate the actual cost, because the cost of cached tasks may be counted multiple times. For accurate cost accounting, you should use the cost reporting tools for your cloud provider. ## Cloud provider cost monitoring and alerts AWS, Google Cloud, and Microsoft Azure provide cost alerting and budgeting tools to enable effective cloud resource management and prevent unexpected costs. ### AWS - **Budgets**: [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) lets you set custom cost and usage budgets with alerts when costs or usage exceed pre-defined thresholds. Set up notifications via email or SNS (Simple Notification Service) to receive alerts when budget thresholds are reached. - **Cost Explorer**: [AWS Cost Explorer](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-what-is.html) provides cost management tools to visualize, understand, and manage your AWS costs and usage over time. - **Cost Anomaly Detection**: [AWS Cost Anomaly Detection](https://docs.aws.amazon.com/cost-management/latest/userguide/getting-started-ad.html) uses machine learning models to detect and alert on anomalous spend patterns in your deployed AWS services. ### Google Cloud - **Budgets and budget alerts**: [Budgets](https://cloud.google.com/billing/docs/how-to/budgets) allow you to set budget thresholds for your GCP projects. When costs exceed these thresholds, you can receive alerts via email, SMS, or notifications in the Google Cloud Console. - **Cost management tools**: [Cloud Billing](https://cloud.google.com/billing/docs/onboarding-checklist) provides cost management tools such as billing reports and spend visualization to help you analyze and understand your GCP costs. ### Microsoft Azure - **Cost Management**: [Microsoft Cost Management](https://learn.microsoft.com/en-us/azure/cost-management-billing/costs/overview-cost-management) is a suite of FinOps tools that help organizations analyze, monitor, and optimize their Microsoft Cloud costs. - **Cost alerts**: Create [alerts](https://learn.microsoft.com/en-us/azure/cost-management-billing/costs/overview-cost-management#monitor-costs-with-alerts) for usage anomalies and costs that exceed pre-defined thresholds. --- ## Dashboard The Seqera Platform **Dashboard** is accessed from the user menu and provides an overview of: - Pipeline runs in your personal and organization workspaces. - Studio sessions in your organization workspaces only. - Fusion usage in your organization workspaces. - Resource usage for your organization workspaces. ## Pipelines You can explore the status of pipelines in your personal and in organizational workspaces. On the **Dashboard** page, select **Pipelines**. ### Filters and summary The **Dashboard** view defaults to all organizations and workspaces you can access. Select the **View** drop-down to filter by specific organizations and workspaces, or to view statistics for your personal workspace only. You can filter by time, including a custom date range of up to 12 months. To filter the set of pipelines, select **Filter**. When a filter is applied, the button icon and color changes. ### Export data Select **Export data** in the filter panel near the top of the page to export dashboard data, based on the filters you have applied, in a CSV file. ### Pipelines per organization The pipeline totals for your selected filters are displayed for each organization that you have access to. Depending on the filter selected, each card details a separate workspace or organization. Total pipelines for each organization are arranged by workspace and status. For a detailed view, you can do one of the following: - Select a pipeline integer value in the table to navigate to a list filtered by the status and time range selected. - Select a workspace name in the table to navigate to a list filtered by the workspace selected. ## Studios You can explore the status of Studio sessions in your organizational workspaces. On the **Dashboard** page, select **Studios**. The following statuses are listed with the number of Studio sessions in each status: - `Building` - `Build-failed` - `Starting` - `Running` - `Stopping` - `Stopped` - `Errored` ### Filters and summary The **Dashboard** view defaults to all organizations and workspaces you can access. Select the **View** drop-down to filter by organizations and workspaces. Select a status in the table to navigate to a list filtered by the status selected. ### Export data Select **Export data** in the view panel near the top of the page to export a CSV of the dashboard data for the selected organizations and workspaces. ## Fusion Select a workspace from the drop-down to view Fusion usage for the current and previous month. The usage is displayed in GB and shows a percentage change from the previous month. ## Resource usage You can explore compute resource consumption across your organization workspaces. On the **Dashboard** page, select **Resource usage**. Monthly CPU hours aggregated across your organization workspaces are displayed. :::note The **Resource usage** view is visible to all members of an organization. ::: ### Filters and summary Select the **View** drop-down to select an organization. Select the **Date** drop-down to filter by year. ### Export data Select **Export data** in the view panel near the top of the page to export a CSV of the dashboard data for the selected organization. [ds]: ../studios/overview --- ## Overview Workflow executions submitted in Seqera Platform can be monitored wherever you have an internet connection. The **Runs** tab contains all previous runs in the workspace. Each new or resumed run is given a random name such as _grave_williams_. Each row corresponds to a specific run. As a run executes, it can transition through the following states: - `submitted`: Pending execution - `running`: Running - `succeeded`: Completed successfully - `failed`: Successfully executed, where at least one task failed with a `terminate` [error strategy](https://docs.seqera.io/nextflow/process#errorstrategy) - `cancelled`: Stopped manually during execution - `unknown`: Indeterminate status Select the name of a run from the list to display that run's [execution details](./run-details.mdx). ## Save run as pipeline From the **Runs** list, any run can be saved as a new pipeline for future use, regardless of run status. Select the options menu next to any run in the list, then select **Save as pipeline**. In the dialog box shown, you can edit the pipeline name, add labels, and **Save**. You can **Review and edit** any run details prior to saving the pipeline. After you've saved the pipeline, it is listed on the **Launchpad** and can be run from the same workspace where it was created. :::note Only runs launched via Platform UI, API, CLI, or Seqerakit can be saved as pipelines to Launchpad. Runs launched via Nextflow CLI using the `--with-tower` flag cannot be saved as pipelines in Platform. ::: ## All runs view The **All runs** page, accessed from the user menu, provides a comprehensive overview of the runs accessible to a user across the entire Seqera instance. This facilitates overall status monitoring and early detection of execution issues from a single view, split across organizations and workspaces. The **All runs** view defaults to all organizations and workspaces you can access. Select the drop-down next to **View** to filter by specific organizations and workspaces, or to view runs from your personal workspace only. ### Search The **Search workflow** bar filters by one or more `:` entries: - `status` - `label` - `workflowId` - `runName` - `username` - `projectName` - `after`: YYYY-MM-DD - `before`: YYYY-MM-DD - `sessionId` - `is:starred` The field suggests valid keywords as you type. Suggested results for `label:` include available labels from all workspaces. Labels present in multiple workspaces are only suggested once. Search covers all workflow runs in a workspace. Enter a query in the Search workflow field. Platform identifies each valid `keyword:value` substring, combines the remaining text into a single freeform string, and filters runs using all of these criteria. For example: `rnaseq username:john_doe status:succeeded after:2024-01-01` will retrieve all runs from the workspace that meet the following criteria: - Ended successfully (`status:succeeded`) - Launched by user john_doe (`username:john_doe`) - Include `rnaseq` in the data fields covered by the free text search - Submitted after January 1, 2024 The freetext search uses a _partial_ match to find runs, so it will search for `*freetext*`. The `keyword:value` item uses an _exact_ match to filter runs, so `username:john` will not retrieve runs launched by `john_doe`. :::caution Filtering elements are combined with **AND** logic. This means that queries like `status:succeeded, status:submitted` are formally valid but return an empty list because a workflow can only have one status. The freeform text result of all the `keyword:value` pairs is merged into a unique string that includes spaces. This may result in an empty list of results if the search query contains typos. ::: :::note Keywords corresponding to dates (`after` or `before`) are automatically converted to valid ISO-8601, taking your timezone into account. Partial dates are also supported: `before:2022-5` is automatically converted to `before:2022-05-01T00:00:00.000Z`. ::: Seqera will suggest matching keywords while you type. Valid values are also suggested for some keywords, when supported. ### Search keywords - **Freeform text** The search box allows you to search for partial matches with `project name`, `run name`, `session id`, or `manifest name`. Use wildcards (`*`) before or after keywords to filter results. - **Exact match keywords** - `workflowId:3b7ToXeH9GvESr`: Search workflows with a specific workflow ID. - `runName:happy_einstein`: Search workflows with a specific run name. - `sessionId:85d35eae-21ea-4294-bc92-xxxxxxxxxxxx`: Search workflows with a specific session ID. - `projectName:nextflow-io/hello`: Search workflows with a specific project name. - `userName:john_doe`: Search workflows by a specific user. - `status:succeeded`: Search workflows with a specific status (`submitted`, `running`, `succeeded`, `failed`, `cancelled`, `unknown`). - `before:2024-01-01`: Search workflows submitted on or before the given date in YYYY-MM-DD format. - `after:2024-01-01`: Search workflows submitted on or after the given date in YYYY-MM-DD format. - `label:label1 label:label2`: Search workflows with specific labels. - `is:starred`: Search workflows that have been starred by the user. --- ## Run details Select a workflow run from the **Runs** list to open a run details page. The top of the page contains basic run details and a progress overview for an at-a-glance view of the run's status: - View and copy the run ID, pipeline name and repository, pipeline work directory, compute environment, and launch date. - Select the star icon to favorite the run and find it more easily via a filter view in the runs list later. - Use the options menu to apply labels, relaunch, resume, or delete the run, save the run as a new pipeline, or publish a new pipeline [version](../pipelines/versioning) (if the run was launched from an unnamed draft). Select the tabs below the workflow run progress bar to view further run details: - **Tasks**: View the status and progress of pipeline tasks and [processes](#processes), including extensive [task details](#tasks). - **Logs**: View and download the pipeline run's execution logs. - **Metrics**: View resource [metrics](#wall-time) for the run. - **Configuration**: View Nextflow configuration files and the resolved [configuration](#configuration) used for the run. - **Inputs**: View pipeline parameters used by the run, including their lineage records. - **Outputs**: View files produced by the run, including reports and lineage records for every published file. - **Containers**: View the details of containers used in the run, if any. - **Run Info**: View details about the [run](#run-details), [infrastructure](#infrastructure-details), and [executor](#executors-details). :::tip Data lineage is made available on request. Please contact your Seqera account manager. Lineage-aware fields and tabs only display data when the run was executed with data lineage enabled. There are three ways to enable lineage: - [**Settings > Lineage**][workspace-lineage-settings]. A workspace maintainer configures the cloud credentials, region, and (optionally) bucket name where lineage records are stored. Select **Enable lineage by default** to make the launch form lineage toggle default to on for every run launched in the workspace. - **Launch form toggle**. When launching a pipeline, toggle lineage on or off for the individual run. - **Nextflow configuration**. Set `lineage.enabled = true` in your pipeline's Nextflow config. See [Getting started with data lineage][nextflow-lineage-tutorial] for the underlying lineage data model. ::: ![Task status overview](./_images/task-status-tiles.png) The cards at the top of the **Tasks** tab provide a real-time status of all tasks in the pipeline run: - **Pending**: The task has been created, but not yet submitted to an executor. - **Submitted**: The task has been submitted to an executor, but is not yet running. - **Running**: The task has been launched by an executor (the precise definition of "running" may vary for each executor). - **Cached**: A previous (and valid) execution of the task was found and used instead of executing the task again. See [Cache and resume](../launch/cache-resume). - **Succeeded**: The task completed successfully. - **Failed**: The task failed. - **Aborted**: The task was submitted, but the run was cancelled or failed before the task could begin. ### Processes The **Processes** panel displays the status of each process in a pipeline run. In Nextflow, a process is an individual step in a pipeline, while a task is a particular invocation of a process for given input data. In the panel, each process is shown with a progress bar indicating how many tasks have been completed for that process. The progress bar is color-coded based on task status (**created**, **submitted**, **completed**, **failed**). Select a process to navigate to the [Tasks](#tasks) panel and filter the table contents by the selected process. ### Tasks The **Tasks** panel shows all the tasks that were executed in the run, including the following task details: | Label | Description | |-------|-------------| | **task_id** | Unique identifier for the task. | | **process** | Process name. | | **tag** | User-defined label or tag associated with the task. | | **hash** | Nextflow task hash value. | | **status** | Task execution status (e.g., `COMPLETED`, `FAILED`, `RUNNING`). | | **attempt** | Number of execution attempts for this task (for retry logic). | | **exit** | Task exit code. | | **container** | Container image used to execute the task. | | **native_id** | Native job ID assigned by the executor (e.g., cluster job ID). | | **submit** | Timestamp when the task was submitted for execution. | | **duration** | Total execution time for the task. | | **realtime** | CPU wall time the task actually ran. | | **% cpu** | Percentage of CPU utilization during task execution. | | **% mem** | Percentage of memory utilization during task execution. | | **peak_rss** | Peak resident set size (physical memory usage). | | **peak_vmem** | Peak virtual memory usage. | | **rchar** | Number of characters read from storage. | | **wchar** | Number of characters written to storage. | | **vol_ctxt** | Number of voluntary context switches. | | **inv_ctxt** | Number of involuntary context switches. | | **lineage_id** | Lineage ID (LID) of the task's `TaskRun` record. Populated only when lineage tracking is active for the run. Select the LID to navigate to the lineage record. | Use the search bar to filter tasks with substrings in the table columns such as **process**, **tag**, **hash**, and **status**. For example, if you enter `succeeded` in the **Search task** field, the table displays only tasks that succeeded. #### Task details ![Task details](./_images/task-details.png) Select a task in the task table to open the **Task details** dialog. The dialog has the following tabs: - **About** - **Metrics** - **Execution log** - **Data Explorer** - **Container** :::note If lineage is enabled for the run, the **About** tab content includes **Inputs** and **Outputs** tabs. The **Inputs** and **Outputs** tabs show every input or output consumed by the task, including the name, its lineage type (`Collection` or `Path`), the source path, the lineage labels assigned to it, and the lineage ID of the corresponding lineage record. Select a name to open the file in [Data Explorer](../data/data-explorer). Select a lineage ID or label to navigate to that lineage record. ::: #### About - **Name**: Process name and tag. - **Status**: Exit code, task status, attempts. - **Native ID**: Unique identifier assigned by the underlying execution executor to a specific job. - **Command**: Task script, defined in the pipeline process. - **Environment**: Environment variables supplied to the task. - **Work directory**: Directory where the task was executed. - **Inputs**: File inputs to the task and associated lineage data. - **Outputs**: File outputs from the task and associated lineage data. - **Upstream**: Links to related upstream tasks. - **Downstream**: Links to related downstream tasks. #### Metrics - **Execution time**: Metrics for task submission, start, and completion time: | Label | Description | |-------|-------------| | **submitted** | Task submission timestamp. | | **started** | Task execution timestamp. | | **completed** | Task completion timestamp. | | **total duration** | Time elapsed from task submission to completion, including scheduling time. | | **script execution time** | Task script execution time. | - **Requested resources**: Metrics for the resources requested by the task: | Label | Description | |-------|-------------| | **container image** | Container image name used to execute the task. | | **queue** | The queue that the executor used to run the process. | | **cpus** | Number of CPUs requested for task execution. | | **memory** | Memory requested for task execution. | | **disk space** | Disk space requested for task execution. | | **time limit** | Time requested for task execution. | | **executor** | The Nextflow executor used for this task. | | **cloudZone** | The cloud zone (region) where the task was executed. | | **machineType** | The virtual machine type used for this task. | | **priceModel** | The price model used to calculate the task computation cost. | | **estimated cost** | The estimated cost to compute this task. | - **Used resources**: Metrics for the actual resources used by the task: | Label | Description | |-------|-------------| | **pcpu** | Percentage of CPU used by the task. | | **rss** | Real memory (resident set) size of the task. | | **peakRss** | Peak of real memory used. | | **vmem** | Virtual memory size of the task. | | **peakVmem** | Peak of virtual memory used. | | **rchar** | Number of bytes the task read, using any read-like system call from files, pipes, tty, etc. | | **wchar** | Number of bytes the task wrote, using any write-like system call. | | **readBytes** | Number of bytes the task read directly from disk. | | **writeBytes** | Number of bytes the task originally dirtied in the page-cache (assuming they will go to disk later). | | **syscr** | Number of read-like system call invocations that the task performed. | | **syscw** | Number of write-like system call invocations that the task performed. | | **volCtxt** | Number of voluntary context switches. | | **invCtxt** | Number of involuntary context switches. | #### Execution log The **Execution log** tab provides a real-time log of the selected task's execution. Task execution and other logs (such as `stdout` and `stderr`) are available for download if they are still available in your compute environment. :::note Real-time log streaming is available only for compute environments that stream logs from a cloud logging service: AWS Batch, Azure Batch, Google Cloud Batch, Kubernetes, and the AWS Cloud and Azure Cloud environments. HPC compute environments (such as Slurm, Grid Engine, LSF, and PBS Pro) retrieve the log from the task work directory rather than streaming it. The **Execution log** tab does not refresh automatically while a task runs. Change tabs or refresh the page to load the latest log content. See [Execution logs don't update in real time for HPC compute environments](../troubleshooting_and_faqs/troubleshooting#execution-logs-dont-update-in-real-time-for-hpc-compute-environments). ::: #### Data Explorer If the pipeline work directory is in cloud storage, this tab shows a [Data Explorer](../data/data-explorer) view of the task's work directory location with the files associated with the task. #### Container This tab contains the image and build details of the container used to execute the task: | Label | Description | |-------|-------------| | **Target image** | The container image used to execute the workflow task. | | **Source image** | The container image specified in the workflow configuration, if available. | | **Request ID** | The unique request ID associated with the container. | | **Request time** | The timestamp when the container request was made. | | **Build ID** | The unique build ID assigned when the container was provisioned. | | **Mirror ID** | The unique mirror ID assigned when the container was copied between repositories. | | **Scan ID** | The unique scan ID from the vulnerability security scan of the container. | | **Cached** | Indicates whether the container was previously built in an earlier request. | | **Freeze** | Indicates whether the container was provisioned for persistent storage using Wave freeze mode. | The **Logs** tab contains a window with the Nextflow execution log console output. Select **Download log files** to download: - Nextflow console output, in TXT format. - Nextflow log file, in LOG format. - Execution timeline graph, in HTML format. ![Metrics overview](./_images/metrics-tiles.png) The cards at the top of the **Metrics** tab display a real-time summary of the resources used by the run. #### Wall time Wall time is the duration of the entire workflow run, from submission to completion. While the run is in progress, wall time is a measure of the time elapsed since run start. #### CPU time CPU time is the total CPU time used by all tasks, measured in CPU hours. It is based on the CPUs _requested_, not the actual CPU usage. The CPU time of an individual task is computed as follows: $$ \text{CPU time (CPU-hours)} = \text{Task CPUs} \times \text{Task runtime} $$ The runtime of an individual task is computed as follows: $$ \text{Task runtime} = \text{Task complete} - \text{Task start} $$ See also: **cpus**, **start**, and **complete** in the task table. #### Memory Memory is the total memory used by all tasks. It is based on the memory _requested_, not the actual memory usage. See also: **peakRss** in the task table. #### Data read and write Data read and Data write are the total amount of data (in GB) read from and written to storage. See also: **readBytes** and **writeBytes** in the task table. #### Estimated cost An estimated cost for the run. See [Seqera cost estimate](../monitoring/cloud-costs#seqera-cost-estimate) for details. #### Load ![Load](./_images/load.png) The **Load** panel displays the current number of running tasks and CPU cores vs the maximum number of tasks and CPU cores for the entire pipeline run. These metrics measure the level of parallelism achieved by the pipeline. Use these metrics to determine whether your pipeline runs are fully utilizing the capacity of your compute environment. #### Utilization ![Utilization](./_images/utilization.png) The **Utilization** panel displays the average resource utilization of all tasks that have completed successfully in a pipeline run. The CPU and memory efficiency of a task are computed as follows: $$ \text{CPU efficiency (\%)} = \text{CPU usage (\%)} \times \text{Task CPUs} $$ $$ \text{Memory efficiency (\%)} = \frac{ \text{Peak memory usage} }{ \text{Task memory} } \times \text{100 \%} $$ See also: **pcpu**, **cpus**, **peakRss**, and **memory** in the task table. These metrics measure how efficiently the pipeline is using its compute resources. Low utilization indicates that the pipeline may be over-requesting resources for some tasks. #### Interactive resource plots ![Interactive CPU plot](./_images/interactive-plot.png) The **CPU**, **Memory**, **Job duration**, and **I/O** interactive plots visualize detailed resource usage, grouped by process. These metrics include succeeded and failed tasks. Use these plots to quickly inspect a pipeline run to determine the resources requested and consumed by each process. :::tip Hover the cursor over each box plot to show more details. ::: The **Configuration** tab contains information about the Nextflow configuration files and the Nextflow command used for the run. #### Configuration ![Configuration](./_images/configuration.png) The **Configuration** window displays the locations of the Nextflow configuration files used for the run, and the resolved configuration resulting from those configuration files. #### Command ![Nextflow command](./_images/command.png) The **Command** window displays the Nextflow command used for the run. The **Inputs** tab consolidates the pipeline parameters and the input files used by the run. #### Parameters ![Parameters](./_images/parameters.png) The **Parameters** window displays the pipeline parameters configured for the run, with options to view, copy, or download the parameters in Groovy, JSON, or YAML format. #### Input files The **Input files** table displays every dataset, file, and collection that was used as input for the run: | Column | Description | |--------|-------------| | **Input Name** | Display name of the input. Select the name to open the file in [Data Explorer](../data/data-explorer) or in the corresponding [Dataset](../data/datasets). | | **Type** | Lineage type, such as `Collection` or `Path`. | | **File Path** | Full path to the input. The path is truncated; hover for the complete path. Select the path to open it in [Data Explorer](../data/data-explorer). | | **Lineage ID** | Lineage ID (LID) of the input's lineage record. Only populated when [lineage tracking is enabled][nextflow-lineage-tutorial]. | | **Lineage Labels** | Lineage labels assigned to the input. Each label is a clickable link that navigates to the lineage record for that label. | If the run was not launched with any input files or datasets, the table is empty. The **Outputs** tab links to every file the run published to its output directory: - **Reports** — The named report files configured for the run, such as the MultiQC report or any reports declared in `tower.yml`. #### Reports ![Reports](./_images/reports.png) The **Reports** sub-tab contains a table with the names, details, and paths to all [reports](../reports/overview) generated by the run, if any were configured. Select a report to open a Data Explorer file preview of the report, with options to open the report in a new tab or download it. :::info The containers feature is only available from Nextflow 25.03.1-edge. ::: ![Containers](./_images/containers.png) The **Containers** tab displays the details of containers used in the run, if any. Container details shown include: - **Target image**: Container image used to execute the task. - **Source image**: Container image specified in the workflow configuration, if available. - **Request ID**: Unique request ID associated with the container. - **Request time**: Timestamp when the container request was made. - **Build ID**: Unique build ID assigned when the container was provisioned, linked to the Wave container build report. - **Mirror ID**: Unique mirror ID assigned when the container was copied between repositories, linked to the Wave mirror report. - **Scan ID**: Unique scan ID for the vulnerability security scan of the container, linked to the Wave scan report. - **Cached**: Indicates if the container was built during a previous request. - **Freeze**: Indicates if the container was provisioned for persistent storage using Wave freeze mode. The **Run Info** tab contains at-a-glance details about the run, infrastructure, and executor. When lineage tracking is enabled, it also displays lineage information. Hover over the information icon next to a card's name to view a value description. Select the icons next to any run detail values to copy them. #### Run details ![Run details](./_images/run-details.png) The **Run details** view displays basic run details: - **Pipeline** name. Select **View pipeline details** to navigate to the pipeline details page. - **Pipeline version** information. Select **View version** to navigate to the pipeline details page. - **Workflow repository**. Select **View repository** to navigate to the pipeline Git repository. - Run **ID**. - **Run start time**. - **Total run duration**. - **Launch user**. Select **View user runs** to view a list of the launch user's runs in the same workspace. - **Executor(s)** used for the run (AWS Batch, Azure Batch, etc.). - **Revision and Git commit ID**. The pipeline version and Git commit ID associated with the version used for the run. #### Infrastructure details ![Infrastructure details](./_images/infra-details.png) The **Infrastructure details** view displays compute environment and work directory information: - **Compute environment** name. Select **Preview** to view a window with basic compute environment details, or **View** to navigate to the compute environment page. - **(Provider) operation ID**. The unique identifier for the task submitted to the cloud provider or compute platform, such as an AWS Batch operation ID. - **Work directory**. Select **View** to browse the work directory in Data Explorer. - **Compute environment ID**. #### Executor(s) details ![Infrastructure details](./_images/executor-details.png) View run executor details: - The **Nextflow version** and **Nextflow session ID** for the run. - The version of [**Fusion**](https://docs.seqera.io/fusion) used in the run, if enabled. - Whether the run used [**Wave**](https://docs.seqera.io/wave) (**Enabled** or **Disabled**). [nextflow-lineage-tutorial]: https://docs.seqera.io/nextflow/tutorials/data-lineage [nextflow-label-directive]: https://docs.seqera.io/nextflow/reference/process#label [workspace-lineage-settings]: ../orgs-and-teams/workspace-management#lineage --- ## Custom roles :::info Custom roles are only available to Seqera Platform Cloud Pro accounts. ::: Seqera Platform supports custom roles to define permissions-based access control at a more granular level than the six default [workspace participant roles](./roles.md#workspace-participant-roles). ### Create custom roles Organization owners can add custom roles and assign read, write, execute, admin, and delete permissions for every Seqera resource type: 1. Select your organization name from the organization and workspace switcher in the top navigation. 1. Select **Access control** to view the list of default and custom roles available in your organization. 1. Select **Add role**. 1. Enter a role **Name** and optional **Description**. 1. From the **Permissions** list, select the **Read**, **Write**, **Execute**, **Admin**, and **Delete** permissions your custom role requires for each resource type. 1. Select **Add** to create the custom role and return to the **Access control** roles list. Select **Edit** or **Delete** to manage existing custom roles in the list. ### Permissions Individual permissions grant read, write, execute, admin, or delete access for each Seqera entity. Individual read and write permissions may grant access for multiple operations via the Platform UI, API, and other programmatic tools such as Platform CLI. For example, the `action:read` permission allows a user to view the list of actions in a workspace, view the details of a specific action, and view available action types. #### Compute | Permission | Description | API endpoint | |------------|-------------|--------------| | **compute_environment:read** | List all compute environments | `GET /compute-envs` | | | View compute environment details | `GET /compute-envs/{computeEnvId}` | | **compute_environment:write** | Create a new compute environment | `POST /compute-envs` | | | Edit an existing compute environment | `PUT /compute-envs/{computeEnvId}` | | | Set a compute environment as primary | `POST /compute-envs/{computeEnvId}/primary` | | | Disable compute environment | `POST /compute-envs/{computeEnvId}/disable` | | | Enable compute environment | `POST /compute-envs/{computeEnvId}/enable` | | | Validate compute environment name availability | `GET /compute-envs/validate` | | **compute_environment:delete** | Delete a compute environment | `DELETE /compute-envs/{computeEnvId}` | | **credentials:read** | List all credentials in workspace | `GET /credentials` | | | View credential details | `GET /credentials/{credentialsId}` | | **credentials:write** | Add new credentials | `POST /credentials` | | | Edit existing credentials | `PUT /credentials/{credentialsId}` | | | Validate credentials | _(Used by Platform)_ | | | Validate credential name availability | `GET /credentials/validate` | | **credentials:delete** | Delete credentials | `DELETE /credentials/{credentialsId}` | | **credentials_encrypted:read** | Get encrypted credentials | `GET /credentials/{credentialsId}/keys` | | **pipeline_secrets:read** | List all pipeline secrets | `GET /pipeline-secrets` | | | View pipeline secret details | `GET /pipeline-secrets/{secretId}` | | **pipeline_secrets:write** | Create a new pipeline secret | `POST /pipeline-secrets` | | | Validate secret name availability | `GET /pipeline-secrets/validate` | | | Edit an existing pipeline secret | `PUT /pipeline-secrets/{secretId}` | | **pipeline_secrets:delete** | Delete a pipeline secret | `DELETE /pipeline-secrets/{secretId}` | | **platform:read** | List available platforms | `GET /platforms` | | | List platform regions | `GET /platforms/{platformId}/regions` | | | View platform details | `GET /platforms/{platformId}` | #### Data | Permission | Description | API endpoint | |------------|-------------|--------------| | **data_link:read** | List all data-links (cloud buckets) | `GET /data-links` | | | View data-link details | `GET /data-links/{dataLinkId}` | | | Resolve data-link cloud-scheme URLs | _(Used by Platform)_ | | **data_link:write** | Refresh data-link cache | `GET /data-links/cache/refresh` | | | Create a custom data-link | `POST /data-links` | | | Edit data-link metadata | `PUT /data-links/{dataLinkId}` | | **data_link:delete** | Remove a data-link from workspace | `DELETE /data-links/{dataLinkId}` | | **data_link:admin** | Hide data-links | _(Used by Platform)_ | | | Show data-links | _(Used by Platform)_ | | **data_link_object:read** | Browse data-link contents | `GET /data-links/{dataLinkId}/browse` | | | Browse data-link contents at the given path | `GET /data-links/{dataLinkId}/browse/{path}` | | | Browse data-link directory tree | `GET /data-links/{dataLinkId}/browse-tree` | | | Download files from data-link | `GET /data-links/{dataLinkId}/download/{filePath}` | | | Generate download URL for data-link files | `GET /data-links/{dataLinkId}/generate-download-url` | | | Generate download script | `GET /data-links/{dataLinkId}/script/download` | | | Sign data-link URLs for batch access | _(Used by Platform)_ | | **data_link_object:write** | Upload files to data-link | `POST /data-links/{dataLinkId}/upload` | | | Upload files to data-link at the given path | `POST /data-links/{dataLinkId}/upload/{dirPath}` | | | Complete file upload to data-link | `POST /data-links/{dataLinkId}/upload/finish` | | | Complete file upload to data-link at the given path | `POST /data-links/{dataLinkId}/upload/finish/{dirPath}` | | **data_link_object:delete** | Delete files from data-link | `DELETE /data-links/{dataLinkId}/content` | | **dataset:read** | List datasets (legacy endpoint) | `GET /workspaces/{workspaceId}/datasets` | | | List workspace dataset versions (legacy endpoint) | `GET /workspaces/{workspaceId}/datasets/versions` | | | List dataset versions (legacy endpoint) | `GET /workspaces/{workspaceId}/datasets/{datasetId}/versions` | | | View dataset metadata (legacy endpoint) | `GET /workspaces/{workspaceId}/datasets/{datasetId}/metadata` | | | Download dataset | _(Used by Platform)_ | | | List all datasets | `GET /datasets` | | | List latest dataset versions | `GET /datasets/versions` | | | List versions for a specific dataset | `GET /datasets/{datasetId}/versions` | | | List datasets used in a pipeline launch | `GET /launch/{launchId}/datasets` | | | View dataset metadata | `GET /datasets/{datasetId}/metadata` | | | Download dataset files | `GET /datasets/{datasetId}/v/{version}/n/{fileName}` | | | Fetch preview content for a URL without persisting | `POST /datasets/preview-url` | | | Preview linked dataset content | `GET /datasets/{datasetId}/v/{version}/preview` | | **dataset:write** | Create dataset (legacy endpoint) | `POST /workspaces/{workspaceId}/datasets` | | | Edit dataset (legacy endpoint) | `PUT /workspaces/{workspaceId}/datasets/{datasetId}` | | | Upload dataset (legacy endpoint) | `POST /workspaces/{workspaceId}/datasets/{datasetId}/upload` | | | Create a new dataset | `POST /datasets` | | | Edit dataset metadata | `PUT /datasets/{datasetId}` | | | Upload files to dataset | `POST /datasets/{datasetId}/upload` | | | Link external URL as dataset version | `POST /datasets/{datasetId}/link` | | | Validate URL for dataset linking | `POST /datasets/validate-url` | | **dataset:delete** | Delete dataset (legacy endpoint) | `DELETE /workspaces/{workspaceId}/datasets/{datasetId}` | | | Delete a single dataset | `DELETE /datasets/{datasetId}` | | | Delete multiple datasets | `DELETE /datasets` | | **dataset:admin** | Hide any workspace user's datasets | `POST /datasets/hide` | | | Show any workspace user's datasets | `POST /datasets/show` | | | Disable any workspace user's dataset version | `POST /datasets/{datasetId}/versions/{version}/disable` | | **dataset_label:write** | Add labels to datasets | `POST /datasets/labels/add` | | | Remove labels from datasets | `POST /datasets/labels/remove` | | | Apply label sets to datasets | `POST /datasets/labels/apply` | #### Pipelines | Permission | Description | API endpoint | |------------|-------------|--------------| | **action:read** | View action details | `GET /actions/{actionId}` | | | View available action types | `GET /actions/types` | | | List all actions in workspace | `GET /actions` | | **action:execute** | Trigger an action to run | `POST /actions/{actionId}/launch` | | **action:write** | Create a new action | `POST /actions` | | | Edit an existing action | `PUT /actions/{actionId}` | | | Test action configuration | _(Used by Platform)_ | | | Pause a running action | `POST /actions/{actionId}/pause` | | | Validate action name availability | `GET /actions/validate` | | **action:delete** | Delete an action | `DELETE /actions/{actionId}` | | **action_label:write** | Apply resource labels when adding an action | Sub-operation on `POST /actions` | | | Apply resource labels when editing an action | Sub-operation on `PUT /actions/{actionId}` | | | Add labels to actions | `POST /actions/labels/add` | | | Remove labels from actions | `POST /actions/labels/remove` | | | Apply label sets to actions | `POST /actions/labels/apply` | | **container:read** | View container details | _(Used by Platform)_ | | | List workflow containers | _(Used by Platform)_ | | **launch:read** | View launch details | `GET /launch/{launchId}` | | **pipeline:read** | View pipeline repository information | `GET /pipelines/info` | | | View pipeline schema and parameters | `GET /pipelines/{pipelineId}/schema` | | | View pipeline schema from repository URL | _(Used by Platform)_ | | | View pipeline launch configuration | `GET /pipelines/{pipelineId}/launch` | | | List available pipeline repositories | `GET /pipelines/repositories` | | | List all pipelines in workspace | `GET /pipelines` | | | View pipeline details | `GET /pipelines/{pipelineId}` | | | List pipeline versions | `GET /pipelines/{pipelineId}/versions` | | | Fetch pipeline optimization | _(Used by Platform)_ | | **pipeline:write** | Modify pipeline details when launching a pipeline run | Sub-operation on `POST /workflow/launch` | | | Add a new pipeline to workspace | `POST /pipelines` | | | Edit pipeline (default version) configuration | `PUT /pipelines/{pipelineId}` | | | Configure pipeline | _(Used by Platform)_ | | | Validate pipeline name availability | `GET /pipelines/validate` | | | Create a pipeline schema | `POST /pipeline-schemas` | | | Validate pipeline version name availability | `GET /pipelines/{pipelineId}/versions/validate` | | | Manage pipeline version | `PUT /pipelines/{pipelineId}/versions/{versionId}/manage` | | | Edit pipeline version configuration | `POST /pipelines/{pipelineId}/versions/{versionId}` | | **pipeline:delete** | Delete a pipeline | `DELETE /pipelines/{pipelineId}` | | **pipeline_label:write** | Apply resource labels when launching a pipeline run | Sub-operation on `POST /workflow/launch` | | | Add labels to pipelines | `POST /pipelines/labels/add` | | | Apply resource labels when adding a pipeline | Sub-operation on `POST /pipelines` | | | Apply resource labels when editing a pipeline (default version) | Sub-operation on `PUT /pipelines/{pipelineId}` | | | Apply resource labels when editing a pipeline version | Sub-operation on `POST /pipelines/{pipelineId}/versions/{versionId}` | | | Remove labels from pipelines | `POST /pipelines/labels/remove` | | | Apply label sets to pipelines | `POST /pipelines/labels/apply` | | **workflow:read** | View run details | `GET /workflow/{workflowId}` | | | View run progress | `GET /workflow/{workflowId}/progress` | | | List tasks in a run | `GET /workflow/{workflowId}/tasks` | | | View individual task details | `GET /workflow/{workflowId}/task/{taskId}` | | | View run metrics | `GET /workflow/{workflowId}/metrics` | | | List all runs in workspace | `GET /workflow` | | | View run launch configuration | `GET /workflow/{workflowId}/launch` | | | View run execution logs | `GET /workflow/{workflowId}/log` | | | View task-specific logs | `GET /workflow/{workflowId}/log/{taskId}` | | | Download run logs | `GET /workflow/{workflowId}/download` | | | Download run content in a workspace | _(Used by Platform)_ | | | Download task logs | `GET /workflow/{workflowId}/download/{taskId}` | | | View run reports | _(Used by Platform)_ | | | Download run report | _(Used by Platform)_ | | | Fetch workflow optimization | _(Used by Platform)_ | | | Check optimized workflow list | _(Used by Platform)_ | | **workflow:execute** | Launch a pipeline run | `POST /workflow/launch` | | | Cancel a running pipeline | `POST /workflow/{workflowId}/cancel` | | | Launch a pipeline run | _(Used by Platform)_ | | **workflow:write** | Create execution trace | `POST /trace/create` | | | Update trace heartbeat | `PUT /trace/{workflowId}/heartbeat` | | | Mark trace begin | `PUT /trace/{workflowId}/begin` | | | Mark trace complete | `PUT /trace/{workflowId}/complete` | | | Update trace progress | `PUT /trace/{workflowId}/progress` | | **workflow:delete** | Delete a single run | `DELETE /workflow/{workflowId}` | | | Delete multiple runs | `POST /workflow/delete` | | **workflow_label:write** | Add labels to runs | `POST /workflow/labels/add` | | | Remove labels from runs | `POST /workflow/labels/remove` | | | Apply label sets to runs | `POST /workflow/labels/apply` | | **workflow_quick:execute** | Launch quick pipeline | Sub-operation on `POST /workflow/launch` | | | Launch quick pipeline | _(Used by Platform)_ | | | GA4GH: create a run | `POST /ga4gh/wes/v1/runs` | | **workflow_star:read** | Check if run is starred (favorited) | `GET /workflow/{workflowId}/star` | | **workflow_star:write** | Star (favorite) a run | `POST /workflow/{workflowId}/star` | | **workflow_star:delete** | Unstar (unfavorite) a run | `DELETE /workflow/{workflowId}/star` | #### Settings | Permission | Description | API endpoint | |------------|-------------|--------------| | **label:read** | List all workspace labels | `GET /labels` | | **label:write** | Create a new label | `POST /labels` | | | Edit an existing label | `PUT /labels/{labelId}` | | **label:delete** | Delete a label | `DELETE /labels/{labelId}` | | **workspace:read** | View workspace details | `GET /orgs/{orgId}/workspaces/{workspaceId}` | | | List workspace participants | `GET /orgs/{orgId}/workspaces/{workspaceId}/participants` | | **workspace:write** | Edit workspace settings | `PUT /orgs/{orgId}/workspaces/{workspaceId}` | | | Add a workspace participant | `PUT /orgs/{orgId}/workspaces/{workspaceId}/participants/add` | | | Find workspace participant candidates | _(Used by Platform)_ | | | Change participant role | `PUT /orgs/{orgId}/workspaces/{workspaceId}/participants/{participantId}/role` | | | Remove a workspace participant (user or team) | `DELETE /orgs/{orgId}/workspaces/{workspaceId}/participants/{participantId}` | | | Remove a workspace user (member or collaborator) | `DELETE /orgs/{orgId}/workspaces/{workspaceId}/users/{userId}` | | **workspace:delete** | Delete the workspace | `DELETE /orgs/{orgId}/workspaces/{workspaceId}` | | **workspace:admin** | Change participant role to/from Owner | Sub-operation on `PUT /orgs/{orgId}/workspaces/{workspaceId}/participants/{participantId}/role` | | | Remove a workspace Owner by participantId | Sub-operation on `DELETE /orgs/{orgId}/workspaces/{workspaceId}/participants/{participantId}` | | | Remove a workspace Owner by userId | Sub-operation on `DELETE /orgs/{orgId}/workspaces/{workspaceId}/users/{userId}` | | **workspace_self:delete** | Leave workspace (remove self as participant) | `DELETE /orgs/{orgId}/workspaces/{workspaceId}/participants` | | **workspace_studio:read** | View studio settings for workspace | `GET /orgs/{orgId}/workspaces/{workspaceId}/settings/studios` | | **workspace_studio:write** | Edit studio settings for workspace | `PUT /orgs/{orgId}/workspaces/{workspaceId}/settings/studios` | #### Studios | Permission | Description | API endpoint | |------------|-------------|--------------| | **studio:read** | View studio session details | `GET /studios/{sessionId}` | | | View studio repository details | _(Used by Platform)_ | | | List all studios in workspace | `GET /studios` | | | List available studio templates | `GET /studios/templates` | | | List checkpoints for a studio | `GET /studios/{sessionId}/checkpoints` | | | View checkpoint details | `GET /studios/{sessionId}/checkpoints/{checkpointId}` | | **studio:execute** | List mounted data-links for studios | `GET /studios/data-links` | | | Start a studio session | `PUT /studios/{sessionId}/start` | | | Stop a studio session | `PUT /studios/{sessionId}/stop` | | **studio:write** | Create a new studio | `POST /studios` | | | Edit checkpoint name | `PUT /studios/{sessionId}/checkpoints/{checkpointId}` | | | Update a studio | `PUT /studios/{sessionId}` | | | Validate studio name availability | `GET /studios/validate` | | **studio:delete** | Delete a studio | `DELETE /studios/{sessionId}` | | **studio:admin** | Delete another user's private studio | Sub-operation on `DELETE /studios/{sessionId}` | | | Start another user's private studio | Sub-operation on `PUT /studios/{sessionId}/start` | | | Update another user's private studio | Sub-operation on `PUT /studios/{sessionId}` | | | Stop another user's private studio | Sub-operation on `PUT /studios/{sessionId}/stop` | | | Extend another user's private studio session lifespan (iframe) | _(Used by Platform)_ | | | Extend another user's private studio session lifespan | Sub-operation on `POST /studios/{sessionId}/lifespan` | | | Administer another user's private studio | _(Used by Platform)_ | | **studio_label:write** | Apply resource labels when starting a studio | Sub-operation on `PUT /studios/{sessionId}/start` | | | Apply resource labels when updating a studio | Sub-operation on `PUT /studios/{sessionId}` | | **studio_session:read** | Open a studio | _(Used by Platform)_ | | **studio_session:execute** | Extend studio session lifespan (iframe) | _(Used by Platform)_ | | | Extend studio session lifespan | `POST /studios/{sessionId}/lifespan` | --- ## Organizations Organizations are the top-level structure and contain workspaces, members, and teams. Before you start using Platform, consider the projects, research areas, and resources you'd like to build out and who'll be using them so that you can scale up easily. You can create multiple organizations, each of which can contain multiple workspaces with shared users and resources. This means you can customize and organize the use of resources while maintaining an access control layer for users associated with a workspace. A workspace can be public (shared across the organization) or private (accessible only to the user who created it) Within an organization, you have members - users that you add to your organization who will access and use Platform - and they're organized into teams. Teams provide a way to group members such as `workflow-developers` or `analysts`, and apply access control for all users within that team. Lastly, you can also add external users (collaborators) to shared workspaces within your organization. :::note Organizations consist of members, while workspaces consist of participants. ::: ### Create an organization When you create an organization, you become the organization owner. Organization owners can add or remove members from an organization or workspace, and can allocate specific access roles within workspaces. You can also add external collaborators to an organization. 1. From the user menu, select [Your organizations](https://cloud.seqera.io/orgs), then **Add Organization**. 2. Enter a **Name** and **Full name** for your organization. 3. Enter any other optional fields as needed: **Description**, **Location**, **Website URL**, and **Logo**. 4. Select **Add**. You can invite or add additional members to the workspace from the workspace **Settings** page. ### Organization settings Organization owners can view, edit, and delete organizations in the **Organization settings** screen. Select your organization from the drop-down, then select **Settings** in the sidebar. Cloud Pro organizations can also configure and manage [single sign-on (SSO)](../sso/single-sign-on) from the organization settings page. #### Edit or delete an organization Select **Edit** in the **Edit organization** row to update the organization name, full name, description, location, website URL, and logo. Select **Update** to save. To delete your organization, select **Delete** in the **Delete organization** card. ## Members You can view the list of all **Members** from the organization's landing page. Seqera provides access control for members of an organization by classifying them either as an **Owner** or a **Member**. Each organization can have multiple owners and members. ### Add a member To add a new member to an organization: 1. Go to the **Members** tab in the sidebar of the organization landing page. 2. Select **Add member**. 3. Enter the name or email address of the user you'd like to add to the organization. An email invitation will be sent to the user. Once they accept the invitation, they can switch to the organization (or organization workspace) from the workspace drop-down. :::note For information about what happens when a user deletes their account, see [user deletion](../data-privacy/overview#user-deletion). ::: ## Teams **Teams** allow organization **owners** to group members and collaborators together into a single unit and to manage them as a whole. ### Create a new team To create a new team: 1. Go to the **Teams** tab in the sidebar of the organization landing page. 2. Select **Add Team**. 3. Enter the **Name** of team. 4. Optionally, add the **Description** and the team's **Avatar**. 5. Select **Add**. To start adding members to your team, select **Edit > Members of team > Add member** and enter the name or email address of the organization members or collaborators. ## Collaborators **Collaborators** are users who are invited to an organization's workspace, but are not members of that organization. As a result, their access is limited to that organization's workspace. You can view the list of all organization **Collaborators** from the organization's landing page. New collaborators to an organization's workspace can be added as **Participants** from the workspace page. See [User roles](./roles) to learn more about participant access levels. :::note **Collaborators** can only be added from a workspace. For more information, see [workspace management](./workspace-management#create-a-new-workspace). ::: ## Organization resource usage tracking Select **Usage overview** next to the organization and workspace selector drop-down to view a window with the following usage details: - **Run history**: The total number of pipeline runs. - **Concurrent runs**: Total simultaneous pipeline runs. - **Running Studio sessions**: Number of concurrent running Studio sessions. - **Users**: Total users per organization. Organization resource usage information is also displayed on the organization's **Settings** tab in the sidebar of the organization landing page. Select **Contact us to upgrade** if you need to increase your Platform usage limits for your organization. :::info Usage limits differ per organization and [subscription type](https://seqera.io/pricing/). [Contact us](https://seqera.io/contact-us/) to discuss your needs. ::: ### Credits [Seqera Compute](../compute-envs/seqera-compute) environments consume credits when running pipelines or Studio sessions. Credits are consumed for CPU time, memory and storage usage, and network costs. One Seqera Compute credit is equivalent to $1 (USD), and resources are charged at the following rates: - CPU time: 1 CPU/Hr = 0.1 credits - Memory: 1 GiB/Hr = 0.025 credits - Storage: 1 GB = 0.025 credits per month :::note Storage and network costs vary per region and are charged at standard AWS rates. Data ingress and egress across regions incur additional costs. ::: Your available credit balance depends on the credits purchased and limits applied to your Seqera license. The **Credits** view contains the current credit balance available to the organization, and the total credits spent in the organization's workspaces. Select **Contact us to upgrade** to request additional credits for your organization. --- ## Personal profile and default settings These settings control how you're identified in Seqera Platform, which workspace you land in after sign-in, and your notification preferences. ## Profile fields | Field | Required | Editable | Description | | --- | --- | --- | --- | | **Email** | Yes | No | Email address used to sign in. Locked after account creation. | | **User name** | Yes | Yes | Auto-generated from email. Lowercase alphanumeric and dash characters only. | | **First name** | No | Yes | First name. | | **Last name** | No | Yes | Surname or family name. | | **Avatar** | No | Yes | Profile picture. Auto-generated if not provided. | | **Organization** | No | Yes | Name of your company or organization. | | **Description** | No | Yes | Free-text information about yourself, shown to other Seqera Platform users. | ## Default settings | Setting | Default | Description | | --- | --- | --- | | **Send notification email on workflow completion** | Off | Receive an email when a pipeline run completes. | | **Default workspace** | None | Organization and workspace you land in after sign-in. If not set, you land in your most recently accessed workspace. | ## Delete your account :::warning This action cannot be undone. ::: Delete your account from Seqera Platform. --- ## User roles Organization owners can assign role-based access levels to individual **participants** and **teams** in an organization workspace. :::tip You can group **members** and **collaborators** into **teams** and apply a role to that team. Members and collaborators inherit the access role of the team. ::: :::note Cloud Pro organizations with active [single sign-on (SSO)](../sso/single-sign-on) can't add external workspace collaborators. External users who need workspace access must be invited as organization members and authenticate through the configured IdP. ::: ### Organization user roles - **Owner**: After an organization is created, the user who created the organization is the default owner of that organization. Additional users can be assigned as organization owners. Owners have full read/write access to modify members, teams, collaborators, and settings within an organization. Organization owners always have full owner access to organization workspaces, regardless of their participant roles at the workspace level. - **Member**: A member is a user who is internal to the organization. Members have an organization role and can operate in one or more organization workspaces. In each workspace, members have a participant role that defines the permissions granted to them within that workspace. ### Role inheritance If a user is concurrently assigned to a workspace as both a named **participant** and member of a **team**, Seqera assigns the higher of the two privilege sets. Example: - If the participant role is Launch and the team role is Admin, the user will have Admin rights. - If the participant role is Admin and the team role is Launch, the user will have Admin rights. - If the participant role is Launch and the team role is Launch, the user will have Launch rights. As a best practice, use teams as the primary vehicle for assigning rights within a workspace and only add named participants when one-off privilege escalations are necessary. ## Workspace participant roles - **Owner**: The user who created the workspace is its first owner. Owners have full administrative privileges over a workspace and its resources, including permission to delete the workspace. Regular participants can also be promoted to workspace owners. - **Admin**: Workspace admins share most of the administrative privileges of workspace owners, but admins cannot delete a workspace. - **Maintain**: Workspace maintainers can use and manage all workspace resources, but cannot create workspace credentials or compute environments. - **Launch**: Launch users can use existing workspace resources and launch pipelines, but they cannot modify workspace resources. - **Connect**: Connect users can connect to running workspace Studios. - **View**: View users can view workspace resources, but cannot modify or execute them. :::note Workspace participants with any role can leave the workspace, i.e., remove themselves as a workspace participant. However, only workspace owners and admins can add or remove workspace participants other than themselves. ::: ### Role permissions The following table shows which operations are available to the default workspace participant roles: | Permission | Owner | Admin | Maintain | Launch | Connect | Viewer | |--------------------------------|-------|-------|----------|--------|---------|--------| | **action:read** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **action:execute** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **action:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **action:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **action_label:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **compute_environment:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **compute_environment:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **compute_environment:delete** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **container:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **credentials:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **credentials:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **credentials:delete** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **credentials_encrypted:read** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **data_link:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **data_link:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **data_link:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **data_link:admin** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **data_link_object:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **data_link_object:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **data_link_object:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **dataset:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **dataset:write** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **dataset:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **dataset:admin** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **dataset_label:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **label:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **label:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **label:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **launch:read** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **lineage:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **pipeline:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **pipeline:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **pipeline:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **pipeline_label:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **pipeline_secrets:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **pipeline_secrets:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **pipeline_secrets:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **platform:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **studio:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **studio:execute** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **studio:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **studio:delete** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **studio:admin** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **studio_label:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **studio_session:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | | **studio_session:execute** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | | **workflow:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workflow:execute** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **workflow:write** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **workflow:delete** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **workflow_label:write** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **workflow_quick:execute** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | **workflow_star:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workflow_star:write** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workflow_star:delete** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workspace:read** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workspace:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **workspace:delete** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | **workspace:admin** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | **workspace_lineage:read** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **workspace_lineage:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | **workspace_self:delete** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **workspace_studio:read** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **workspace_studio:write** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | --- ## Teams Use **teams** to group organization members and collaborators and manage them together. Apply a workspace role to a team, and every member inherits that access. See [User roles](./roles) for the available roles. :::note If your organization has [single sign-on (SSO)](../sso/single-sign-on) with IdP delegation enabled, you can delegate a team to an **IdP group** so your identity provider controls its membership. See [Delegate a team to an IdP group](#delegate-a-team-to-an-idp-group). ::: ## Create a team To create a new team: 1. Go to the **Teams** tab in the sidebar of the organization landing page. 2. Select **Add Team**. 3. Enter the **Name** of the team. 4. Optionally, add the **Description** and the team's **Avatar**. 5. Select **Add**. To add members to the team, select **Edit**, then **Members of team**, then **Add member**. Enter the name or email address of an organization member or collaborator. ## Edit a team To edit an existing team: 1. Open the **Teams** tab and select the team you want to edit. 2. Select **Edit**. 3. Update the **Name**, **Description**, **Avatar**, or membership. 4. Select **Update** to save. The same surface is used to delete a team. The **Delete** action is disabled for delegated teams. Clear the **IdP Group** field first. ## Delegate a team to an IdP group Organizations with an active SSO connection can delegate team membership to an identity provider (IdP) group. After you delegate a team, the IdP becomes the sole authority for who belongs. Seqera evaluates each user's IdP claims at every login and adjusts membership to match. For how delegation works, see [IdP delegation overview](../sso/idp-delegation/overview). :::info[**Prerequisites**]{#prerequisites} You need the following: - An active SSO connection on your organization. See [Single sign-on (SSO)](../sso/single-sign-on). - A populated IdP group catalog. See [Manage your IdP group catalog](../sso/idp-delegation/group-catalog/overview). - An IdP that emits the `groups` claim. See [IdP claim mapping](../sso/idp-delegation/claim-mapping). - Organization owner access to your Seqera organization. ::: ### Delegate a team To delegate a team: 1. Open your organization, then select **Settings**. 2. Open the **Teams** tab and select the team you want to delegate, or create a new team. 3. Set the **IdP Group** field to a group from the catalog. 4. Select **Update** to save. The same IdP group can only be assigned to a single team, and each team can reference exactly one IdP group. :::caution After you delegate a team, your IdP is the sole authority for its membership. Members removed from the IdP group, or whose token stops carrying the `groups` claim, lose their delegated team memberships at their next login. See [What happens at login](#what-happens-at-login). ::: ### What changes when a team is delegated After you delegate a team: - Membership becomes immutable in the Platform UI. The **Add member** and **Remove member** controls are hidden. - The member list displays a banner indicating that your identity provider manages the team's membership. - The team can't be deleted. To delete a delegated team, clear the **IdP Group** field first. - The team's name, description, avatar, and **IdP Group** value remain editable. - Existing manual workspace and role assignments on the team are preserved. - The team is labeled **Managed in IdP** in the teams list. ### What happens at login Cloud Pro tokens carry an `org_id` claim that scopes evaluation to a single organization. On every SSO login, Seqera evaluates each delegated team against the user's `groups` claim and updates membership accordingly: - **Match found**: The user is added to the team if they aren't already a member. - **No match and the user was previously a delegation-driven member**: The user is removed from the team. - **No match and the user was never a delegation-driven member**: No change. - **Claim absent or empty**: All of the user's delegated team memberships in the organization are revoked. Major IdPs, including Okta and Entra ID, omit the `groups` claim entirely when a user belongs to no groups. An absent claim is treated the same as an empty one. - **Claim malformed** (not a list, or containing non-string values): No membership changes are applied. Existing memberships are preserved as a safeguard against IdP or claim-mapping errors. Users added manually to a team with no **IdP Group** value keep their membership regardless of their IdP claims. ### Stop delegating a team To convert a delegated team back to manual management: 1. Open the team and clear the **IdP Group** field. 2. Select **Update** to save. Existing members are kept. The **Add member** and **Remove member** controls become available again, and the team can be deleted as normal. ## Workspace and role assignment Delegation controls who belongs to the team. It doesn't assign the team to workspaces or grant roles. Your IdP owns team membership, and your organization owns workspace and role assignment. After delegation: - Assign the team to a workspace using the workspace **Participants** page. - Set the team's workspace role separately. See [User roles](./roles). --- ## Workspaces Each user has a unique **user workspace** to manage resources such as pipelines, compute environments, and credentials. You can also create multiple workspaces within an organization context and associate each of these workspaces with dedicated teams of users, while providing fine-grained access control for each of the teams. **Organization workspaces** extend the functionality of user workspaces by adding the ability to fine-tune access levels for specific members, collaborators, or teams. This is achieved by managing **participants** in the organization workspaces. :::note Organizations consist of members, while workspaces consist of participants. A workspace participant may be a member of the workspace organization or a collaborator within that workspace only. Collaborators count toward the total number of workspace participants. See [Usage limits](../limits/overview). ::: ## Create a new workspace Organization owners and admins can create a new workspace within an organization: 1. Go to the **Workspaces** tab of the organization page. 2. Select **Add Workspace**. 3. Enter the **Name** and **Full name** for the workspace. 4. Optionally, add a **Description** for the workspace. 5. Under **Visibility**, select either **Private** or **Shared**. Private visibility means that workspace pipelines are only accessible to workspace participants. 6. Select **Add**. :::tip As a workspace owner, you can modify optional workspace fields after workspace creation. You can either select **Edit** on an organization's workspaces list or the **Settings** tab within the workspace page. ::: Apart from the **Participants** tab, the _organization_ workspace is similar to the _user_ workspace. As such, the relation to [runs](../launch/launchpad), [actions](../pipeline-actions/overview), [compute environments](../compute-envs/overview), and [credentials](../credentials/overview) is the same. ## Workspace settings Select the **Settings** tab within a workspace to manage credits, Studios settings, workspace labels, lineage storage and defaults, and edit or delete the workspace. ### Credits [Seqera Compute](../compute-envs/seqera-compute) environments consume credits when running pipelines or Studio sessions. Credits are consumed for CPU time, memory and storage usage, and network costs. One Seqera Compute credit is equivalent to $1 (USD), and resources are charged at the following rates: - CPU time: 1 CPU/Hr = 0.1 credits - Memory: 1 GiB/Hr = 0.025 credits - Storage: 1 GB = 0.025 credits per month :::note Storage and network costs vary per region, charged at standard AWS rates. Data ingress and egress across regions incur additional costs. ::: Your available credit balance depends on the credits purchased and limits applied to your Seqera license. The **Credits** view contains the current credit balance available to the organization, and the credits spent in the workspace. Select **Contact us to upgrade** to purchase additional credits for your organization. ### Studios - **Collaboration mode**: Limit which members can connect to a running Studio in the workspace. Toggle between **Collaborative** (any member with the right permissions can connect) and **Private** (only the creator can connect). Default is **Collaborative** mode. - **Session lifespan**: Set a predefined lifespan (between 1 and 120 hours), after which all Studio sessions in the workspace are automatically stopped. To keep all workspace Studios running indefinitely, select **Always keep the session running**. Default is a session lifespan of **8 hours**. - **Container repository**: Define the target container repository where custom Studio images built with Wave will be pushed. The workspace must have a credential with read and write permissions to the target container registry. Default for Seqera Cloud is the [community-wave](https://seqera.io/containers) registry. - **Container naming strategy**: Define your container registry naming strategy. Default for Seqera Cloud is **tagPrefix**. - **tagPrefix**: Differentiate application versions within the same repository (e.g., `registry/image:prefix-version`). This strategy is recommended for organizing specific image types (`dev`, `staging`, `prod`) and typically results in fewer repositories with more tags. - **imageSuffix**: Group different build types across repositories (e.g., `registry/image-suffix:version`). This strategy is recommended for managing permissions or different build environments (`front-end` vs. `back-end`, or `API` vs. `GUI`) and typically results in higher repository counts (i.e., one repository per environment/variant). :::note Studios sessions created in shared workspaces are not shared across all the workspaces in an organization. ::: ### Labels Select **Manage** to open the workspace [labels and resource labels](../labels/overview). ### Lineage :::note Data lineage is currently in public preview. It requires Nextflow 25.04 or later, AWS S3 object storage, and Amazon Simple Queue Service (SQS). For best results, use Nextflow 26.04 or higher. ::: Configure where Nextflow lineage data are stored and whether lineage tracking is on by default for every run launched in the workspace. :::tip For compliance-driven teams (regulated industries, audit-tracked work), set **Enable lineage by default** to automatically capture provenance for every pipeline run. Lineage records persist for the lifetime of the configured bucket. Coordinate with your team on retention policies. ::: Select **Manage** and then choose to enable lineage by default for all pipeline runs in the workspace. Configure the lineage settings manually or automatically. | Field | Description | |-------|-------------| | **Credentials** | The workspace credentials Platform uses to create and access the lineage storage bucket and SQS queue. The credentials must include permission to create buckets in the chosen region (or to access an existing bucket if **Bucket name** is specified), activate object notifications on the bucket, and manage the SQS queue. See [Credentials](#credentials). | | **Region** | Cloud region where the lineage storage bucket is created (for example, `us-east-1`, `eu-west-1`). | If configuring **manually**, two additional settings are required: | Field | Description | |-------|-------------| | **Bucket name** | Object storage bucket where lineage records are stored. | | **SQS Queue ARN** | ARN of the SQS queue. This is useful if your Platform deployment requires cross-account access. | If configuring **automatically**, Platform generates the object storage bucket and SQS queue. | Field | Auto-generated name pattern | |-------|-----------------------------| | **Bucket name** | `seqera-lineage-` | | **SQS Queue ARN** | `seqera-lineage--notifications` | :::note Automated configuration uses the **configured workspace credentials** through the same model as [Data Explorer](../data/data-explorer). ::: When lineage is enabled: - The [Run details](../monitoring/run-details) page surfaces lineage IDs and labels on the **Run Info**, **Tasks**, **Inputs**, and **Outputs** tabs. - [Data Explorer](../data/data-explorer) object previews show the lineage ID and labels for files produced by lineage-enabled runs. The pipeline launch form toggle's default state is controlled by **Enable lineage by default**. Maintain role and higher users can override default behavior for an individual run via the launch form toggle. See [Getting started with data lineage](https://docs.seqera.io/nextflow/tutorials/data-lineage) for the underlying Nextflow lineage data model and example JSON payloads. #### Credentials The credentials required for lineage are indicated below in an example AWS policy. ``` { "Version": "2012-10-17", "Statement": [ { /// ---- LINEAGE SPECIFIC "Sid": "SQSQueueActions", "Effect": "Allow", "Action": [ "sqs:CreateQueue", "sqs:GetQueueAttributes", "sqs:SetQueueAttributes", "sqs:ReceiveMessage", "sqs:DeleteMessage" ], "Resource": "arn:aws:sqs:*:*:seqera-lineage-*" }, /// ---- { "Sid": "S3BucketActions", "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:CreateBucket", /// LINEAGE SPECIFIC "s3:PutBucketNotification", "s3:GetBucketNotification" /// ---- ], "Resource": "arn:aws:s3:::seqera-lineage-*" }, { "Sid": "S3ObjectActions", "Effect": "Allow", "Action": "s3:*Object", "Resource": "arn:aws:s3:::seqera-lineage-*/*" }, { "Sid": "S3ObjectTagging", "Effect": "Allow", "Action": [ "s3:PutObjectTagging", "s3:GetObjectTagging" ], "Resource": "arn:aws:s3:::seqera-lineage-*/*" } ] } ``` ### Edit or delete a workspace :::note Workspace **owners** can edit their workspace name from the workspace **Settings** tab. ::: - Select **Edit workspace** to update the workspace name, full name, description, and sharing. Select **Update** to save changes. - Select **Delete workspace** to delete the workspace and its associated resources. This action cannot be reversed. `` ## Add a new participant A new workspace participant can be an existing organization member, team, or collaborator. To add a new participant to a workspace: 1. Go to the **Participants** tab in the workspace menu. 2. Select **Add participant**. 3. Enter the **Name** of the new participant. 4. Optionally, update the participant **role**. ## Workspace run monitoring To allow users executing pipelines from the command line to share their runs with a given workspace, see [deployment options](../getting-started/deployment-options#nextflow--with-tower). Seqera Platform introduces the concept of shared workspaces as a solution for synchronization and resource sharing within an organization. A shared workspace enables the creation of pipelines in a centralized location, making them accessible to all members of an organization. The benefits of using a shared workspace within an organization include: - **Define once and share everywhere**: Set up shared resources once and automatically share them across the organization. - **Centralize the management of key resources**: Organization administrators can ensure the correct pipeline configuration is used in all areas of an organization without the need to replicate pipelines across multiple workspaces. - **Immediate update adoption**: Updated parameters for a shared pipeline become immediately available across the entire organization, reducing the risk of pipeline discrepancies. - **Computational resource provision**: Pipelines in shared workflows can be shared along with the required computational resources. This eliminates the need to duplicate resource setup in individual workspaces across the organization. Shared workspaces centralize and simplify resource sharing within an organization. ## Create a shared workspace Creating a shared workspace is similar to the creation of a private workspace, with the exception of the **Visibility** option, which must be set to **Shared**. ## Create a shared pipeline When you create a pipeline in a shared workspace, associating it with a [compute environment](../compute-envs/overview) is optional. If a compute environment from the shared workspace is associated with the pipeline, it will be available to users in other organization workspaces to launch the shared pipeline with the associated compute environment by default. ## Use shared pipelines from a private workspace Once a pipeline is set up in a shared workspace and associated with a compute environment in that workspace, any user can launch the pipeline from an organization workspace using the shared workspace's compute environment. This eliminates the need for users to replicate shared compute environments in their private workspaces. :::note The shared compute environment will not be available to launch other pipelines limited to that specific private workspace. ::: If a pipeline from a shared workspace is shared **without** an associated compute environment, users can run it from other organization workspaces. By default, the **primary** compute environment of the launching workspace will be selected. ## Make shared pipelines visible in a private workspace :::note Pipelines from _all_ shared workspaces are visible when the visibility is set to **Shared workspaces**. ::: To view pipelines from shared workspaces, go to the [Launchpad](../launch/launchpad) and set the **Filter > Pipelines from** option to **This and shared workspaces**. --- ## Pipeline actions Actions enable event-based pipeline execution, such as triggering a pipeline launch with a GitHub webhook whenever the pipeline repository is updated. Seqera Platform currently offers support for native **GitHub webhooks** and a general **Tower webhook** that can be invoked programmatically. ### GitHub webhooks A **GitHub webhook** listens for any changes made in the pipeline repository. When a change occurs it triggers the launch of the pipeline automatically. :::note You must sign in to Seqera using GitHub authentication to create a GitHub webhook action. If you're signed in via Google the **Add** button in step 6 below will be inactive. ::: To create a new action, select the **Actions** tab and select **Add Action**. 1. Enter a **Name** for your action. 1. Select **GitHub webhook** as the **Event source**. 1. Select the **Compute environment** where the pipeline will be executed. 1. Select the **Pipeline to launch** and (optionally) the **Revision**. 1. Enter the **Work directory**, the **Config profiles**, and the **Pipeline parameters**. 1. Select **Add**. The pipeline action is now set up. When a new commit occurs for the selected repository and revision, an event is triggered and the pipeline is launched. Workspace maintainers can edit pipeline actions. Select **Edit** from the options menu to the right of the action on the **Actions** list to load the action details. Select **Update** to save the updated pipeline action. :::note Workspace maintainers can edit the names of existing pipeline actions from the **Edit Action** page. ::: ### Tower launch hooks A **Tower launch hook** creates a custom endpoint URL which can be used to trigger the execution of your pipeline programmatically from a script or web service. To create a new action, select the **Actions** tab and select **Add Action**. 1. Enter a **Name** for your action. 1. Select **Tower launch hook** as the event source. 1. Select the **Compute environment** to execute your pipeline. 1. Enter the **Pipeline to launch** and (optionally) the **Revision**. 1. Enter the **Work directory**, the **Config profiles**, and the **Pipeline parameters**. 1. Select **Add**. The pipeline action is now set up and the new endpoint can be used to launch the corresponding pipeline programmatically. When you create a **Tower launch hook**, you also create an **access token** for launching pipelines. Access tokens can be managed on the [tokens page](https://cloud.seqera.io/tokens), which is also accessible from the user menu. --- ## Pipeline optimization(Pipeline-optimization) Pipeline optimization takes the resource usage information from previous workflow runs to optimize subsequent runs. When a run completes successfully, an _optimized profile_ is created. This profile consists of Nextflow configuration settings for each process and each resource directive (where applicable): `cpus`, `memory`, and `time`. The optimized setting for a given process and resource directive is based on the maximum use of that resource across all tasks in that process. :::caution Due to the variability of production pipeline data inputs, optimization results may vary per run. The optimization profile can be updated or removed from your pipeline if you experience unexpected results. Contact [support](https://support.seqera.io) for further assistance. ::: ## Optimize a pipeline On the **Launchpad**, each pipeline that can be optimized shows a lightbulb icon. Any pipeline with at least one successful run can be optimized. 1. Select the lightbulb icon to open the **Customize optimization profile** menu. 2. Under the **Optimization profile** tab, select a previous run from the drop-down. The list contains all successful runs. 3. Select which **Targets** to optimize. 4. Enable **Retry with dynamic resources** for failed tasks to be retried with increased resources. This option is useful if an optimized setting is too low and causes a task to fail. 5. Select the **Optimized configuration** tab to preview your configuration. 6. Select **Save** to save the optimized configuration and enable it for the pipeline. All subsequent launches of the pipeline will use the optimized configuration. You can also toggle the optimized profile from the pipeline detail page. ### Verify the optimized configuration You can verify the optimized configuration of a given run by inspecting the resource usage plots for that run and these fields in the run's task table: - CPU usage: `pcpu` - Memory usage: `peakRss` - Runtime: `start` and `complete` ### Override the optimized configuration While the optimized configuration is applied after the base configuration of the pipeline, it can be overridden by the **Nextflow config file** text box. Ensure there are no conflicting settings in this text box, unless you explicitly want to override some optimization settings. ### Handle large variations in resource usage Each optimized profile is calibrated to a specific run, so it can only be used safely for "similar" runs. Whether a new run is "similar" is subjective, but in general, an optimized profile should only be used for runs that use the same [**compute environment**](../compute-envs/overview) and have similar task-level resource requirements. However, it's common for a pipeline to process input files that vary widely in size. In this case, the task-level resource requirements may vary widely for a given process, and the optimized profile may not be accurate or efficient. The best way to handle this variation is to create multiple optimized profiles for specific ranges of input sizes. Here is an example strategy: 1. Separate your input files into "bins" based on their size, e.g., _small_, _medium_, and _large_. Duplicate your pipeline in the **Launchpad** for each bin. 2. For each bin, run the pipeline with a few representative samples from that bin. When the run completes, Seqera automatically creates an optimized profile for it. 3. Configure and enable the optimized profile for each pipeline. You now have multiple optimized profiles to handle a variety of input sizes. Although this example uses three bins, you can use as many or as few bins as you need to handle the variation of your input data. --- ## Pipeline schema Pipeline schema files describe the structure and validation constraints of your workflow parameters. They are used to validate parameters before launch to prevent software or pipelines from failing in unexpected ways at runtime. You can populate the parameters in the pipeline by uploading a YAML or JSON file, or in the Seqera Platform interface. The platform uses your pipeline schema to build a bespoke launchpad parameters form. See [nf-core/rnaseq](https://github.com/nf-core/rnaseq/blob/e049f51f0214b2aef7624b9dd496a404a7c34d14/nextflow_schema.json) as an example of the pipeline parameters that can be represented by a JSON schema file. ### Define pipeline schema When adding or editing a pipeline, you can select one of three schema options to control parameter validation and the launch form: 1. **Repository default**: Use the default schema provided by the Pipeline git repository. 2. **Repository path**: Use a schema at a specific path in the repository. 3. **Seqera Platform schema**: Use a Nextflow JSON schema stored in Seqera Platform (overrides repository). The selected schema controls which pipeline parameters are exposed in the launch form. This allows you to restrict the parameters visible to launch users, simplifying the launch experience and preventing modification of parameters that should remain fixed. #### Seqera Platform schema Users with [Maintain or higher](../orgs-and-teams/roles.md) permissions can upload a custom Nextflow JSON schema directly to Seqera Platform. When you upload a custom schema: - The schema content is validated to ensure it's a valid JSON schema. - The Platform schema controls which parameters appear in the pipeline launch form. - The Platform schema is applied to all launches using that pipeline version. To add or update a Seqera Platform schema: 1. Navigate to **Add pipeline** or select **Edit** for an existing pipeline. 2. Select **Seqera Platform schema** from the schema options. 3. In the **Seqera Platform schema** field, paste your custom Nextflow schema JSON. 4. The schema is validated automatically as you enter it. 5. Select **Add** or **Save** to create a new draft version with the Platform schema. :::note The schema `id` field must be unique. If you're pasting pipeline schema contents from an existing pipeline schema file, update the `id` field to a unique value, or remove it. ::: ### Building pipeline schema files The pipeline schema is based on [json-schema.org](https://json-schema.org/) syntax, with some additional conventions. While you can create your pipeline schema manually, we highly recommend using [nf-core tools](https://nf-co.re/tools#json-schema-graphical-interface), a toolset for developing Nextflow pipelines built by the nf-core community. When you run the `nf-core schema build` command in your pipeline root directory, the tool collects your pipeline parameters and gives you interactive prompts about missing or unexpected parameters. If no existing schema file is found, the tool creates one for you. The `schema build` commands include the option to validate and lint your schema file according to best practice guidelines from the nf-core community. :::note The nf-core community creates the schema builder but it can be used with any Nextflow pipeline. ::: ### Customize pipeline schema When the skeleton pipeline schema file has been built with `nf-core schema build`, the command line tool will prompt you to open a [graphical schema editor](https://nf-co.re/pipeline_schema_builder) on the nf-core website. ![nf-core schema builder interface](./_images/pipeline_schema_overview.png) Leave the command line tool running in the background as it checks the status of your schema on the website. When you select **Finished** on the schema editor page, your changes are saved to the schema file locally. :::note Your pipeline schema contains a `mimetype` field that specifies the accepted file type for input [datasets](../data/datasets). When you launch a pipeline from the [Launchpad](../launch/launchpad), the input field drop-down will only show datasets that match the required file type (either `text/csv` or `text/tsv`). ::: --- ## Overview(Pipelines) Seqera Platform provides version-controlled, access-controlled, reproducible execution of Nextflow pipelines. When you add a pipeline to Seqera, you define: - The pipeline Git repository and [revision](./revision.md) (branch, tag, or commit) - [Compute environment](../compute-envs/overview.md) for execution - Pipeline parameters and [configuration profiles](https://docs.seqera.io/nextflow/config#config-profiles) - (Optional) [Labels](../labels/overview.md), [resource labels](../resource-labels/overview.md), and [secrets](../secrets/overview.md) - (Optional) [Pre-run and post-run](../launch/advanced.md#pre-and-post-run-scripts) bash scripts that execute in your compute environment ### Manage pipelines - [Add pipelines](../getting-started/quickstart-demo/add-pipelines.md) - [Edit pipelines](../launch/launchpad.md#edit-pipelines) - [Launch pipelines](../launch/launchpad.md) ### Key features #### Pipeline revision management Workflow repositories change over time as code is updated. Seqera provides [revision management](./revision.md) features, such as **commit ID pinning** to ensure reproducible execution by locking pipelines to specific Git commits, and **Pull latest** controls to instruct Nextflow to fetch the most recent commit at execution time. --- ## Git revision management Workflow repositories are mutable - branches can be updated, tags can be moved (though rarely), and the "latest" code changes over time. This creates a reproducibility challenge: launching the same pipeline configuration at different times could execute different workflow code. **Commit ID pinning** solves this by tracking the specific Git commit ID alongside the branch or tag revision. When you pin a commit ID, Seqera ensures that exact version of the workflow code is executed for every launch, regardless of upstream repository changes. :::info Commit ID pinning requires a valid pipeline and **Revision** (tag or branch name) to be specified. The **Commit ID** field and pin icon is disabled if the **Revision** field is left empty. ::: The **Pull latest** toggle controls whether Nextflow fetches the most recent HEAD commit of the pipeline revision at execution time. This is equivalent to the `nextflow run -latest` flag. If **Pull latest** is **disabled** in HPC compute environments, the Nextflow cache is used (if available). Cloud compute environments always pull the latest HEAD commit of the revision at execution time, unless a specific commit ID revision is set or pinned. Enabling **Pull latest** unpins any pinned commit ID. ### Pin commit ID versus Pull latest behavior The **Commit ID** and **Pull latest** fields appear on pipeline add, edit, and launch forms. Their interaction and behavior depend on compute environment type: **Cloud compute environments** | Revision | Commit ID | Pull latest | Launch behavior | |----------|-----------|-------------|-------------------| | Branch/tag | Empty (unpinned) - default | OFF - default | Fetches current HEAD commit at execution time (non-deterministic). | | Branch/tag | Pinned | OFF - automatically set when pinned | Uses the pinned commit ID for deterministic execution. | | Branch/tag | Empty (unpinned) | ON | Fetches current HEAD commit at execution time (non-deterministic). Equivalent to `nextflow run -latest`. | | Commit ID | Automatically populated and pinned | OFF - default | Uses the specified commit ID (deterministic by definition). | **HPC compute environments** | Revision | Commit ID | Pull latest | Launch behavior | |----------|-----------|-------------|-------------------| | Branch/tag | Empty (unpinned) - default | OFF - default | Runs locally cached pipeline version. No update or network fetch is performed. | | Branch/tag | Pinned | OFF - automatically set when pinned | Uses the pinned commit ID for deterministic execution. | | Branch/tag | Empty (unpinned) | ON | Fetches and caches current HEAD commit before execution (non-deterministic). Equivalent to `nextflow run -latest`. | | Commit ID | Automatically populated and pinned | OFF - default | Uses the specified commit ID (deterministic by definition). | This relationship ensures commit ID pinning provides deterministic execution across both Cloud and HPC environments. Once pinned, the same commit ID is used for each launch, regardless of compute environment type. :::note If you enter a commit ID in the **Revision** field, the **Commit ID** field, pin icon, and **Pull latest** toggle are disabled. ::: --- ## Pipeline versioning Seqera's pipeline versioning system captures configuration changes as new draft versions of the pipeline, ensuring configuration traceability and execution reproducibility. Users with appropriate permissions can edit and publish draft versions, creating published versions that teams can reference and launch consistently. When you add a new pipeline to Seqera, the first default version of that pipeline is automatically published. New draft versions are automatically generated when you modify the following: - All pipeline schema parameters, unless the `track_changes` schema configuration for a given property is set to `false`. :::info Changes to all pipeline schema parameters trigger a new version by default (`"track_changes": true`). To alter this behavior for specific parameters, add `"track_changes": false` to the parameter definition: ```json "my_parameter": { "type": "string", "description": "Changes to this parameter will not trigger a new pipeline version to be created", "track_changes": false } ``` For nested parameters, `track_changes` is supported at the leaf node level: ```json "nestedParam": { "type": "object", "properties": { "leafParam": { "type": "string", "track_changes": false } } } ``` ::: - Fields in the pipeline **Edit** form, excluding: - **Name** - **Image** - **Description** - **Labels** - **Resource labels** - Pipeline schema selection (see [Define pipeline schema](../pipeline-schema/overview.md#define-pipeline-schema)) Published versions provide a stable reference for team-wide pipeline launches. Users with Maintain or higher permissions can publish a draft version, giving it a name and optionally setting it as the default version. This makes important configurations easy to identify, share, and promote across your team. :::info A pipeline's default version is shown in the Launchpad and automatically selected during launch. ::: Seqera maintains a history of all draft and published versions, providing an audit trail of pipeline evolution. #### Seqera Platform schema Users with Maintain or higher permissions can upload a `nextflow_schema.json` file to Seqera Platform to control which pipeline parameters appear in the launch form. Changes to the Seqera Platform schema trigger a new draft version of the pipeline. For more information, see [Define pipeline schema](../pipeline-schema/overview.md#define-pipeline-schema). #### Manage pipeline versions ![](./_images/pipeline-version-detail.jpg) Select a pipeline from the workspace Launchpad to open the pipeline's details page. From here, users with Maintain or higher permissions can: - **View version history**: See a chronological list of all draft and published versions with creator, date, and hash. - Use the drop-down next to **Show:** to show all versions, or filter by draft or published versions. - **Search** for specific version names (freetext search), or use keywords to search by `versionId:`, `versionName:`, or `versionHash:` ([version hash](#version-hash)). - **Manage draft versions**: - Select **Publish** from the options menu of a draft version to name this version and optionally make it the default version to launch from the Launchpad. :::note Draft versions created from workflow runs can only be published from the pipeline's original workspace. For shared pipelines, the **Publish** action is only available in the workspace where the pipeline was created. ::: - Select **Edit** to open the pipeline edit form and either save a new draft or publish the current draft version. - **Manage published versions**: - Select **Make default** from the options menu of a published version to use this version for every pipeline launch. - Select **Edit** to open the pipeline edit form and either save a new draft or update the current published version. - Select **Unpublish** to turn this version back into a draft. Draft versions are still visible to launch users. Individual draft versions cannot be deleted - the pipeline configuration audit trail is immutable. However, published versions can be unpublished or have their names reassigned to different draft versions. :::note Changes made at launch time in a target workspace cannot be saved. Changes to versions can only be saved and published from the pipeline's original workspace. ::: #### Pipeline optimization [Pipeline optimization](../pipeline-optimization/overview) is available directly from the pipeline details page for the default version. Users with Maintain or higher permissions can: - **Optimize pipeline**: Configure pipeline optimization settings for the default version from the **Default** section or the **Edit pipeline** form. - **Toggle optimization**: Enable or disable optimization for a pipeline that has already been optimized. - **Customize profile**: Modify the optimization profile settings when optimization is enabled. To optimize specific non-default versions, use the **Edit** page for that version. Pipeline optimization settings apply per version and remain configured when you set a different version as the default. #### Version hash Seqera calculates a hash for each draft version based on its version-triggering parameters. This provides: - **Cryptographic verification** that a workflow run's configuration matches its associated pipeline version - **Provenance tracking** for audit and compliance requirements --- ## Seqera Platform Cloud Seqera Platform Cloud is a centralized environment that makes scientific analysis accessible at any scale. Run pipelines, work interactively in managed analysis environments, manage data, and collaborate across teams using your own compute resources and infrastructure. Seqera helps organizations: - **Run pipelines**: Launch, manage, and monitor [Nextflow](https://www.nextflow.io) pipelines on cloud or HPC compute, with a [Launchpad](/platform-cloud/launch/launchpad) interface for non-technical users. - **Analyze interactively**: Spin up [Studios](/platform-cloud/studios/overview) with JupyterLab, R-IDE, VS Code, or Xpra remote desktops on a connected compute environment. - **Manage data**: Browse data across AWS, Azure, and Google Cloud buckets with [Data Explorer](/platform-cloud/data/data-explorer), and trace pipeline provenance with [Data Lineage](/platform-cloud/data/data-lineage) (public preview). - **Optimize cost and performance**: Get automated resource recommendations from [pipeline optimization](/platform-cloud/pipeline-optimization/overview). - **Work with AI**: Use [Co-Scientist](/platform-cloud/co-scientist/) and MCP-compatible agents to write, debug, and run pipelines. - **Collaborate securely**: Share pipelines, data, and compute across [organizations and teams](/platform-cloud/orgs-and-teams/workspace-management). - **Access curated pipelines**: Run production-tested [community pipelines](https://seqera.io/pipelines/) from [nf-core](https://nf-co.re/) and others. - **Automate workflows**: [Automate](/platform-cloud/getting-started/quickstart-demo/automation) launches as part of larger enterprise processes. :::tip [**Sign up**](https://cloud.seqera.io "Seqera Platform Cloud") to try Seqera Cloud for free, or request a [**Seqera Enterprise demo**](https://seqera.io/demo "Seqera Platform Enterprise Demo") for deployments in your own on-premises or cloud environment. ::: ### Access Seqera Cloud Log in to [Seqera Cloud](https://cloud.seqera.io/login) with your GitHub or Google account, or by providing an email address. If you are signing in for the first time, Seqera Cloud sends an authentication link to the email address to enable login. Upon your first login, you arrive in `community/showcase`, a workspace pre-filled with resources to launch your first pipeline with public data. - To begin launching Showcase pipelines, see [Launch pipelines](/platform-cloud/getting-started/quickstart-demo/launch-pipelines). - To skip the Showcase and begin adding your own pipelines and resources, see [Set up your workspace](/platform-cloud/getting-started/workspace-setup) to first create your own organizations and workspaces. --- ## Explore Seqera Cloud When you create a Seqera Cloud account with a verified work email, Seqera provisions managed starter resources on your first login. These resources include a Seqera compute environment and $100 in free credits to launch pipelines and Studios. :::note Generic email domains like Gmail are not eligible for the free resources detailed in this guide. ::: ## Your free resources When you first log in after verifying your email, Platform creates an organization and workspace for you. Select **Explore Platform** to look around your workspace while starter resources provision in the background. Provisioning typically takes under a minute. When setup completes, a banner confirms that your starter resources are ready. Platform provisions four types of resources to get you started: - A [Seqera Compute environment](./compute-envs/seqera-compute.md) with $100 in free credits. These credits can be used to run pipelines or Studios - [Credentials](./credentials/overview.md) used by your compute environment to create and manage cloud resources on your behalf - A cloud storage bucket in [Data Explorer](./data/data-explorer.md) - Pre-configured nf-core pipelines, ready to launch ### Seqera Compute environment Your organization workspace includes a pre-configured [Seqera Compute](https://docs.seqera.io/platform-cloud/compute-envs/seqera-compute) environment that requires no cloud account setup or configuration. Your $100 in free credits are consumed based on the computational resources your pipeline runs and Studio session use, calculated from CPU-hours, GB-hours, and network and storage costs. You can monitor your credit balance in the **Usage overview** drop-down in the top navigation bar, or view detailed usage in your organization or workspace **Settings** tab. See [Credit management](./administration/credit-management) for more information on monitoring usage and requesting additional credits. ### Data Explorer Your workspace includes an automatically provisioned cloud storage bucket in [Data Explorer](https://docs.seqera.io/platform-cloud/data/data-explorer), linked to your Seqera Compute environment. This bucket provides storage for pipeline outputs, intermediate files, and any data you want to browse or manage through the Platform interface. Your organization includes 25 GB of free cloud storage. :::tip After completing pipeline test runs, delete working directory files and other data you no longer need to manage your cloud storage optimally. ::: ### Launchpad Your workspace Launchpad includes six pre-configured [nf-core](https://nf-co.re) pipelines. Each uses a `test` profile and launches with test data. #### nextflow-io/hello Nextflow's [Hello World](https://github.com/nextflow-io/hello) is an example pipeline that demonstrates basic Nextflow functionality. Use it to verify that your compute setup works and to see how pipeline execution works in Platform. **To launch this pipeline**: 1. From the **Launchpad** in the left navigation menu, select **Launch** next to the **nextflow-io/hello** pipeline. 1. While this pipeline requires no inputs to run, you can optionally explore the parameters in the launch form. For example, note the **Work directory** is pre-populated with your compute environment work directory path. 1. Select **Launch**. #### nf-core/demultiplex The [nf-core/demultiplex](https://nf-co.re/demultiplex) pipeline separates pooled sequencing reads into individual samples based on barcode sequences. It supports Illumina sequencing data and can handle both single and dual indexing strategies. Sequencing facilities often pool multiple samples into a single sequencing run to reduce costs. This pipeline separates the pooled data back into individual sample files based on the unique barcode assigned to each sample during library preparation. **To launch this pipeline**: 1. From the **Launchpad** in the left navigation menu, select **Launch** next to the **nf-core/demultiplex** pipeline. 1. From the **General config** tab, scroll down and copy your **Work directory** path. You can optionally enter a custom **Workflow run name** or create and add **Labels** to the run. 1. From the **Run parameters** tab, scroll to the **outdir** field and paste your work directory path. Add `/demultiplex/outdir` to the end to keep your cloud storage organized. 1. If the **input** field is not automatically populated, fetch and paste the example samplesheet URL from the [nf-core/demultiplex documentation](https://nf-co.re/demultiplex/latest/docs/usage#example-pipeline-samplesheet). 1. Select **Launch**. #### nf-core/molkart The [nf-core/molkart](https://nf-co.re/molkart) pipeline performs spatial analysis of highly multiplexed tissue imaging data. It processes images from technologies like CODEX, CycIF, or IMC to segment cells, quantify marker expression, and analyze spatial relationships between cells. This pipeline is used in spatial biology and pathology research to understand how different cell types are organized in tissue and how they interact. For example, researchers studying tumor immunology use it to map where immune cells are located relative to cancer cells and analyze their spatial relationships. **To launch this pipeline**: 1. From the **Launchpad** in the left navigation menu, select **Launch** next to the **nf-core/molkart** pipeline. 1. From the **General config** tab, scroll down and copy your **Work directory** path. You can also optionally enter a custom **Workflow run name** or create and add **Labels** to the run. 1. From the **Run parameters** tab, scroll to the **outdir** field and paste your work directory path. Add `/molkart/outdir` to the end to keep your cloud storage organized. 1. If the **input** field is not automatically populated, fetch and paste the example samplesheet URL from the [nf-core/molkart documentation](https://nf-co.re/molkart/latest/docs/usage#full-samplesheet). 1. Select **Launch**. #### nf-core/rnaseq RNA-seq is one of the most common applications in genomics research. Scientists use this pipeline to measure gene expression levels across different conditions, time points, or tissues. For example, researchers studying disease mechanisms might compare gene expression between healthy and diseased tissue to identify which genes are turned on or off. The [nf-core/rnaseq](https://nf-co.re/rnaseq) pipeline performs RNA sequencing analysis, from raw reads to gene expression quantification. It includes quality control, read alignment, transcript quantification, and quality metrics reporting. **To launch this pipeline**: 1. From the **Launchpad** in the left navigation menu, select **Launch** next to the **nf-core/rnaseq** pipeline. 1. From the **General config** tab, scroll down and copy your **Work directory** path. You can also optionally enter a custom **Workflow run name** or create and add **Labels** to the run. 1. From the **Run parameters** tab, scroll to the **outdir** field and paste your work directory path. Add `/rnaseq/outdir` to the end to keep your cloud storage organized. 1. If the **input** field is not automatically populated, fetch and paste the example samplesheet URL from the [nf-core/rnaseq documentation](https://nf-co.re/rnaseq/latest/docs/usage#full-samplesheet). 1. Select **Launch**. #### nf-core/sarek The [nf-core/sarek](https://nf-co.re/sarek) pipeline performs variant calling and annotation from whole genome or targeted sequencing data. It detects germline and somatic variants, including SNVs, indels, and structural variants, and annotates them. This pipeline is widely used in cancer genomics and rare disease research. Clinical researchers use Sarek to identify disease-causing mutations in patient genomes, while cancer researchers use it to detect somatic mutations in tumor samples and compare them to normal tissue. **To launch this pipeline**: 1. From the **Launchpad** in the left navigation menu, select **Launch** next to the **nf-core/sarek** pipeline. 1. From the **General config** tab, scroll down and copy your **Work directory** path. You can also optionally enter a custom **Workflow run name** or create and add **Labels** to the run. 1. From the **Run parameters** tab, scroll to the **outdir** field and paste your work directory path. Add `/sarek/outdir` to the end to keep your cloud storage organized. 1. If the **input** field is not automatically populated, fetch and paste the example samplesheet URL from the [nf-core/sarek documentation](https://nf-co.re/sarek/latest/docs/usage#overview-samplesheet-columns). 1. Select **Launch**. #### nf-core/scrnaseq The [nf-core/scrnaseq](https://nf-co.re/scrnaseq) pipeline processes single-cell RNA sequencing data. It performs read alignment, cell barcode and UMI quantification, quality control, and generates count matrices for downstream analysis. Single-cell RNA-seq allows researchers to measure gene expression in individual cells rather than bulk tissue. This pipeline is used to study cellular heterogeneity, identify rare cell populations, and understand how individual cells respond differently to treatments or disease states. For example, immunologists use it to characterize the diverse cell types within the immune system. **To launch this pipeline**: 1. From the **Launchpad** in the left navigation menu, select **Launch** next to the **nf-core/scrnaseq** pipeline. 1. From the **General config** tab, scroll down and copy your **Work directory** path. You can also optionally enter a custom **Workflow run name** or create and add **Labels** to the run. 1. From the **Run parameters** tab, scroll to the **outdir** field and paste your work directory path. Add `/scrnaseq/outdir` to the end to keep your cloud storage organized. 1. If the **input** field is not automatically populated, fetch and paste the example samplesheet URL from the [nf-core/scrnaseq documentation](https://nf-co.re/scrnaseq/latest/docs/usage#full-samplesheet). 1. Select **Launch**. ### Studios Studios are cloud-based, on-demand development environments for interactive bioinformatics work. They integrate with Seqera Platform and offer VS Code or JupyterLab interfaces with access to your pipeline data and compute resources. While your free workspace does not include an existing Studio, see [Studios for interactive analysis](https://docs.seqera.io/platform-cloud/studios/overview) to learn how to configure and run Studios on your Seqera Compute environment. The guide includes instructions for adding publicly available data to analyze in your Studios. ## Next steps After launching your first pipelines, you can: - [Monitor run progress](./monitoring/run-details.mdx) - [Explore output data](./data/data-explorer.md) When you're ready to run pipelines and Studios with your own data, you can: - [Add data](./getting-started/quickstart-demo/add-data.md) - [Add new pipelines](./getting-started/quickstart-demo/add-pipelines.md) - [Add participants](./getting-started/workspace-setup.md) to collaborate with your team Contact the [Seqera community forum](https://community.seqera.io/) or ask [Co-scientist](https://ai.seqera.io) if you encounter any unexpected issues or need assistance. --- ## Reports Most Nextflow pipelines will generate reports or output files which are useful to inspect at the end of the pipeline execution. Reports may be in various formats (e.g. HTML, PDF, TXT) and would typically contain quality control (QC) metrics that would be important to assess the integrity of the results. **Reports** allow you to directly visualize supported file types or to download them via the user interface (see [Limitations](#limitations)). This saves users the time and effort of having to retrieve and visualize output files from their local storage. ### Visualize reports Available reports are listed in a **Reports** tab on the **Runs** page. You can select a report from the table to view or download it (see [Limitations](#limitations) for supported file types and sizes). To open a report preview, the file must be smaller than 10 MB. You can download a report directly or from the provided file path. Reports larger than 25 MB cannot be downloaded directly — the option to download from file path is given instead. ### Configure reports Create a config file that defines the paths to a selection of output files published by the pipeline for Seqera to render reports. There are 2 ways to provide the config file, both of which have to be in YAML format: 1. **Pipeline repository**: If a file called `tower.yml` exists in the root of the pipeline repository then this will be fetched automatically before the pipeline execution. 2. **Seqera Platform interface**: Provide the YAML definition within the **Advanced options > Seqera Cloud config file** box when: - Creating a pipeline in the Launchpad. - Amending the launch settings during pipeline launch. This is available to users with the **Maintain** role only. :::caution Any configuration provided in the interface will override configuration supplied in the pipeline repository. ::: ### Configure reports for Nextflow CLI runs The reports and log files for pipeline runs launched with Nextflow CLI (`nextflow run -with-tower`) can be accessed directly in Platform. The files generated by the run must be accessible to your workspace's primary compute environment. Specify your workspace prior to launch by setting the `TOWER_WORKSPACE_ID` environment variable. Reports are listed under the **Reports** tab on the run details page. Execution logs are available in the **Logs** tab by default, provided the output files are accessible to your workspace primary compute environment. To specify additional report files to be made available, your pipeline repository root folder must include a `tower.yml` file that specifies the files to be included (see below). ### Reports implementation Pipeline reports need to be specified using YAML syntax: ```yaml reports: : display: text to display (required) mimeType: file mime type (optional) ``` ### Path pattern Only the published files (using the Nextflow `publishDir` directive) are candidate files for reports. The path pattern is used to match published files to a report entry. It can be a partial path, a glob expression, or just a file name. Examples of valid path patterns are: - `multiqc.html`: This will match all the published files with this name. - `**/multiqc.html`: This is a glob expression that matches any subfolder. It's equivalent to the previous expression. - `results/output.txt`: This will match all the `output.txt` files inside any `results` folder. - `*_output.tsv`: This will match any file that ends with `\_output.tsv`. :::caution To use `*` in your path pattern, you must wrap the pattern in double quotes for valid YAML syntax. ::: ### Display Display defines the title that will be shown on the website. If there are multiple files that match the same pattern, a suffix will be added automatically. The suffix is the minimum difference between all the matching paths. For example, given this report definition: ```yaml reports: "**/out/sheet.tsv": display: "Data sheet" ``` For paths `/workdir/sample1/out/sheet.tsv` and `/workdir/sample2/out/sheet.tsv`, both match the path pattern. The final display name will for these paths will be _Data sheet (sample1)_ and _Data sheet (sample2)_. ### MIME type By default, the MIME type is deduced from the file extension, so you don't need to explicitly define it. Optionally, you can define it to force a viewer, for example showing a `txt` file as a `tsv`. It is important that it is a valid MIME-type text, otherwise it will be ignored and the extension will be used instead. ### Built-in reports Nextflow can generate a number of built-in reports: - [Execution report](https://docs.seqera.io/nextflow/reports#execution-report) - [Execution timeline](https://docs.seqera.io/nextflow/reports#timeline-report) - [Trace file](https://docs.seqera.io/nextflow/reports#trace-report) - [Workflow diagram](https://docs.seqera.io/nextflow/reports#dag-visualisation) (i.e. DAG) In Nextflow version 24.03.0-edge and later, these reports can be included as pipeline reports in Platform. Specify them in `tower.yml` like any other file: ```yaml reports: "report.html": display: "Nextflow execution report" "timeline.html": display: "Nextflow execution timeline" "trace.txt": display: "Nextflow trace file" "dag.html": display: "Nextflow workflow diagram" ``` :::note The filenames must match any custom filenames defined in the Nextflow config: - Execution report: `report.file` - Execution timeline: `timeline.file` - Trace file: `trace.file` - Workflow diagram: `dag.file` ::: ### Limitations The current reports implementation limits rendering to the following formats: `HTML`, `csv`, `tsv`, `pdf`, and `txt`. In-page rendering/report preview is restricted to files smaller than 10 MB. Larger files need to be downloaded first. The download is restricted to files smaller than 25 MB. Files larger than 25 MB need to be downloaded from the path. YAML formatting validation checks both the `tower.yml` file inside the repository and the UI configuration box. The validation phase will produce an error message if you try to launch a pipeline with non-compliant YAML definitions. --- ## Resource labels Platform supports resource labels in compute environments, pipelines, actions, runs, and Studios. This provides a flexible tagging system for annotating and tracking the cloud resources consumed by a run or Studio. Resource labels are sent to the cloud service provider in `key=value` format. Resource labels enable: - Cloud resource attribution across projects and teams - Granular cloud cost tracking - Resource organization and management - Compliance and governance enforcement ## How resource labels work Resource labels can be applied to compute environments, pipelines, actions, runs, and Studios. Resource labels are propagated to cloud resources during: - Compute environment creation - Workflow submission - Workflow execution - The start of a Studio's first session :::info Seqera applies resource labels to cloud resources in one direction only. Any tags changed or deleted directly in your cloud environment will not be reflected in Seqera. ::: :::note Resource labels are normally created and managed in Seqera at the workspace, compute environment, pipeline, action, run, and Studio levels. Advanced users can also define resource labels directly in Nextflow configuration using the [`resourceLabels`](https://docs.seqera.io/nextflow/reference/process#resourcelabels) process directive, set per process or globally with `process.resourceLabels`. Labels defined this way are applied by Nextflow at task submission and execution time. ::: ### Resource labels applied to compute environments Resource labels can be applied to all cloud compute environments. Cloud resources are tagged when a pipeline run is launched or a Studio is started with those resource labels applied. :::info If a compute environment is created with Batch Forge, it propagates resource labels to all cloud resources during the compute environment creation process. See [AWS](#aws) for the list of resources tagged during Batch Forge creation time. ::: ### Resource labels applied to a pipeline run A run inherits resource labels applied at the compute environment, pipeline, and action level. Resource labels can also be added or overridden during pipeline launch. When a run is executed with resource labels attached: - Seqera propagates the labels to the set of resources [listed for each provider](#resource-label-propagation-to-cloud-environments). - Nextflow distributes the labels for the resources spawned at runtime. ### Resource labels applied to a Studio A Studio inherits resource labels applied at the compute environment level. Resource labels can also be added or overridden when you add a Studio. When a Studio starts with resource labels attached: - Seqera propagates the labels to the set of resources [listed for each provider](#resource-label-propagation-to-cloud-environments). ## Prerequisites and limitations - Resource labels are only available for cloud environments that use a resource tagging system. AWS, Azure, Google, and Kubernetes are supported. HPC compute environments do not support resource labels. - Cloud provider credentials must have the appropriate roles or permissions to tag resources in your environment. - You can't assign multiple resource labels, using the same key, to the same resource, regardless of whether this option is supported by the destination cloud provider. ## Create resource labels **Workspace-level resource labels**: Create resource labels at the workspace level for consistent use across compute environments, pipelines, actions, runs, and Studios: 1. In your workspace, select **Settings** > **Edit labels**. 1. Select **Add label**. 1. Under **Type**, select **Resource label**. 1. Enter a **Name** such as `owner`, `team`, or `platform-run`. 1. Enter a **Value**: - **Standard resource labels**: ``, `TEAM_NAME` - **[Dynamic resource labels](#dynamic-resource-labels)**: Use variable syntax — `${sessionId}`, `${userName}`, or `${workflowId}` 1. Optionally, enable **Use as default in compute environment form** to automatically apply this resource label to all new compute environments in this workspace. 1. Select **Save**. **Create resource labels during compute environment, pipeline, action, run, and Studio creation**: Resource labels can also be created and added to new Platform entities on the fly. The deletion of a resource label from a workspace has no influence on the cloud environment. :::info All users can add resource labels, but only maintainers (or higher) can edit or delete them, provided they're not already associated with **any** resource. ::: ## Apply resource labels Once created at the workspace level, resource labels can be applied to: - **Compute environments**: In the **Resource labels** field when creating a new compute environment. Once the compute environment has been created, its resource labels cannot be edited. - **Pipelines**: In the **Resource labels** field when adding or editing a pipeline. - **Actions**: In the **Resource labels** field when creating or editing an action. - **Pipeline runs**: In the **Resource labels** field when launching a pipeline. - **Studios**: In the **Resource labels** field when adding a Studio. Resource labels from the compute environment or pipeline are prefilled in the pipeline launch form, and compute environment resource labels are prefilled in the Studio add form. You can apply or override these labels when you launch a pipeline or add a Studio. Workspace maintainers can override default resource labels inherited from the compute environment when they create or edit pipelines, actions, runs, and Studios. Custom resource labels associated with each element propagate to resources in your cloud provider account. They don't alter the default resource labels on the compute environment. When you add or edit resource labels associated with a pipeline, action, run, or Studio, the **submission and execution time** resource labels are altered. This does not affect the resource labels for resources spawned at compute environment **creation time**. For example, the resource label `name=ce1` is set during AWS Batch compute environment creation. If you create the resource label `pipeline=pipeline1` while launching a pipeline with the same AWS Batch compute environment, the EC2 instances associated with that compute environment will still contain only the `name=ce1` label. Job Definitions associated with the pipeline run will inherit the `pipeline=pipeline1` resource label. If a maintainer changes the compute environment associated with a pipeline, the **Resource labels** field is updated with the resource labels from the new compute environment. ## Dynamic resource labels Dynamic resource labels extend the standard resource labels functionality by allowing variable values that are populated with unique workflow identifiers at runtime. This enables precise cost tracking and resource attribution for individual pipeline runs across cloud compute environments. Standard resource labels use static key-value pairs, such as `project=research` or `environment=production`. Dynamic resource labels use variable placeholders. Seqera and Nextflow resolve these placeholders when a workflow runs: | Value | Description | |-----------------|---------------------| | `${workflowId}` | Platform run ID | | `${sessionId}` | Nextflow session ID | | `${userName}` | Platform username (run launch user) | For example, a dynamic resource label `platformRun=${workflowId}` becomes `platformRun=12345abcde` when applied to the cloud resources consumed by run `12345abcde`. Additional dynamic values, such as the user or team that launched a run, will be supported in a future release. :::info **Dynamic resource labels** tag resources with unique values for each pipeline run. Nextflow applies these labels at workflow submission and execution time, not during compute environment creation. See the **Submission time** and **Execution time** resources listed for each cloud provider in the [Resource label propagation](#resource-label-propagation-to-cloud-environments) section. ::: ### Benefits of dynamic resource labels Dynamic resource labels provide several key advantages: - **Granular cost tracking**: Associate cloud costs with specific workflow runs rather than entire compute environments or projects. - **Automated attribution**: Apply resource labels automatically at execution time - no manual tagging of individual runs. - **Enhanced reporting**: Filter and group costs by individual workflow runs in your cloud provider's cost management tools. - **Audit trails**: Track resource usage patterns for specific workflows over time. ## Search and filter with resource labels Search and filter pipelines on the Launchpad, and runs on the **Runs** tab, using one or more resource labels. The resource label search uses a `label:key=value` format. ## Resource label propagation to cloud environments ### AWS The following resources are tagged using the resource labels associated with the compute environment (either [Batch](../compute-envs/aws-batch) or [Cloud](../compute-envs/aws-cloud)): **Batch**: - **Batch Forge creation time** - FSX Filesystems (does not cascade to files) - EFS Filesystems (does not cascade to files) - Batch Compute Environment - Batch Queue(s) - ComputeResource (EC2 instances, including EBS volumes) - Service role - Spot Fleet role - Execution role - Instance Profile role - Launch template - **Submission time** - Jobs and Job Definitions - Tasks (via the `propagateTags` parameter on Job Definitions) - **Execution time** - Work Tasks (via the `propagateTags` parameter on Job Definitions) **Cloud**: - **Submission and execution time** - ComputeResource (EC2 instances, including EBS volumes) At execution time, when jobs are submitted to Batch, the requests are set up to propagate tags to all the instances and volumes created by the head job. :::caution Only compute environments and their associated queues **created by Batch Forge** are tagged with your resource labels automatically. AWS Batch compute environments, job queues, or other resources you create **manually outside of Seqera** don't inherit these tags, so their costs aren't attributable in AWS Cost Explorer or your data exports until you tag them yourself. If you run a mix of Forge-created and manually created queues, add the relevant cost-allocation tag (for example, `project=`) to the manually created resources in the AWS console. ::: The [IAM permissions](../compute-envs/aws-batch#required-platform-iam-permissions) contain the roles needed for Batch Forge-created AWS Batch compute environments to tag AWS resources. Specifically, the required roles are `iam:TagRole`, `iam:TagInstanceProfile`, and `batch:TagResource`. #### Verify resource label propagation to AWS Resource labels applied in Seqera surface as AWS tags with the same `key=value` on the resources listed above. For example, a resource label `project=rnaseq` on a Batch Forge compute environment is applied as the AWS tag `project=rnaseq` on the Batch compute environment, job queues, and EC2 instances at creation time, and on the jobs and job definitions submitted for each run. A dynamic resource label such as `platformRun=${workflowId}` is applied as a tag like `platformRun=12345abcde` on the jobs and job definitions spawned by that run. To view, manage, and verify the resource labels applied to AWS resources by Seqera and Nextflow, go to the [AWS Tag Editor](https://docs.aws.amazon.com/tag-editor/latest/userguide/find-resources-to-tag.html) (as an administrative user) and follow these steps: 1. Under **Find resources to tag**, search for the resource label key and value in the relevant search fields under **Tags**. Your search can be further refined by AWS region and resource type. 1. Select **Search resources**. **Resource search results** display all the resources tagged with your given resource label key and/or value. ### Include Seqera resource labels in AWS billing reports To include the cost information associated with your resource labels in your AWS billing reports, you need to activate cost allocation tags. The method for viewing costs differs between static and dynamic resource labels: :::tip Resource labels combined with your cloud provider's native cost tools are the recommended way to achieve full cost accounting — including compute, storage, and networking — for your pipeline runs. Avoid custom wrapper scripts that dedicate an entire EC2 instance to a single job to attribute cost: this pattern is incompatible with AWS Batch's shared-instance scheduling model and typically increases cost. Tag your resources with resource labels and report on them in AWS Cost Explorer or your data exports instead. ::: **For static resource labels**: Because static resource labels have fixed values at compute environment creation time or workflow submission time, they are applied to static resources including Batch compute environments and EC2 instances. Static resource label costs can be viewed in AWS Cost Explorer, [Data Exports](https://docs.aws.amazon.com/cur/latest/userguide/what-is-data-exports.html), and QuickSight dashboards. **For dynamic resource labels**: Dynamic resource labels are only propagated at workflow submission and execution time. This means only jobs and job definitions (for AWS Batch compute environments), and EC2 instances (for AWS Cloud compute environments) spawned at runtime are tagged with the unique workflow identifiers. You must [enable split cost allocation data](https://docs.aws.amazon.com/cur/latest/userguide/enabling-split-cost-allocation-data.html) and view costs in [AWS Data Exports](https://docs.aws.amazon.com/cur/latest/userguide/what-is-data-exports.html) and Cost and Usage Reports (CUR). Dynamic resource label costs are not visible in AWS Cost Explorer, which does not support split cost allocation data. **Steps to activate cost allocation tags**: 1. **Wait for tag creation**: After creating resources with resource labels, wait up to 24 hours for the tag keys to appear in your cost allocation tags page 2. **Activate cost allocation tags**: [Activate](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html) the associated tags in the **AWS Billing and Cost Management console**. Newly-applied tags may take up to 24 hours to appear on your cost allocation tags page. - In the navigation pane, choose **Cost allocation tags** - Select the tag keys you want to activate - Choose **Activate** - Allow up to 24 hours for tags to activate 3. **For static resource labels - View in Cost Explorer or Data Exports**: - Navigate to AWS Cost Explorer and use **Group by** filters to organize costs by your activated tag keys - Create [cost allocation reports](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/configurecostallocreport.html#allocation-viewing) including your resource label tags - Alternatively, view in Data Exports and QuickSight dashboards for more detailed analysis 4. **For dynamic resource labels - Enable split cost allocation and view in Data Exports**: - [Enable split cost allocation data](https://docs.aws.amazon.com/cur/latest/userguide/enabling-split-cost-allocation-data.html) in your Cost and Usage Reports preferences - View costs in your [Data Exports](https://docs.aws.amazon.com/cur/latest/userguide/what-is-data-exports.html) and Cost and Usage Reports (CUR) - Query reports using Amazon Athena or visualize in Amazon QuickSight dashboards (requires a QuickSight subscription) - For a complete walkthrough, see our [guide to AWS cost tracking with resource labels](https://seqera.io/blog/aws-labels-cost-tracking/) #### Verify cost data in your AWS billing reports After you activate cost-allocation tags, cost data for your labeled resources typically appears in Cost Explorer and your data exports (CUR/Parquet) only after a **24–48 hour delay**. To confirm that your labels and their costs landed, inspect the data export directly — for example, query the Parquet files with Amazon Athena, or download and open them — and check that your resource-label tag keys are present and associated with non-zero costs. :::caution AWS Cost and Usage Reports normalize tag characters. In CUR (version 2), colons (`:`) are rewritten as underscores (`_`), and mixed- or upper-case characters are lowercased and separated with underscores. For example, a tag key `costCenter` can appear as `cost_center`, and `team:genomics` as `team_genomics`, in the export. Design your resource-label keys and values so they remain unambiguous after this normalization, and account for it in downstream Athena or QuickSight queries. ::: #### AWS limitations - Resource label keys and values must contain a minimum of 2 and a maximum of 39 alphanumeric characters (each), separated by dashes or underscores. - The key and value cannot begin or end with dashes `-` or underscores `_`. - The key and value cannot contain a consecutive combination of `-` or `_` characters (`--`, `__`, `-_`, etc.) - A maximum of 25 resource labels can be applied to each resource. - A maximum of 1000 resource labels can be used in each workspace. - Keys and values cannot start with `aws` or `user`, as these are reserved prefixes appended to tags by AWS. - Keys and values are case-sensitive in AWS. See [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions) for more information on AWS resource tagging. ### Google Cloud The following resources are tagged using the labels associated with the compute environment (either [Batch](../compute-envs/google-cloud-batch.md) or [Cloud](../compute-envs/google-cloud.md)): **Submission time** - Job (Batch) **Execution time** - AllocationPolicy (Batch) - VirtualMachine (Cloud) #### View costs by resource labels in Google Cloud Google Cloud includes resource labels in billing data for cost analysis and reporting: 1. **Access Billing Console**: Go to [Google Cloud Billing](https://console.cloud.google.com/billing) and navigate to **Reports** in the Cost management section. 2. **Configure Reports**: Use the **Labels** filter to select specific label keys and set **Group by** to organize costs by your label values. 3. **Export for Analysis**: - [Enable Cloud Billing export to BigQuery](https://cloud.google.com/billing/docs/how-to/export-data-bigquery) for detailed analysis and custom reporting. - Use tools like [Looker Studio](https://cloud.google.com/looker-studio) to visualize your labeled cost data. #### Google Cloud limitations - Resource label keys and values must contain a minimum of 2 and a maximum of 39 alphanumeric characters (each), separated by dashes or underscores. - The key and value cannot begin or end with dashes `-` or underscores `_`. - The key and value cannot contain a consecutive combination of `-` or `_` characters (`--`, `__`, `-_`, etc.) - A maximum of 25 resource labels can be applied to each resource. - A maximum of 1000 resource labels can be used in each workspace. - Keys and values in Google Cloud Resource Manager may contain **only lowercase letters**. Resource labels created with uppercase characters are **automatically converted to lowercase** in Platform before being propagated to Google Cloud. See [here](https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements) for more information on Google Cloud Resource Manager labeling. ### Azure The following resources receive the labels associated with the compute environment (either [Batch](../compute-envs/azure-batch.md) or [Cloud](../compute-envs/azure-cloud.md)): **Batch**: - **Compute environment creation time** - Pool metadata (Azure Batch Pool) - **Submission time** - Jobs - **Execution time** - Tasks Static resource labels from the compute environment are written to the Azure Batch Pool `metadata` fields when the compute environment is created, and are also propagated to Azure Batch jobs and tasks at submission and execution time. Resource labels added or overridden when you launch a pipeline are applied only to Azure Batch submission and execution time resources. Dynamic resource labels do not modify the existing Pool metadata. **Cloud**: - **Submission and execution time** - Virtual machines and related resources #### View costs by resource labels in Azure Azure cost analysis by tags applies to Azure Resource Manager resources that support tags, such as Azure Cloud virtual machines and related resources. Azure Batch uses `metadata` pairs rather than Azure Resource Manager tags, so Azure Batch resource labels may have limited or no visibility in Azure Cost Management. :::note For Azure Batch, both static and dynamic resource labels are added as `key=value` metadata pairs on Azure Batch jobs and tasks. Dynamic resource labels are not applied to the Azure Batch Pool itself. Because Azure Batch uses metadata rather than Azure Resource Manager tags, these labels may not be available for filtering or grouping in **Cost Management**. ::: **Prerequisites for tag-based Azure cost tracking**: Billing profile contributor/owner permissions for billing profile tags, and Contributor role or Tag Contributor role for resource tagging. **Steps to enable tag-based cost tracking for Azure-tagged resources**: 1. **Enable Tag Inheritance** (recommended): Navigate to Cost Management in the Azure portal, select a billing account or subscription scope, and under **Settings** > **Configuration** > **Tag inheritance**, enable **Automatically apply subscription and resource group tags to new data**. See [Azure tag inheritance documentation](https://docs.microsoft.com/en-us/azure/cost-management-billing/costs/enable-tag-inheritance) for detailed steps. 2. **View Tagged Costs**: Navigate to **Cost Management + Billing** > **Cost Management** > **Cost analysis** and select **Group by** for your tag key. 3. **Create Budgets with Tag Filters**: [Create budgets with filters](https://docs.microsoft.com/en-us/azure/cost-management-billing/costs/tutorial-acm-create-budgets) on the inherited tags, available 24 hours after enabling tag inheritance. #### Azure limitations - Resource label keys and values must contain a minimum of 2 and a maximum of 39 alphanumeric characters (each), separated by dashes or underscores. - The key and value cannot begin or end with dashes `-` or underscores `_`. - The key and value cannot contain a consecutive combination of `-` or `_` characters (`--`, `__`, `-_`, etc.) - A maximum of 25 resource labels can be applied to each resource. - A maximum of 1000 resource labels can be used in each workspace. - Keys are case-insensitive, but values are case-sensitive. - Microsoft advises against using a non-English language in your resource labels, as this can lead to decoding progress failure while loading your VM's metadata. Tags are not available for tenant resources not associated with subscriptions, classic resources, or some resource types that don't support tags in usage data. See [here](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/tag-resources?tabs=json) for more information on Azure Resource Manager tagging. ### Kubernetes Both the Head pod and Work pod specs will contain the set of resource labels associated with the compute environment in addition to the standard resource labels applied by Seqera Platform and Nextflow. :::caution Currently, tagging with resource labels is not available for the files created during a workflow execution. The cloud instances are the elements being tagged. ::: The following resources will be tagged using the resource labels associated with the compute environment: **Compute environment creation time** - Deployment - PodTemplate **Submission time** - Head Pod Metadata **Execution time** - Run Pod Metadata #### Kubernetes limits - Resource label keys and values must contain a minimum of 2 and a maximum of 39 alphanumeric characters (each), separated by dashes or underscores. - The key and value cannot begin or end with dashes `-` or underscores `_`. - The key and value cannot contain a consecutive combination of `-` or `_` characters (`--`, `__`, `-_`, etc.) - A maximum of 25 resource labels can be applied to each resource. - A maximum of 1000 resource labels can be used in each workspace. See [Syntax and character set](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) for more information on Kubernetes object labeling. ## Best Practices - **Use descriptive keys**: Choose tag keys that clearly indicate their purpose (e.g., `workflow-id`, `pipeline-run`, `session-id`). - **Plan for cost analysis**: Consider how you'll group and filter costs in your cloud provider's tools when designing your tag schema. - **Combine static and dynamic resource labels**: Use dynamic resource labels alongside static resource labels for comprehensive cost attribution (e.g., static `project=genomics` with dynamic `platformRun=${workflowId}`). - **Monitor tag limits**: Stay within cloud provider tag limits (25 tags per resource for AWS/GCP/Azure). - **Document your schema**: Maintain documentation of your tagging strategy for team members who will analyze costs. ## Troubleshooting See [Resource labels](../troubleshooting_and_faqs/resource-labels.md) for troubleshooting common resource label propagation errors. --- ## Secrets **Secrets** store the keys and tokens used by workflow tasks to interact with external systems, such as a password to connect to an external database or an API token. Seqera Platform relies on third-party secret manager services to maintain security between the workflow execution context and the secret container. This means that no secure data is transmitted from your Seqera instance to the compute environment. :::note AWS, Google Cloud, and HPC compute environments are currently supported. See [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/index.html) and [Google Secret Manager](https://cloud.google.com/secret-manager/docs/overview) for more information. ::: ## Pipeline secrets To create a pipeline secret, go to a workspace (private or shared) and select the **Secrets** tab in the navigation bar. Available secrets are listed here and users with appropriate [permissions](../orgs-and-teams/roles) (maintainer, admin, or owner) can create or update secret values. :::note Multi-line secrets must be base64-encoded. ::: Select **Add Pipeline Secret** and enter a name and value for the secret. Then select **Add**. ## User secrets Listing, creating, and updating secrets for users is the same as secrets in a workspace. You can access user secrets from **Your secrets** in the user menu. :::caution Secrets defined by a user have higher priority and will override any secrets with the same name defined in a workspace. ::: ## Use secrets in workflows When you launch a new workflow, all secrets are sent to the corresponding secrets manager for the compute environment. Nextflow downloads these secrets internally when they're referenced in the pipeline code. See [Nextflow secrets](https://docs.seqera.io/nextflow/secrets) for more information. Secrets are automatically deleted from the secret manager when the pipeline completes, successfully or unsuccessfully. :::note In AWS Batch compute environments, Seqera passes stored secrets to jobs as part of the Seqera-created job definition. Seqera secrets cannot be used in Nextflow processes that use a [custom job definition](https://docs.seqera.io/nextflow/aws#custom-job-definition). ::: ## AWS Secrets Manager integration Seqera and associated AWS Batch IAM Roles require [specific permissions](../compute-envs/aws-batch#pipeline-secrets-optional) to interact with AWS Secrets Manager. :::note If you plan to limit the scope of this IAM policy, please ensure that the ListSecrets action remains granted on all resources (`"Resource": "*"`). Otherwise, the Seqera Platform will be unable to delete secrets, which can cause workflows to remain in a running (stuck) state. For more details, see the AWS documentation: [AWS Secrets Manager actions and permissions reference](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions) ::: ### ECS Agent permissions The ECS Agent uses the [Batch Execution role](https://docs.aws.amazon.com/batch/latest/userguide/execution-IAM-role.html#create-execution-role) to communicate with AWS Secrets Manager. - If your AWS Batch compute environment does not have an assigned execution role, create one. - If your AWS Batch compute environment already has an assigned execution role, augment it. **IAM permissions** 1. Add the [`AmazonECSTaskExecutionRolePolicy` managed policy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonECSTaskExecutionRolePolicy.html). 1. Add this inline policy (specifying ``): ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowECSAgentToRetrieveSecrets", "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager::*:secret:tower-*" } ] } ``` :::note Including `tower-*` in the Resource ARN above limits access to Platform secrets only (as opposed to all secrets in the given region). ::: **IAM trust relationship** ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowECSTaskAssumption", "Effect": "Allow", "Principal": { "Service": "ecs-tasks.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ### Compute permissions The Nextflow head job must communicate with AWS Secrets Manager. Its permissions are inherited either from a custom role assigned during the [AWS Batch CE creation process](../compute-envs/aws-batch#advanced-options), or from its host [EC2 instance](https://docs.aws.amazon.com/batch/latest/userguide/instance_IAM_role.html). Augment your Nextflow head job permissions source with one of the following policies: **EC2 Instance role** Add this policy to your EC2 Instance role: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowNextflowHeadJobToAccessSecrets", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" } ] } ``` **Custom IAM role** Add this policy to your custom IAM role (specifying `YOUR_ACCOUNT` and `YOUR_BATCH_CLUSTER`): ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowNextflowHeadJobToAccessSecrets", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" }, { "Sid": "AllowNextflowHeadJobToPassRoles", "Effect": "Allow", "Action": [ "iam:GetRole", "iam:PassRole" ], "Resource": "arn:aws:iam::YOUR_ACCOUNT:role/YOUR_BATCH_CLUSTER-ExecutionRole" } ] } ``` Add this trust policy to your custom IAM role: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowECSTaskAssumption", "Effect": "Allow", "Principal": { "Service": "ecs-tasks.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ## Google Secret Manager integration You must [enable Google Secret Manager](https://cloud.google.com/secret-manager/docs/configuring-secret-manager) in the same project that your Google compute environment credentials have access to. Your compute environment credentials require additional IAM permissions to interact with Google Secret Manager. ### IAM permissions See the [Google documentation](https://cloud.google.com/secret-manager/docs/access-control) for permission configuration instructions to integrate with Google Secret Manager. Seqera Platform requires `roles/secretmanager.admin` permissions in the project where it will manage your secrets. Ensure that your compute environment contains credentials with this access role for the same `project_id` listed in the service account JSON file. --- ## nf-core Tools The nf-core tools provide access to 1630+ pre-built, standardized Nextflow bioinformatics modules and pipelines. These tools help discover modules for specific tasks, get detailed usage information, and receive recommendations for analysis pipelines based on your data type. ## Available tools ### search_nfcore_module Search nf-core modules using natural language queries. Find modules for tasks like alignment, variant calling, quality control, assembly, and annotation. **Example prompts:** - "Find nf-core modules for quality control of sequencing data" - "Search for alignment modules that support paired-end reads" - "What modules are available for variant calling?" - "Find modules for RNA-seq quantification" - "Search for tools that can trim adapters from FASTQ files" ### describe_nfcore_module Get comprehensive metadata for a specific module including input/output schemas, command templates, configuration examples, and AI execution guidance. **Example prompts:** - "Describe the nf-core/fastqc module" - "Show me how to use the bwa/mem module" - "What are the inputs and outputs for samtools/sort?" - "Give me the Nextflow command to run the multiqc module" - "How do I configure the star/align module for my analysis?" ### nfcore_suggest_analysis Suggest appropriate nf-core pipelines and reference genomes based on library strategy and organism. Maps sequencing assay types to recommended analysis workflows. **Supported library strategies:** - RNA-Seq, mRNA-Seq → nf-core/rnaseq - WGS, WXS → nf-core/sarek - ATAC-Seq → nf-core/atacseq - ChIP-Seq → nf-core/chipseq - Bisulfite-Seq → nf-core/methylseq - miRNA-Seq → nf-core/smrnaseq - Amplicon → nf-core/ampliseq - Hi-C → nf-core/hic **Supported organisms (with genome builds):** - Homo sapiens → GRCh38 - Mus musculus → GRCm39 - Rattus norvegicus → Rnor_6.0 - Danio rerio → GRCz11 - Drosophila melanogaster → BDGP6 - Arabidopsis thaliana → TAIR10 - And many more... **Example prompts:** - "What pipeline should I use for human RNA-seq data?" - "Suggest an analysis pipeline for mouse ATAC-seq" - "What's the recommended genome for Homo sapiens?" - "I have WGS data from zebrafish, what should I use?" - "Recommend a pipeline for ChIP-seq analysis of mouse samples" ## Typical workflow 1. **Search** for modules using natural language with `search_nfcore_module` 2. **Describe** specific modules to understand inputs, outputs, and usage with `describe_nfcore_module` 3. **Suggest** the best pipeline and genome for your data type with `nfcore_suggest_analysis` 4. **Execute** the recommended pipeline with Nextflow ## Example session ``` User: I have paired-end RNA-seq data from human liver samples. What should I use to analyze it? AI: [Uses nfcore_suggest_analysis] Recommended pipeline: nf-core/rnaseq Pipeline URL: https://nf-co.re/rnaseq Reference genome: GRCh38 iGenomes path: s3://ngi-igenomes/igenomes/GRCh38 User: What modules does rnaseq use for quality control? AI: [Uses search_nfcore_module with "quality control RNA-seq"] Found relevant modules: 1. nf-core/fastqc - QC checks on sequencing data 2. nf-core/multiqc - Aggregate QC reports 3. nf-core/trimgalore - Adapter and quality trimming User: Tell me more about fastqc AI: [Uses describe_nfcore_module for nf-core/fastqc] Module: nf-core/fastqc Description: Run FastQC quality control checks on sequencing data Inputs: - reads: FASTQ files (*.fastq.gz) Outputs: - html: FastQC HTML report - zip: FastQC data archive Nextflow command: nextflow run nf-core/fastqc \ --input samplesheet.csv \ --outdir results \ -profile docker ``` ## Pipeline mapping reference | Library strategy | nf-core Pipeline | Description | |-----------------|------------------|-------------| | RNA-Seq | rnaseq | RNA sequencing analysis | | WGS/WXS | sarek | Variant calling for germline/somatic | | ATAC-Seq | atacseq | Chromatin accessibility | | ChIP-Seq | chipseq | Protein-DNA binding | | Bisulfite-Seq | methylseq | DNA methylation | | miRNA-Seq | smrnaseq | Small RNA analysis | | Amplicon | ampliseq | Amplicon sequencing | | Hi-C | hic | Chromosome conformation | ## Genome reference | Organism | Common name | Genome build | |----------|-------------|--------------| | Homo sapiens | Human | GRCh38 | | Mus musculus | Mouse | GRCm39 | | Rattus norvegicus | Rat | Rnor_6.0 | | Danio rerio | Zebrafish | GRCz11 | | Drosophila melanogaster | Fruit fly | BDGP6 | | Caenorhabditis elegans | Worm | WBcel235 | | Saccharomyces cerevisiae | Yeast | R64-1-1 | | Arabidopsis thaliana | Arabidopsis | TAIR10 | --- ## Seqera MCP Seqera MCP is a [Model Context Protocol](https://modelcontextprotocol.io/) server that enables AI assistants to interact with the Seqera ecosystem. It provides access to Seqera Platform, Wave containers, nf-core modules, and bioinformatics data resources. ## Features - **Seqera Platform integration**: Launch, monitor, and manage Nextflow pipelines. - **Wave container service**: Create containerized environments with conda/pip packages. - **nf-core modules**: Search and execute 1000+ standardized bioinformatics modules. - **SRA/ENA/GEO access**: Search and retrieve public sequencing data. ## Tool documentation - [Seqera Platform tools](seqera-tools.md) - Workflow management, compute environments, and containers. - [SRA Tools](sra-tools.md) - Search and retrieve sequencing data from NCBI SRA, EBI ENA, and GEO. - [nf-core Tools](nfcore-tools.md) - Search modules and get analysis recommendations. ## Remote server The hosted Seqera MCP server is available at: ```console https://mcp.seqera.io/mcp ``` ## Authentication Seqera MCP supports two authentication methods: - **OAuth 2.1** (recommended): Interactive login through Seqera Platform. Your browser opens automatically to authenticate when connecting. - **Personal Access Token**: Use your Seqera Platform [access token](https://docs.seqera.io/platform-cloud/credentials/overview) as a Bearer token. Useful for clients that don't support OAuth. ## Client setup ### Claude Code ```bash claude \ mcp add \ --scope=user \ --transport=http \ seqera \ https://mcp.seqera.io/mcp ``` ### Claude Desktop 1. Open Claude Desktop settings. 2. Select **Add connectors**. 3. Click **Add custom connector**. 4. Enter the URL: `https://mcp.seqera.io/mcp`. 5. Select **OAuth** as the authentication method. ### Cursor Create or edit `~/.cursor/mcp.json`: ```json { "mcpServers": { "seqera": { "url": "https://mcp.seqera.io/mcp" } } } ``` Restart Cursor to apply the configuration. On first use, your browser will open for authentication. ### OpenAI Codex First, enable the MCP client feature in `~/.codex/config.toml`: ```toml [features] rmcp_client = true ``` Then add the Seqera MCP server and authenticate: ```bash codex mcp add seqera --url https://mcp.seqera.io/mcp codex mcp login seqera ``` ### VS Code Create or edit `~/Library/Application Support/Code/User/mcp.json` (macOS) or `%APPDATA%\Code\User\mcp.json` (Windows): ```json { "servers": { "seqera": { "url": "https://mcp.seqera.io/mcp", "type": "http" } } } ``` ### Windsurf Create or edit `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "seqera": { "serverUrl": "https://mcp.seqera.io/mcp" } } } ``` ### Using Personal Access Token For clients that don't support OAuth, add your access token as a header: ```json { "mcpServers": { "seqera": { "url": "https://mcp.seqera.io/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ## Resources - [Model Context Protocol specification](https://modelcontextprotocol.io/) --- ## Seqera Platform Tools The Seqera tools provide comprehensive access to Seqera Platform for workflow management, compute environments, datasets, and Wave container provisioning. With 74+ tools available, this page highlights the most commonly used operations. ## RAG search tools ### search_seqera_api Natural language search across all Seqera Platform, Wave, and SeqeraHub APIs. Use this to discover available operations. **Example prompts:** - "How do I launch a workflow?" - "What APIs are available for managing compute environments?" - "Find tools for creating containers" - "Search for dataset management operations" ### call_seqera_api Execute discovered APIs with validated parameters. Use after `search_seqera_api` to perform operations. **Example prompts:** - "Call the API to list my workflows" - "Execute the container creation API" - "Run the workflow launch operation" ## Workflow management ### platform_list_workflows List all workflow runs in a workspace with status, duration, and metadata. **Example prompts:** - "List all my workflow runs" - "Show me the recent workflows in my workspace" - "What workflows have I run this week?" ### platform_get_workflow Get detailed information about a specific workflow run including status, logs, and outputs. **Example prompts:** - "Get details for workflow run 5abc123" - "Show me the status of my latest workflow" - "What's the output of workflow 12345?" ### platform_launch_workflow Launch a new workflow run with specified parameters, compute environment, and configuration. **Example prompts:** - "Launch nf-core/rnaseq with my sample sheet" - "Run the variant calling pipeline on AWS Batch" - "Start a new workflow with these parameters" ### platform_cancel_workflow Cancel a running workflow. **Example prompts:** - "Cancel workflow run 5abc123" - "Stop my currently running pipeline" ## Compute environments ### platform_list_compute_envs List available compute environments in a workspace. **Example prompts:** - "List my compute environments" - "What compute resources do I have available?" - "Show me the AWS Batch environments" ### platform_get_compute_env Get detailed configuration for a compute environment. **Example prompts:** - "Show details for compute environment aws-batch-prod" - "What's the configuration of my Kubernetes environment?" ### platform_create_compute_env Create a new compute environment (AWS Batch, Google Cloud, Azure, Kubernetes, etc.). **Example prompts:** - "Create an AWS Batch compute environment" - "Set up a new Kubernetes executor" - "Configure a Google Cloud environment for my pipelines" ## Datasets ### platform_list_datasets List datasets available in a workspace. **Example prompts:** - "List all datasets in my workspace" - "What datasets do I have available?" ### platform_create_dataset Create a new dataset from a CSV/TSV file. **Example prompts:** - "Create a dataset from my sample sheet" - "Upload this CSV as a new dataset" ## Pipelines ### platform_list_pipelines List configured pipelines in a workspace. **Example prompts:** - "List all pipelines in my workspace" - "What pipelines are available to run?" ### platform_add_pipeline Add a new pipeline to the workspace. **Example prompts:** - "Add nf-core/rnaseq to my workspace" - "Configure a new pipeline from GitHub" ## Wave container service ### wave_get_container Create a container with specified packages (conda, pip) or from a Dockerfile. **Example prompts:** - "Create a container with samtools and bwa" - "Build a container with Python 3.11 and pandas" - "Get a container with bioconda packages: salmon, kallisto" ### wave_inspect_container Inspect a container image to see its layers, packages, and metadata. **Example prompts:** - "Inspect the container image biocontainers/samtools" - "What packages are in this container?" ## Package Search ### seqerahub_search_conda Search for conda packages across bioconda, conda-forge, and other channels. **Example prompts:** - "Search for samtools in conda" - "Find bioinformatics packages for alignment" - "What versions of bwa are available?" ### seqerahub_search_pypi Search for Python packages on PyPI. **Example prompts:** - "Search for pandas on PyPI" - "Find Python packages for data visualization" ## Organizations & Teams ### platform_list_organizations List organizations you belong to. **Example prompts:** - "List my organizations" - "What organizations do I have access to?" ### platform_list_workspaces List workspaces in an organization. **Example prompts:** - "List workspaces in my organization" - "Show me all available workspaces" ### platform_list_members List members of a workspace or organization. **Example prompts:** - "Who are the members of this workspace?" - "List team members in my organization" ## Example Session ``` User: I want to run an RNA-seq analysis on my human samples AI: Let me help you set that up. First, let me check your available resources. [Uses platform_list_compute_envs] You have these compute environments: - aws-batch-prod (AWS Batch, running) - local-docker (Local, running) User: Use the AWS Batch one. I need a container with STAR and samtools AI: [Uses wave_get_container with packages: star, samtools] Created container: wave.seqera.io/wt/abc123 Contains: STAR 2.7.10b, samtools 1.17 User: Now launch nf-core/rnaseq with my samples AI: [Uses platform_launch_workflow] Launched workflow run: 5x7abc123 Pipeline: nf-core/rnaseq Compute: aws-batch-prod Status: SUBMITTED User: What's the status? AI: [Uses platform_get_workflow] Workflow: 5x7abc123 Status: RUNNING Progress: 45% (18/40 tasks complete) Running for: 2h 15m ``` ## Workspace Context Most Platform operations require a workspace context. The AI assistant automatically uses your current workspace, or you can specify one: **Example prompts:** - "List workflows in workspace 'production'" - "Switch to the 'development' workspace" - "Use organization 'my-lab' and workspace 'rnaseq-project'" --- ## SRA Tools The SRA tools provide access to public sequencing data repositories including NCBI SRA, EBI ENA, and NCBI GEO. These tools enable searching for datasets, exploring study metadata, and generating sample sheets for downstream analysis. ## Available tools ### sra_search_ncbi Search NCBI Sequence Read Archive using the E-utilities API. **Example prompts:** - "Search NCBI SRA for human RNA-seq studies on liver cancer" - "Find all single-cell RNA-seq datasets for mouse brain" - "Search for COVID-19 sequencing studies from 2023" ### sra_search_ebi Search EBI European Nucleotide Archive with advanced query syntax. **Example prompts:** - "Search EBI ENA for ATAC-seq data from Homo sapiens" - "Find paired-end Illumina WGS studies for Arabidopsis thaliana" - "Search ENA for ChIP-seq experiments targeting H3K27ac" ### sra_fetch_geo_study Fetch GEO study metadata and find linked SRA projects. Given a GSE accession, retrieves study title, summary, organism, sample count, and linked SRA/BioProject accessions. **Example prompts:** - "Get metadata for GEO study GSE147507" - "What is the GSE110004 study about and how many samples does it have?" - "Find the SRA project linked to GSE164073" ### sra_list_runs_detailed Get detailed metadata for all runs in a study, including library strategy, layout, size, and organism. Accepts both GEO (GSE) and SRA (SRP) accessions. **Example prompts:** - "List all runs in GSE147507 with their library strategies" - "Show me the detailed run information for SRP253951" - "What sequencing platforms were used in GSE110004?" ### sra_group_by_assay Group runs by assay type (library strategy + layout) for multi-assay studies. Useful for selecting specific data types from complex studies. **Example prompts:** - "Group the runs in GSE147507 by assay type" - "Show me how many RNA-seq vs ATAC-seq runs are in this study" - "Organize the runs in SRP253951 by library strategy and layout" ### sra_fetch_download_urls Get download URLs for SRA and FASTQ files with MD5 checksums. Supports FTP, HTTP, and HTTPS protocols. **Example prompts:** - "Get FASTQ download URLs for SRR10971381" - "Fetch download links for runs SRR001, SRR002, SRR003" - "Get the FTP URLs for all runs in my search results" ### sra_create_samples_sheet Generate downloadable sample sheets in CSV, TSV, or JSON format with metadata and download URLs. Ideal for preparing pipeline inputs. **Example prompts:** - "Create a CSV sample sheet for the RNA-seq runs in GSE147507" - "Generate a TSV file with download URLs for these SRR accessions" - "Make a sample sheet I can use with nf-core/rnaseq" ## Typical workflow 1. **Search** for datasets using `sra_search_ncbi` or `sra_search_ebi` 2. **Explore** a study with `sra_fetch_geo_study` to get overview 3. **List** detailed run information with `sra_list_runs_detailed` 4. **Group** by assay type with `sra_group_by_assay` for multi-assay studies 5. **Download** URLs with `sra_fetch_download_urls` or create a sample sheet with `sra_create_samples_sheet` ## Example session ``` User: Find RNA-seq studies for human liver cancer AI: [Uses sra_search_ncbi to find relevant studies] Found 150 results. Top study: GSE147507 - "COVID-19 and liver damage" User: Tell me more about GSE147507 AI: [Uses sra_fetch_geo_study] Study: GSE147507 Title: Human liver organoids to model COVID-19 Organism: Homo sapiens Samples: 48 Linked SRA: SRP253951 User: What types of assays are in this study? AI: [Uses sra_list_runs_detailed then sra_group_by_assay] - RNA-Seq:PAIRED: 36 runs (450 GB) - ATAC-Seq:PAIRED: 12 runs (120 GB) User: Create a sample sheet for just the RNA-seq data AI: [Uses sra_create_samples_sheet with RNA-seq runs] Generated samples.csv with 36 samples Download URL: https://storage.example.com/samples.csv ``` --- ## Commands Use the `--help` or `-h` option to list available commands and options: ```shell-session seqerakit --help ``` ### Input Seqerakit supports input through paths to YAML configuration files or directly from standard input (`stdin`). - Using file path: ```shell-session seqerakit file.yaml ``` - Using `stdin`: ```shell-session cat file.yaml | seqerakit - ``` See [YAML configuration options](./yaml-configuration#yaml-configuration-options) for guidance on formatting your input YAML files. ### Dryrun Confirm that your configuration and command are correct before creating resources in your Seqera account, particularly when automating the end-to-end creation of multiple entities at once. To print the commands that would be executed with Platform CLI when using a YAML file, run your `seqerakit` command with the `--dryrun` option: ```shell-session seqerakit file.yaml --dryrun ``` ### Specify targets When using a YAML file as an input that defines multiple resources, use the `--targets` option to specify which resources to create. This option accepts a comma-separated list of resource names. Supported resource names include: - `actions` - `compute-envs` - `credentials` - `datasets` - `labels` - `launch` - `members` - `organizations` - `participants` - `pipelines` - `secrets` - `teams` - `workspaces` For example, given a `test.yaml` file that defines the following resources: ```yaml workspaces: - name: 'workspace-1' organization: 'seqerakit' ... compute-envs: - name: 'compute-env' type: 'aws-batch forge' workspace: 'seqerakit/workspace-1' ... pipelines: - name: 'hello-world' url: 'https://github.com/nextflow-io/hello' workspace: 'seqerakit/workspace-1' compute-env: 'compute-env' ... ``` You can target the creation of `pipelines` only by running: ```shell-session seqerakit test.yaml --targets pipelines ``` This command will create only the pipelines defined in the YAML file and ignore `workspaces` and `compute-envs`. To create both workspaces and pipelines, run: ```shell-session seqerakit test.yaml --targets workspaces,pipelines ``` ### Delete resources Instead of adding or creating resources, specify the `--delete` option to recursively delete resources in your YAML file: ```shell-session seqerakit file.yaml --delete ``` For example, if you have a `file.yaml` that defines an organization, workspace, team, credentials, and compute environment that have already been created, run `seqerakit file.yaml --delete` to recursively delete the same resources. ### Use `tw`-specific CLI options Specify `tw`-specific CLI options with the `--cli=` option: ```shell-session seqerakit file.yaml --cli="--arg1 --arg2" ``` See [CLI commands](https://docs.seqera.io/platform-cli/commands-reference) or run `tw -h` for the full list of options. :::note The `--verbose` option for `tw` CLI is currently not supported in `seqerakit` commands. ::: #### Example: HTTP-only connections The Platform CLI expects to connect to a Seqera instance that is secured by a TLS certificate. If your Seqera Enterprise instance does not present a certificate, you must run your `tw` commands with the `--insecure` option. To use `tw`-specific CLI options such as `--insecure`, use the `--cli=` option, followed by the options to use enclosed in double quotes: ```shell-session seqerakit file.yaml --cli="--insecure" ``` --- ## Installation(Seqerakit) Seqerakit is a Python wrapper that sets [Platform CLI](https://docs.seqera.io/platform-cli) command options using YAML configuration files. Individual commands and configuration parameters can be chained together to automate the end-to-end creation of all Seqera Platform entities. As an extension of the Platform CLI, Seqerakit enables: - **Infrastructure as code**: Users manage and provision their infrastructure from the command line. - **Simple configuration**: All Platform CLI command-line options can be defined in simple YAML format. - **Automation**: End-to-end creation of Seqera entities, from adding an organization to launching pipelines. ### Installation Seqerakit has three dependencies: 1. [Seqera Platform CLI (`>=0.10.1`)](https://github.com/seqeralabs/tower-cli/releases) 2. [Python (`>=3.8`)](https://www.python.org/downloads/) 3. [PyYAML](https://pypi.org/project/PyYAML/) #### Pip If you already have [Platform CLI](https://docs.seqera.io/platform-cli/installation) and Python installed on your system, install Seqerakit directly from [PyPI](https://pypi.org/project/seqerakit/): ```bash pip install seqerakit ``` Overwrite an existing installation to use the latest version: ```bash pip install --upgrade --force-reinstall seqerakit ``` #### Conda To install `seqerakit` and its dependencies via Conda, first configure the correct channels: ```bash conda config --add channels bioconda conda config --add channels conda-forge conda config --set channel_priority strict ``` Then create a conda environment with `seqerakit` installed: ```bash conda env create -n seqerakit seqerakit conda activate seqerakit ``` #### Local development installation Install the development branch of `seqerakit` on your local machine to test the latest features and updates: 1. You must have [Python](https://www.python.org/downloads/) and [Git](https://git-scm.com/downloads) installed on your system. 1. To install directly from pip: ```bash pip install git+https://github.com/seqeralabs/seqera-kit.git@dev ``` 1. Alternatively, clone the repository locally and install manually: ```bash git clone https://github.com/seqeralabs/seqera-kit.git cd seqera-kit git checkout dev pip install . ``` 1. Verify your installation: ```bash pip show seqerakit ``` ### Configuration Create a [Seqera](https://cloud.seqera.io/tokens) access token via **Your Tokens** in the user menu. Seqerakit reads your access token from the `TOWER_ACCESS_TOKEN` environment variable: ```bash export TOWER_ACCESS_TOKEN= ``` For Enterprise installations, specify the custom API endpoint used to connect to Seqera. Export the API endpoint environment variable: ```bash export TOWER_API_ENDPOINT= ``` By default, this is set to `https://api.cloud.seqera.io` to connect to Seqera Cloud. ### Usage To confirm the installation of `seqerakit`, configuration of the Platform CLI, and connection to Seqera is working as expected, run this command: ```bash seqerakit --info ``` This runs the `tw info` command under the hood. Use `--version` or `-v` to retrieve the current version of your `seqerakit` installation: ```bash seqerakit --version ``` Use the `--help` or `-h` option to list the available commands and their associated options: ```bash seqerakit --help ``` See [Commands](./commands) for detailed instructions to use Seqerakit. --- ## Templates Customize YAML configuration templates to use in `seqerakit` commands to create, update, or delete Seqera resources. Create or delete multiple resources with a single command by combining them into a single configuration file. To use the templates on this page: 1. Copy the template text or download the YAML files you need. 1. Edit the values to specify your resource details, and save as a `.yaml` file. 1. Specify the YAML template file in your `seqerakit` commands: - To create the resources specified in the file: ```shell-session seqerakit file.yaml ``` - To delete the existing resources specified in the file: ```shell-session seqerakit file.yaml --delete ``` :::info See [Specify targets](./commands#specify-targets) to create or delete only selected resources from configuration templates that contain multiple resource entries. ::: See [End-to-end example](#end-to-end-example) for a template that contains examples of all Seqera resources that can be created with Seqerakit. ### Administration Manage organizations, organization members, workspaces, teams, and participants. #### Organizations Add or delete organizations. {Organizations} [Download organizations.yaml](./templates/organizations.yaml) #### Members Add or delete organization members. {Members} [Download members.yaml](./templates/members.yaml) #### Workspaces Add or delete workspaces. {Workspaces} [Download workspaces.yaml](./templates/workspaces.yaml) #### Teams Add or delete teams. {Teams} [Download teams.yaml](./templates/teams.yaml) #### Participants Add or delete participants in workspaces and teams. {Participants} [Download participants.yaml](./templates/participants.yaml) ### Credentials Add or delete compute environment, Git, and container registry credentials in workspaces. {Credentials} [Download credentials.yaml](./templates/credentials.yaml) ### Compute environments Add or delete compute environments. {ComputeEnvironments} [Download compute-envs.yaml](./templates/compute-envs.yaml) ### Pipelines Add or delete pipelines in workspace Launchpads. {Pipelines} [Download pipelines.yaml](./templates/pipelines.yaml) ### Launch Launch a Nextflow pipeline. {Launch} [Download launch.yaml](./templates/launch.yaml) ### Datasets Add or delete workspace datasets for pipeline input data. {Datasets} [Download datasets.yaml](./templates/datasets.yaml) ### Labels Add or delete labels and resource labels to apply to workspace compute environments, pipelines, and runs. {Labels} [Download labels.yaml](./templates/labels.yaml) ### Secrets Add or delete user and workspace secrets. {Secrets} [Download secrets.yaml](./templates/secrets.yaml) ### Actions Add or delete pipeline actions. {Actions} [Download actions.yaml](./templates/actions.yaml) ### End-to-end example A template to create the following resources: - An organization - A workspace - A team - Participants - Credentials - Secrets - Compute environments - Datasets - Pipelines The template also contains `launch` entries to launch saved pipelines. {EndToEnd} [Download seqerakit-e2e.yaml](./templates/seqerakit-e2e.yaml) --- ## YAML configuration Seqerakit supports the creation and deletion of the following Seqera Platform resources, listed here with their respective Platform CLI resource names: - Pipeline actions: `actions` - Compute environments: `compute-envs` - Credentials: `credentials` - Datasets: `datasets` - Labels (including resource labels): `labels` - Pipeline launch: `launch` - Organization members: `members` - Organizations: `organizations` - Workspace and team participants: `participants` - Pipelines: `pipelines` - Pipeline secrets: `secrets` - Teams: `teams` - Workspaces: `workspaces` To determine the options to provide as definitions in your YAML file, run the Platform CLI help command for the resource you want to create. 1. Retrieve CLI options: Obtain a list of available CLI options for defining your YAML file with the Platform CLI `help` command. For example, to add a pipeline to your workspace, view the options for adding a pipeline: ```shell-session tw pipelines add -h ``` ```shell-session Usage: tw pipelines add [OPTIONS] PIPELINE_URL Add a workspace pipeline. Parameters: * PIPELINE_URL Nextflow pipeline URL. Options: * -n, --name= Pipeline name. -w, --workspace= Workspace numeric identifier (TOWER_WORKSPACE_ID as default) or workspace reference as OrganizationName/WorkspaceName -d, --description= Pipeline description. --labels=[,...] List of labels seperated by coma. -c, --compute-env= Compute environment name. --work-dir= Path where the pipeline scratch data is stored. -p, --profile=[,...] Comma-separated list of one or more configuration profile names you want to use for this pipeline execution. --params-file= Pipeline parameters in either JSON or YML format. --revision= A valid repository commit Id, tag or branch name. ... ``` 1. Define key-value pairs in YAML: Translate each CLI option into a key-value pair in the YAML file. The structure of your YAML file should reflect the hierarchy and format of the CLI options. For example: ```yaml pipelines: - name: 'my_first_pipeline' url: 'https://github.com/username/my_pipeline' workspace: 'my_organization/my_workspace' description: 'My test pipeline' labels: 'yeast,test_data' compute-env: 'my_compute_environment' work-dir: 's3://my_bucket' profile: 'test' params-file: '/path/to/params.yaml' revision: '1.0' ``` In this example: - The keys (`name`, `url`, `workspace`, and so forth) are the keys derived from the CLI options. - The corresponding values are user-defined. #### Best practices - The indentation and structure of the YAML file must be correct — YAML is sensitive to formatting. - Use quotes around strings that contain special characters or spaces. - To list multiple values (such as multiple `labels`, `instance-types`, or `allow-buckets`), separate values with commas. This is shown with `labels` in the preceding example. - For complex configurations, see [Templates](./templates). ### Templates See [Templates](./templates) for YAML file templates for each of the entities that can be created in Seqera. ### YAML Configuration Options Some options handled specially by `seqerakit` or not exposed as `tw` CLI options can be provided in your YAML configuration file. #### Pipeline parameters using `params` and `params-file` To specify pipeline parameters, use `params:` to specify a list of parameters or `params-file:` to point to a parameters file. For example, to specify pipeline parameters within your YAML: ```yaml params: outdir: 's3://path/to/outdir' fasta: 's3://path/to/reference.fasta' ``` To specify a file containing pipeline parameters: ```yaml params-file: '/path/to/my/parameters.yaml' ``` Or provide both: ```yaml params-file: '/path/to/my/parameters.yaml' params: outdir: 's3://path/to/outdir' fasta: 's3://path/to/reference.fasta' ``` :::note If duplicate parameters are provided, the parameters provided as key-value pairs inside the `params` nested dictionary of the YAML file will take precedence **over** values in the `params-file`. ::: #### Overwrite For every entity defined in your YAML file, specify `overwrite: True` to overwrite any existing Seqera entities of the same name. Seqerakit will first check to see if the name of the entity exists. If so, it will invoke a `tw delete` command before attempting to create it based on the options defined in the YAML file. ```shell-session DEBUG:root: Overwrite is set to 'True' for organizations DEBUG:root: Running command: tw -o json organizations list DEBUG:root: The attempted organizations resource already exists. Overwriting. DEBUG:root: Running command: tw organizations delete --name $SEQERA_ORGANIZATION_NAME DEBUG:root: Running command: tw organizations add --name $SEQERA_ORGANIZATION_NAME --full-name $SEQERA_ORGANIZATION_NAME --description 'Example of an organization' ``` #### Specify JSON configuration files with `file-path` The Platform CLI allows the export and import of entities through JSON configuration files for pipelines and compute environments. To use these files to add a pipeline or compute environment to a workspace, use the `file-path` key to specify a path to a JSON configuration file. An example of the `file-path` option is provided in the [compute-envs.yaml](./templates/compute-envs.yaml) template: ```yaml compute-envs: - name: 'my_aws_compute_environment' # required workspace: 'my_organization/my_workspace' # required credentials: 'my_aws_credentials' # required wait: 'AVAILABLE' # optional file-path: './compute-envs/my_aws_compute_environment.json' # required overwrite: True ``` --- ## IdP claim mapping For IdP-delegated teams to evaluate correctly at login, tokens that reach Seqera must include a `groups` claim. Cloud Pro authenticates through Auth0, so two layers are involved: - Your **identity provider** emits the group membership for each user. - The **Auth0 connection** that fronts your SSO passes that group data through to Seqera as a `groups` claim. Configure the group emission at the IdP. The Auth0 self-service SSO connection passes the claim through to Seqera. :::caution Keep the claim configuration stable after you delegate teams. If the `groups` claim stops reaching Seqera — for example, the Auth0 Post-Login Action is removed, or the IdP claim mapping is deleted — all delegated team memberships are revoked at next login. A malformed claim (not a list of strings) is ignored, and existing memberships are preserved. ::: ## Identity provider configuration Configure your identity provider to emit a `groups` claim so team membership flows into the catalog. The steps differ by provider. ### Okta In Okta, add a custom claim to the authorization server that backs your application: 1. In the Okta administrator console, open **Security**, then **API**, then **Authorization Servers**. 2. Select the authorization server backing your application (typically `default`). 3. Open **Claims**, then **Add claim**. 4. Set: - **Name**: `groups` - **Include in token type**: **ID Token** (and **Access Token** if you use access tokens for downstream services) - **Value type**: **Groups** - **Filter**: Match the groups you want exposed (`Matches regex .*` to expose all of them). 5. Select **Save**. ### Entra ID Entra ID requires an app-registration change. Pay attention to the format Entra emits. 1. In the Azure portal, open the app registration that backs your connection. 2. Open **Token configuration**, then **Add groups claim**. 3. Select the group types to emit (typically **Security groups**). 4. Under **Customize token properties by type**, choose whether to emit **Group ID** (object GUIDs) or **sAMAccountName** (display names where supported). 5. In Entra ID's **Token Preview**, confirm that a sample sign-in includes the `groups` claim. :::caution With **Group ID** selected, Entra ID emits group object GUIDs. You have two options: - Use the GUID values as the catalog identifier and the **IdP Group** field on each team. This works but makes the catalog harder to read. - Configure Entra ID to emit display names instead. Set **sAMAccountName** as the source where supported, or post-process via a custom claims policy. The GUID and the display name don't both flow at the same time. Pick one approach for your tenant and use it consistently. ::: ## Verify the mapping After saving the IdP changes, confirm the claim reaches Platform: 1. Sign in to Platform as a test user via SSO. 2. Confirm the user is added to the expected delegated teams. If they aren't, the `groups` claim either isn't reaching Seqera or doesn't match the catalog identifiers. :::caution If a test user's token carries no `groups` claim, or the claim is empty, all of their delegated team memberships are revoked at that login. Verify the mapping with a test user before you delegate production teams. ::: For sign-in and claim problems, see [SSO troubleshooting](../../troubleshooting_and_faqs/sso_troubleshooting). --- ## Manage your IdP group catalog Platform maintains a per-organization catalog of identity provider (IdP) groups. Groups appear in the catalog as soon as they're synced from the IdP or added manually. They don't depend on any user having signed in. Choose the path that fits your IdP: | IdP | Recommended path | Setup guide | |-----|------------------|-------------| | Okta | SCIM push | [SCIM provisioning with Okta](./scim-okta) | | Entra ID | SCIM push | [SCIM provisioning with Entra ID](./scim-entra-id) | :::info[Other identity providers] Seqera supports SCIM provisioning for Okta and Microsoft Entra ID. With these providers, group membership syncs automatically, including lifecycle events (joiners, movers, leavers). Other OIDC or SAML identity providers can authenticate users through Auth0, but group membership doesn't sync automatically. An organization owner must update memberships in Seqera as users join, move, or leave. If you use Google Workspace, Keycloak, Ping, OneLogin, or another OIDC/SAML provider and want to delegate team membership, contact your Seqera account team to discuss your setup. ::: ## SCIM push If your IdP supports SCIM 2.0 group provisioning, Platform exposes a per-organization SCIM endpoint that the IdP can push to. Create, rename, and delete events sync automatically without administrator intervention. To set up SCIM: 1. In Platform, open **Organization settings > Group mapping**. 2. Copy the **SCIM endpoint URL** and the generated **bearer token**. 3. Configure these values in your IdP's SCIM provisioning settings. 4. Trigger an initial sync from the IdP, or wait until the IdP performs a scheduled sync. After the sync completes, the catalog displays every group your IdP shared, and the **Linked team** drop-down on **Group mapping** is populated. :::caution Treat the SCIM bearer token like a password. It grants write access to your organization's group catalog. If the token is compromised, rotate it immediately by generating a new token in the **Group mapping** panel. The previous token is revoked when the new token is issued. ::: ## Manual entry To add a group manually: 1. In Platform, open **Organization settings > Group mapping**. 2. Select **Add group manually**. 3. Enter the group identifier exactly as it appears in your IdP's `groups` claim. 4. Select **Save**. To delete a manually-entered group, select **Delete** on its row. If any delegated team references the group, its members are immediately purged. :::info A manually-entered group is automatically promoted to SCIM-managed if your IdP later pushes the same group via SCIM. The promotion happens in place. The catalog row is reused, and any delegated teams that reference it continue to work without interruption. After promotion, the row's lifecycle is fully driven by SCIM, and the manual **Delete** action is no longer available. The row is removed when your IdP issues a SCIM `DELETE`. ::: ## Remove a catalog entry When a group is removed from the catalog — by SCIM `DELETE`, manual deletion, or IdP-side rename detection: - The catalog row is removed. - Every delegated team that referenced the group has its delegation-driven members purged. The affected teams remain in place with empty membership and an orphaned-team warning. Other team settings (name, workspace assignments, role) are preserved. - To reset an affected team's membership, set its **IdP Group** field to a different group, or clear the field to convert the team back to manual management. --- ## SCIM provisioning with Entra ID Configure Microsoft Entra ID (formerly Azure AD) to push your tenant's groups to Platform over SCIM 2.0. After provisioning is enabled, the groups you assign to your Seqera application appear in Platform's IdP group catalog and stay in sync with renames, additions, and deletions. :::info[**Prerequisites**]{#prerequisites} You need the following: - An active [SSO connection](../../single-sign-on) for your organization with Entra ID as the IdP. - Organization owner access to your Platform organization. - Administrator access to your Entra ID tenant with permission to manage application provisioning. ::: ## Get the Platform SCIM connection details To get Platform SCIM connection details: 1. In Platform, open **Organization settings > Group mapping**. 2. Copy the **SCIM endpoint URL** shown in the panel. 3. Select **Generate token** to issue a SCIM bearer token. Copy your bearer token immediately. You can't view it again after closing the dialog. :::caution The bearer token grants write access to your group catalog. Store it in a secrets manager and rotate it on a schedule. To rotate, generate a new token in Seqera and update Entra ID's configuration. The previous token is revoked when the new token is issued. ::: ## Enable provisioning in Entra ID To enable provisioning in Entra ID: 1. Sign in to the Azure portal and open **Entra ID**, then **Enterprise applications**. 2. Select the application that fronts your Platform SSO connection. 3. Open **Provisioning** and select **Get started**. 4. Set **Provisioning Mode** to **Automatic**. 5. Under **Admin Credentials**, provide: - **Tenant URL**: The Platform SCIM endpoint URL from the previous section. - **Secret Token**: The Platform bearer token from the previous section. 6. Select **Test Connection**. Entra ID should report success. 7. Select **Save**. ## Scope and start provisioning To scope and start provisioning: 1. With **Provisioning** still open, expand **Settings**. 2. Set **Scope** to **Sync only assigned users and groups**. 3. Save, then set **Provisioning Status** to **On**. 4. Return to the application's **Users and groups** tab and assign the groups you want Platform to receive. Entra ID runs an initial cycle within minutes and then syncs incrementally every ~40 minutes. ## Group display names vs. object IDs :::caution By default, Entra ID emits group **object GUIDs** in the `groups` claim, not display names. There are two options: - **Recommended**: Configure Entra ID to emit display names. In the application's **Token configuration**, add a **groups claim** and select **sAMAccountName** as the source where supported, or use a custom claims policy. This makes catalog entries and audit trail entries human-readable. - **Alternative**: Accept the default GUID emission. Use the GUID as the **IdP Group** value on each team. This works but makes the catalog harder to read. Pick one approach for your tenant and use it consistently. The GUID and the display name don't both flow at the same time. ::: ## Verify in Platform To verify in Platform: 1. In Platform, open **Organization settings > Group mapping**. 2. Select **Refresh**. The assigned Entra ID groups should appear in the catalog list after the first provisioning cycle. 3. The **Linked team** drop-down is now populated with the synced groups. If groups don't appear, open the **Provisioning logs** for the application in Entra ID and review any failed actions. ## Rename and delete behavior Renames and deletes propagate automatically through SCIM: - **Rename**: The next provisioning cycle updates the catalog row's display name. Delegated teams that reference the group continue to work without interruption. - **Delete**: Entra ID issues a SCIM `DELETE` for the group, or removes the assignment from the enterprise application. Seqera removes the catalog row and synchronously purges members from any delegated team that referenced it. Affected teams remain in place with empty membership and an orphaned-team warning. For provisioning problems, see [SSO troubleshooting](../../../troubleshooting_and_faqs/sso_troubleshooting). --- ## SCIM provisioning with Okta Configure Okta to push your organization's groups to Platform over SCIM 2.0. After provisioning is enabled, your Okta group directory appears in Seqera's IdP group catalog and stays in sync with renames, additions, and deletions. :::info[**Prerequisites**]{#prerequisites} You need the following: - An active [SSO connection](../../single-sign-on) for your organization with Okta as the IdP. - Organization owner access to your Platform organization. - Administrator access to your Okta tenant. ::: ## Get the Seqera SCIM connection details To get the Seqera SCIM connection details: 1. In Platform, open **Organization settings > Group mapping**. 2. Copy the **SCIM endpoint URL** shown in the panel. 3. Select **Generate token** to issue a SCIM bearer token. Copy it immediately. You can't view it again after closing the dialog. :::caution The bearer token grants write access to your group catalog. Store it in a secrets manager and rotate it on a schedule. To rotate, generate a new token in Seqera and update Okta's configuration. The previous token is revoked when the new token is issued. ::: ## Enable provisioning in Okta To enable provisioning in Okta: 1. Sign in to your Okta administrator console. 2. Open **Applications**, then select the application that fronts your Seqera SSO connection. 3. Open the **Provisioning** tab and select **Configure API integration**. 4. Select **Enable API integration** and provide: - **Base URL**: The Platform SCIM endpoint URL from the previous section, with `/Groups` removed (Okta appends the resource path). - **API token**: The Platform bearer token from the previous section. 5. Select **Test API Credentials**. Okta should report a successful connection. 6. Select **Save**. ## Enable group push To enable group push: 1. With the application still open, switch to the **Push Groups** tab. 2. Select **Push Groups**, then **Find groups by name** (or **By rule** for dynamic group sets). 3. Select the Okta groups you want available in Platform. 4. Confirm the push. Okta sends an initial provisioning batch. ## Verify in Platform To verify in Platform: 1. In Platform, open **Organization settings > Group mapping**. 2. Select **Refresh**. The pushed Okta groups should appear in the catalog list within a few seconds. 3. The **Linked team** drop-down is now populated with the synced groups. If groups don't appear, check the **Push Groups** status column in Okta for error details, and confirm that the **Provisioning** tab shows **Push Groups: ON**. ## Rename and delete behavior Renames and deletes propagate automatically: - **Rename**: The next SCIM push updates the catalog row's display name. Delegated teams that reference the group continue to work without interruption. - **Delete**: Okta issues a SCIM `DELETE` for the group. Seqera removes the catalog row and synchronously purges members from any delegated team that referenced it. Affected teams remain in place with empty membership and an orphaned-team warning. For provisioning problems, see [SSO troubleshooting](../../../troubleshooting_and_faqs/sso_troubleshooting). --- ## IdP delegation overview With IdP delegation, you map a Seqera team to a group in your identity provider (IdP). After you delegate a team, the IdP becomes the sole authority for that team's membership. Every time a user signs in through SSO, Seqera reads the `groups` claim from their token and updates the user's delegated-team memberships to match. IdP delegation requires an active SSO connection for your organization. See [Single sign-on (SSO)](../single-sign-on). :::caution After you delegate a team, the IdP is the sole authority for its membership. If the `groups` claim stops reaching Seqera — for example, the Auth0 Post-Login Action is removed, or the IdP claim mapping is deleted — all delegated team memberships are revoked at next login. Verify the claim mapping works before you delegate teams. See [What happens at login](#what-happens-at-login). ::: ## How it works Delegation has three components that an organization owner configures once. ### The IdP group catalog Seqera maintains a per-organization catalog of IdP groups. The catalog populates the **IdP Group** drop-down on the team mapping page. Groups appear in the catalog as soon as they're synced or entered, before any user has signed in. The catalog is populated in one of two ways: - **SCIM 2.0 push**: Your IdP pushes its group directory to your organization's SCIM endpoint. Used with Okta and Entra ID. - **Manual entry**: For IdPs that don't support SCIM group sync, an organization owner enters group identifiers in the catalog UI. A manually-entered group is automatically promoted to SCIM-managed if your IdP later pushes the same group. See [Manage your IdP group catalog](./group-catalog/overview). ### The `groups` claim At login, Seqera reads the user's IdP claims to decide which delegated teams they belong to. The `groups` claim must reach Seqera and must contain the same group identifiers as your catalog. Cloud Pro authenticates through Auth0. Auth0 sits between your IdP and Seqera, and maps the `groups` claim at the connection rather than reading it from the IdP token directly. See [IdP claim mapping](./claim-mapping). ### The team's `IdP Group` field When an organization owner sets the **IdP Group** field on a team, the team becomes delegated. Delegation has the following effects: - The team is labeled **Managed in IdP** in the teams list. - The team's member list displays a banner indicating that your identity provider manages the team's membership, and that members removed from the IdP group lose access at their next login. - The **Add member** and **Remove member** controls are hidden. - The team can't be deleted until the **IdP Group** field is cleared. - The team's name, description, avatar, and workspace assignments remain editable. The same IdP group can only be assigned to a single team, and each team can reference exactly one IdP group. ## What happens at login Cloud Pro tokens carry an `org_id` claim that scopes evaluation to a single organization. On every SSO login, Seqera evaluates each delegated team in that organization against the user's `groups` claim: - **Match found**: The user is added to the team if they aren't already a member. - **No match and the user was previously a delegation-driven member**: The user is removed from the team. - **No match and the user was never a delegation-driven member**: No change. - **Claim absent or empty**: All of the user's delegated team memberships in the organization are revoked. Major IdPs, including Okta and Entra ID, omit the `groups` claim entirely when a user belongs to no groups. An absent claim is treated the same as an empty one. - **Claim malformed** (not a list, or containing non-string values): No membership changes are applied. Existing memberships are preserved as a safeguard against IdP or claim-mapping errors. Login evaluation never changes manual assignments to non-delegated teams. Users added manually to a team with no **IdP Group** value keep their membership regardless of their IdP claims. ## Delegate a team to an IdP group You delegate a team from the team's settings by setting its **IdP Group** field to a group from the catalog. The team is then labeled **Managed in IdP**, and its member list is controlled by the IdP from the next SSO login onward. For the full procedure — prerequisites, what changes when a team is delegated, and how to stop delegating — see [Delegate a team to an IdP group](../../orgs-and-teams/teams#delegate-a-team-to-an-idp-group). ## Audit trail Delegation activity is recorded in your organization's audit trail: - Setting, changing, or clearing the **IdP Group** field on a team produces a `team_updated` event with the previous and new value of `idpGroup`. - Each delegation-driven membership change at login produces a `team_member_added` or `team_member_removed` event. - Group catalog operations produce `idp_group_created`, `idp_group_updated`, and `idp_group_deleted` events so you can correlate catalog changes with downstream membership changes. SCIM-originated entries (operations performed by your IdP's provisioning agent against your organization's SCIM endpoint) are attributed to a **System** operator rather than to a named administrator. The provisioning agent authenticates with a SCIM bearer token, not as a named user. To correlate a SCIM event with a specific administrator action, match by `displayName` and timestamp against your IdP's provisioning logs. ## Set up delegation Complete these steps in order: 1. [Configure single sign-on](../single-sign-on) for your organization if you haven't already. 2. [Populate the IdP group catalog](./group-catalog/overview). Choose SCIM push or manual entry depending on your IdP. 3. [Configure the `groups` claim](./claim-mapping) so it reaches Seqera at login. 4. [Delegate a team to an IdP group](../../orgs-and-teams/teams#delegate-a-team-to-an-idp-group). --- ## Single sign-on (SSO) With single sign-on (SSO), a Seqera Platform Cloud organization authenticates through its corporate identity provider (IdP). After SSO is enabled, users with a matching email domain are routed to the organization's IdP when they sign in. SSO is available for Cloud Pro organizations and uses Auth0 self-service SSO to connect supported SAML and OpenID Connect (OIDC) identity providers. :::info[**Prerequisites**] You need the following: - A [Cloud Pro](https://seqera.io/pricing/) organization. - The organization owner role. See [User roles](../orgs-and-teams/roles). - An email domain that isn't already claimed by another organization. - Organization members and collaborators resolved to the claimed domain. See [Prepare users before setup](#prepare-users-before-setup). - Administrative access to your organization's IdP. Depending on the provider, you need values such as a client ID, client secret, metadata URL, issuer URL, or signing certificate. ::: :::caution After SSO is enabled, users on the claimed domain authenticate through the configured IdP. If the IdP is unavailable, those users can't fall back to another sign-in method. ::: ## Prepare users before setup Seqera blocks domain claiming when the organization has members with email addresses outside the claimed domain or existing workspace collaborators. The setup flow lists the affected users. Before you configure SSO: - Remove organization members whose email addresses don't use the claimed domain, or update their accounts to use addresses on the claimed domain. - Remove all workspace collaborators. If external users need continued access, add them to your IdP as guest or external accounts so they can sign in through SSO and be provisioned as organization members. - Add any collaborator who already uses the claimed domain as an organization member before you claim the domain. ## Configure SSO 1. Open your organization, then select **Settings**. 2. Select the option to configure SSO and enter the email domain to claim. 3. Select **Generate setup URL**. 4. Open the setup URL to start the Auth0 self-service SSO wizard. 5. In the wizard, select your identity provider and complete the provider-specific configuration. 6. Run the connection test in the Auth0 wizard to confirm that authentication works. Seqera validates the configured Auth0 connection when you enable SSO. If the domain configured in Auth0 doesn't match the domain claimed in Seqera, activation fails. Correct the Auth0 configuration or delete the SSO configuration and create a new one with the correct domain. The setup link expires after five days. After an IdP administrator opens the Auth0 access ticket, the ticket expires after five hours. If the ticket expires before setup or verification is complete, refresh the URL from the SSO settings page. After the connection test succeeds, verify your domain before you enable SSO. ## Verify your domain Before you enable SSO, prove that you control the domain you claimed. The Auth0 wizard shows provider-specific instructions, but domain verification works the same way for every identity provider. 1. In the **Domain Configuration** step of the Auth0 self-service wizard, copy the **TXT Record Name** and **Record Value**. 2. In your DNS provider, create a TXT record with those exact values. 3. Wait for the DNS record to propagate, then for Auth0 to verify the domain. Verification can take up to 48 hours. 4. After Auth0 verifies the domain, return to Seqera and select **Enable SSO**. ## Identity provider setup The Auth0 self-service SSO wizard provides provider-specific instructions. Follow the wizard for the exact values and configuration steps required by your IdP. For the current list of supported providers, see [Auth0 Self-Service Enterprise Configuration](https://auth0.com/docs/authenticate/enterprise-connections/self-service-enterprise-config). Configure user or group access in your IdP before you run the connection test in Auth0. ## Sign-in behavior When an organization has active SSO: - The sign-in flow starts with an email-first step. - Users whose email domain matches an active SSO connection are redirected to their corporate IdP. - Users whose email domain does not match an SSO connection continue with the standard Seqera sign-in options. - Users who previously signed in with a social provider and have a matching SSO domain are redirected to the corporate IdP instead. ## User provisioning and account linking When a user signs in through an active SSO connection for the first time: - Existing Auth0 accounts with the same email are linked to the SSO identity instead of creating a duplicate user. - Users who first access Seqera after SSO is active are created through the SSO sign-in flow and automatically added to the organization as members. - Existing organization memberships, workspace roles, ownership, and run history are preserved for linked accounts. - Name and profile fields are populated from the IdP when those attributes are available. Newly provisioned users receive the lowest organization-level role by default. Organization owners can then promote them or grant workspace-level access. SSO applies only to users with the claimed email domain. External users who need workspace access must be added to the organization's IdP as guest or external accounts, provisioned as organization members through SSO, and granted the appropriate workspace access. Active SSO blocks new workspace collaborator assignments. ## Manage an existing connection Organization owners can manage the SSO connection from **Organization settings**: - Disable SSO enforcement without deleting the existing configuration. - Re-enable a previously disabled connection if no other organization has activated the same domain. - Generate an Auth0 connection management link for an active connection to make IdP configuration changes such as credential rotation. - Delete the connection and release the claimed domain. :::note You can't change the claimed domain through the edit flow. To move SSO to a different domain, delete the existing connection and create a new one. For setup, sign-in, and account-linking problems, see [SSO troubleshooting](../troubleshooting_and_faqs/sso_troubleshooting). ::: ## Next steps After SSO is active, you can map Seqera teams to groups in your IdP so team membership is controlled at the IdP and evaluated on every login. See [IdP delegation](./idp-delegation/overview). --- ## Custom container template :::info[**Prerequisites**] You need the following: - Valid credentials for accessing cloud storage resources - **Maintain** role permissions or above - A compute environment with sufficient resources (scale based on data volume) - [Data Explorer](../data/data-explorer) enabled ::: Select **Custom container template** and provide your own template (see [Custom container template image][custom-image]). This option doesn't support **Install Conda packages**. For ready-to-use examples, see [Example custom Studios][example-studios]. Configure the following fields: - **Container identifier**: The template for the container. - **Resource labels**: Any [resource label](../labels/overview) already defined for the compute environment is added by default. Add or remove custom resource labels as needed. - **Environment variables**: Environment variables for the session. The session inherits and displays all variables from the selected compute environment. Add session-specific variables as needed. Session-level variables take precedence. To override an inherited variable, define the same key with a different value. - **Studio name**: The name for the Studio. - **Description** (optional): A description for the Studio. - **Collaboration**: Session access permissions. By default, all workspace users with the launch role and above can connect to the session. Toggle **Private** on to restrict connections to the session creator only. :::note When private, workspace administrators can still start, stop, and delete sessions, but cannot connect to them. ::: - **Session lifespan**: The duration the session remains active. Available options depend on your workspace settings: - **Stop the session automatically after a predefined period of time**: An automatic timeout for the session (minimum: 1 hour; maximum: 120 hours; default: 8 hours). If a workspace-level session lifespan is configured, this field cannot be edited. Changes apply only to the current session and revert to default values after the session stops. - **Keep the session running:** Continuous session operation until manually stopped or an error terminates it. The session continues consuming compute resources until stopped. ### Mount data Mount data to make them accessible in your session: 1. Select **Mount data** to open the data selection modal. 1. Choose the data to mount. 1. Select **Mount data** to confirm. Once the Studio session is running, mounted data are accessible at `/workspace/data/` using the [Fusion file system](https://docs.seqera.io/fusion). Data doesn't need to match the compute environment region, though cross-region data transfer (ingress and egress) may increase costs. Sessions have read-only access to mounted data by default. Enable write permissions by adding AWS S3 buckets as **Allowed S3 Buckets** in your compute environment configuration. Files uploaded to a mounted bucket during an active session may not be immediately available within that session. See [Running session does not show new data in object storage](../troubleshooting_and_faqs/studios_troubleshooting#running-session-does-not-show-new-data-in-object-storage) for more information. ## Save and start 1. Review the configuration. 1. Save your configuration: - To save and immediately start your Studio, select **Add and start**. - To save but not immediately start your Studio, select **Add only**. Studios you create are listed on the Studios landing page with a status of **stopped** or **starting**. Select a Studio to inspect its configuration details. {/* links */} [contact]: https://support.seqera.io/ [aws-cloud]: ../compute-envs/aws-cloud [aws-gpu]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html [aws-batch]: ../compute-envs/aws-batch [custom-envs]: ./custom-envs [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./container-images [example-studios]: ./example-studios --- ## Import from a Git repository :::info[**Prerequisites**] You need the following: - **Maintain** role permissions or above - A compute environment with sufficient resources (scale based on data volume) - [Data Explorer](../data/data-explorer) enabled - Git credentials configured in your workspace - A Git repository containing a `.seqera` folder ::: **Limitations** - Compute environments are Platform-specific and cannot be defined in external Git repositories. Select the compute environment when you add a Studio. - Data-links currently cannot be referenced in Git repositories. Mount data manually when adding a Studio. - Git repositories with multiple Studio configurations are not supported. However, you can use a Git repository with multiple branches and a single configuration per branch. ### Create the required configuration files Create a `studio-config.yaml` file in the `.seqera` directory in your repository. Your `studio-config.yaml` must contain at least `schemaVersion`, `kind`, and `session.template.kind`. All other fields are optional. ```yaml schemaVersion: "0.0.1" kind: "studio-config" session: name: "studio-name" # Must be unique to a workspace. If undefined, an auto-generated name is used description: "desc" # Short description of what the Studio is for template: kind: "registry"|"dockerfile"|"none" # Required registry: "cr.seqera.io/image:latest" # Ignored for `dockerfile` and `none` dockerfile: "Dockerfile" # Ignored for `registry` and `none` clone: enabled: true # Clone the contents of the repository to the Studio. Defaults to `true` path: "/workspace" # Defaults to `/workspace`. If you want to clone to `/workspace/repository` then you need to specify this dependencies: condaEnvironmentFile: "environment.yaml" # Define additional libraries (and versions). Ignored for `dockerfile` computeRequirements: awsBatch: # Ignored for non-AWS batch CE cpu: 2 # Number of CPUs to use. Defaults to 2 gpu: 0 # Number of GPUs to use (if the CE supports GPUs). Defaults to 0 memory: 8192 # Memory allocated in MiB. Defaults to 8192 environmentVariables: # Ordered sequence of elements that are objects (or mappings) of key-value pairs - name: "var1" value: "value1" - name: "var2" value: "value2" management: # Session management settings lifespanHours: 1 # Ignored if workspace lifespan is set isPrivate: false # Defaults to `false` ``` The schema can define a custom `Dockerfile` or an `environment.yaml` file, which must be in the `.seqera` folder. The following limitations apply: - The workspace Admin needs to set a target repository per workspace, in **Settings > Studios > Container repository**. If no repository configuration is specified, the build fails. - Each workspace needs valid credentials to push to the specified repository. - The only supported repository and compute environment combination for a fully private Dockerfile-based Studio is ECR and AWS. - The files pulled for Dockerbuild context have individual and total file size limits: - Individual files cannot be larger than 5 MB. - Total file size cannot be more than 10 MB. :::tip A public [GitHub repository][github-examples] provides branches for common use cases, each with different configuration options. ::: ### Add a Studio Add a Studio by referencing a Git repository that contains Studio configuration files. You can also configure the following fields: - **Git repository**: Enter the full URL to your Git repository (e.g., `https://github.com/your-org/your-repo`). - **Revision**: Select a branch, tag, or commit from the drop-down. The drop-down is dynamically populated based on the repository URL. If no revision is selected, the default branch is used. - **Install Conda packages**: A list of conda packages to include with the Studio. For more information on package syntax, see [conda package syntax][conda-syntax]. - **Resource labels**: Any [resource label](../labels/overview) already defined for the compute environment is added by default, but you can remove it. Add or remove custom resource labels as needed. - **Environment variables**: Environment variables for the session. The session inherits and displays all variables from the selected compute environment. Add session-specific variables as needed. Session-level variables take precedence. To override an inherited variable, define the same key with a different value. - **Studio name**: The name for the Studio. - **Description** (optional): A description for the Studio. - **Collaboration**: Session access permissions. By default, all workspace users with the launch role and above can connect to the session. Toggle **Private** on to restrict connections to the session creator only. :::note When private, workspace administrators can still start, stop, and delete sessions, but cannot connect to them. ::: - **Session lifespan**: The duration the session remains active. Available options depend on your workspace settings: - **Stop the session automatically after a predefined period of time**: An automatic timeout for the session (minimum: 1 hour; maximum: 120 hours; default: 8 hours). If a workspace-level session lifespan is configured, this field cannot be edited. Changes apply only to the current session and revert to default values after the session stops. - **Keep the session running**: Continuous session operation until manually stopped or an error terminates it. The session continues consuming compute resources until stopped. :::note When the **Git URL** or **Revision** fields are changed, form field values dynamically update. ::: ### Mount data Mount data to make them accessible in your session: 1. Select **Mount data** to open the data selection modal. 1. Choose the data to mount. 1. Select **Mount data** to confirm. Once the Studio session is running, mounted data are accessible at `/workspace/data/` using the [Fusion file system](https://docs.seqera.io/fusion). Data doesn't need to match the compute environment region, though cross-region data transfer (ingress and egress) may increase costs. Sessions have read-only access to mounted data by default. Enable write permissions by adding AWS S3 buckets as **Allowed S3 Buckets** in your compute environment configuration. Files uploaded to a mounted bucket during an active session may not be immediately available within that session. See [Running session does not show new data in object storage](../troubleshooting_and_faqs/studios_troubleshooting#running-session-does-not-show-new-data-in-object-storage) for more information. ### Repository cloning When a Studio session starts from a Git repository, the repository contents are cloned into the session using the same commit that was selected or resolved when the Studio was first created. For example, repository `https://github.com/seqeralabs/studio-templates.git` clones to `/workspace/` with `README.md` at `/workspace/README.md`. Disable cloning to share a public or private template. You can define the clone path in the schema without building a different Docker image. #### Limitations - Platform credentials are not shared with the Studio. - The `.git` folder is not synced and you cannot push/pull from the configured repository after initial Studio creation. - No preprovisioned Git credentials are available in the Studio. ## Save and start 1. Review the configuration. 1. Save your configuration: - To save and immediately start your Studio, select **Add and start**. - To save but not immediately start your Studio, select **Add only**. Studios you create are listed on the Studios landing page with a status of **stopped** or **starting**. Select a Studio to inspect its configuration details. {/* links */} [github-examples]: https://github.com/seqeralabs/studio-schema-examples [contact]: https://support.seqera.io/ [aws-cloud]: ../compute-envs/aws-cloud [aws-gpu]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html [aws-batch]: ../compute-envs/aws-batch [custom-envs]: ./custom-envs [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./container-images --- ## Seqera-provided container template :::info[**Prerequisites**] You need the following: - Valid credentials for accessing cloud storage resources - **Maintain** role permissions or above - A compute environment with sufficient resources (scale based on data volume) - [Data Explorer](../data/data-explorer) enabled ::: Configure the following fields: - **Container template**: The template for the container. Select a provided container template. - **Install Conda packages**: A list of conda packages to include with the Studio. For more information on package syntax, see [conda package syntax][conda-syntax]. :::note The workspace Admin needs to set a target repository per workspace, in **Settings > Studios > Container repository**. If no repository configuration is specified, the build will fail. Each workspace must have credentials available to push to the specified repository. ::: - **Resource labels**: Any [resource label](../labels/overview) already defined for the compute environment is added by default. Add or remove custom resource labels as needed. - **Environment variable**: Environment variables for the session. The session inherits and displays all variables from the selected compute environment. Add session-specific variables as needed. Session-level variables take precedence. To override an inherited variable, define the same key with a different value. - **Studio name**: The name for the Studio. - **Description** (optional): A description for the Studio. - **Collaboration**: Session access permissions. By default, all workspace users with the launch role and above can connect to the session. Toggle **Private** on to restrict connections to the session creator only. :::note When private, workspace administrators can still start, stop, and delete sessions, but cannot connect to them. ::: - **Session lifespan**: The duration the session remains active. Available options depend on your workspace settings: - **Stop the session automatically after a predefined period of time**: An automatic timeout for the session (minimum: 1 hour; maximum: 120 hours; default: 8 hours). If a workspace-level session lifespan is configured, this field cannot be edited. Changes apply only to the current session and revert to default values after the session stops. - **Keep the session running**: Continuous session operation until manually stopped or an error terminates it. The session continues consuming compute resources until stopped. ### Mount data Mount data to make them accessible in your session: 1. Select **Mount data** to open the data selection modal. 1. Choose the data to mount. 1. Select **Mount data** to confirm. Once the Studio session is running, mounted data are accessible at `/workspace/data/` using the [Fusion file system](https://docs.seqera.io/fusion). Data doesn't need to match the compute environment region, though cross-region data transfer (ingress and egress) may increase costs. Sessions have read-only access to mounted data by default. Enable write permissions by adding AWS S3 buckets as **Allowed S3 Buckets** in your compute environment configuration. Files uploaded to a mounted bucket during an active session may not be immediately available within that session. See [Running session does not show new data in object storage](../troubleshooting_and_faqs/studios_troubleshooting#running-session-does-not-show-new-data-in-object-storage) for more information. ## Save and start 1. Review the configuration. 1. Save your configuration: - To save and immediately start your Studio, select **Add and start**. - To save but not immediately start your Studio, select **Add only**. Studios you create are listed on the Studios landing page with a status of **stopped** or **starting**. Select a Studio to inspect its configuration details. {/* links */} [contact]: https://support.seqera.io/ [aws-cloud]: ../compute-envs/aws-cloud [aws-gpu]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html [aws-batch]: ../compute-envs/aws-batch [custom-envs]: ./custom-envs [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./container-images --- ## Add a Studio Select the **Studios** tab, and then select **Add Studio**. The options available are: - [Provided container template][provided-template] - [Custom container template][custom-container] - [Import from a Git repository][github] ### Compute environment requirements For AWS Batch compute environments: - **CPUs allocated**: The default allocation is 2 CPUs. - **GPUs allocated**: Available only if the selected compute environment has GPU support enabled. For more information about GPUs on AWS, see [Amazon ECS task definitions for GPU workloads][aws-gpu]. The default allocation is 0 GPUs. - **Maximum memory allocated**: The default allocation is 8192 MiB of memory. :::note In AWS Batch, Seqera creates two job queues and their respective compute environments: a head queue that runs the parent Nextflow process on a single On-Demand instance, and a worker queue that executes per-task processes dispatched by the head node, typically on Spot instances. Studios uses only the head queue and its compute environment and does not use the worker queue. ::: For more information on AWS Batch configuration, see [AWS Batch][aws-batch]. Single virtual machine compute environments are supported for [AWS][aws-cloud], [Azure][azure-cloud], and [Google Cloud][google-cloud]. ### EFS file systems If you configured your compute environment to include an EFS file system with **EFS file system > EFS mount path**, the mount path must be explicitly specified. The mount path cannot be the same as your compute environment work directory. If the EFS file system is mounted as your compute environment work directory, snapshots cannot be saved and sessions fail. To mount an EFS volume in a Studio session (for example, if your organization has a custom, managed, and standardized software stack in an EFS volume), add the EFS volume to the compute environment (system ID and mount path). The volume will be available at the specified mount path in the session. {/* links */} [aws-cloud]: ../compute-envs/aws-cloud [aws-gpu]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html [aws-batch]: ../compute-envs/aws-batch [azure-cloud]: ../compute-envs/azure-cloud.md [google-cloud]: ../compute-envs/google-cloud.md [github]: ./add-studio-git-repo [custom-container]: ./add-studio-custom-container [custom-image]: ./custom-envs#custom-containers [custom-container]: ./add-studio-custom-container [provided-template]: ./add-studio-provided-template --- ## Connect changelog :::note Always use the `recommended` tagged template image for new Studios. Only two earlier minor versions of Seqera Connect are supported by Seqera. ::: ## Connect server ### server/v0.11.0 `latest` - 2026-03-02 * Fix(proxy): bidirectional proxy fixes * Fix(proxy): apply security team suggestions * Fix: slow/flaky tests ### server/v0.10.0 - 2026-02-11 * Add: SSH Connectivity: * Server implementation (initialize SSH server when enabled) * Authenticate authorization requests to Platform with OIDC secret * Add SSH connection activity tracking and notifications * Change the logger timestamp format to ISO8601 * Detect network load balancer health checks ### server/v0.9.0 - 2025-12-05 - Add: missing env when testing with platform - Fix: security vulnerabilities for crypto SSH library and Slack Nebula - Upgrade go (from v1.24.3 to 1.25.3) and caddyserver (from 2.10.0 to 2.10.2) ### server/v0.8.4 - 2025-10-31 * N/A ### server/v0.8.3 - 2025-07-25 * Extract Fusion version * Fix(proxy): include prefix in Location header ### server/v0.8.2 - 2025-07-21 * Add ability to set tool identifier after compile time * Add mount data to initial configuration logs * Add eStargz support to client images build * Add management API tunnels `GET` requests * Add `$` to `metrics_patch.txt` * Add `connector_id` to stored tunnel host in Redis * Add CPU/memory collector * Add `connector_id` to identify sessions in logs * Add support for multi-platform build of Connect clients (adding Linux/ARM64) * Improve race condition `reOpening`, `compareAndDelete`, and `Handle` * Simplify `sessionid` functionality interface * Use `CONNECT_MANAGEMENT_PORT`for proxy instead of deprecated `CONNECT_METRICS_PORT` * Disable resource collector * Spot instance termination watcher implementation * Create a client and server packages * Restructure proxy package * Use `synctest` in `executor_test.go` * Basic structure of management API * Enable path-based routing ** Update go-jose library (v3 from 3.0.3 to 3.0.4; v4 from 4.0.4 to 4.0.5) * Update x/net dependency (from v0.36.0 to v0.40.0) * Upgrade go (from v1.23.0 to v1.24.3) and xcaddy (from v2.9.1 to v2.10.0) * Upgrade go in Dockerfiles (from v1.23 to v1.24) * Bump golang.org/x/net (from v0.35.0 to v0.36.0) * Bump dependencies that were using vulnerable golang.org/x/crypto (from v0.33.0 to v0.35.0) ### server/v0.8.1-rc - 2025-04-10 * Extend `GithubActions` to trigger clients publishing/promoting in downstream repo studio-templates * `sync.Map`: use `Swap` instead of `LoadAndDelete` ### server/v0.8.0-rc - 2025-03-19 * Feat: update caddy reverse proxy to dynamic A record * Feat: change proxy Docker command to be the same as before * Feat: client mux implementation * Feat: server connect-tunnel implementation * Feat: in case view scope is missing from access token, redirect with auth callback error query parameter * Feat: removal of `go-gost`, implement `connect-tunnel`, and upgrade go from v1.20 to v1.23 * Feat: micromamba based RStudio * Feat: add Git hash to stage releases * Feat: add 10 minutes' waiting period before failing notifying Platform * Cut 0.8.0 release * Upgrade xcaddy version (from v0.4.2 to v0.4.4) * Release Server version 0.7.5 ### server/v0.7.8 - 2025-03-06 * Feat: update caddy reverse proxy to dynamic a record * Feat: client mux implementation * Feat: micromamba based rstudio * Feat: server connect-tunnel implementation * Feat: in case view scope is missing form access token, redirect with auth callback error query parameter * Feat: removal of `go-gost`, implement `connect-tunnel`, and upgrade `go` (from v1.20 to v1.23) * Use Fusion v2.4.9 * Upgrade xcaddy version ### server/v0.7.7 - 2025-01-10 * Feat: change proxy Docker command to be the same as before ### server/v0.7.6 - 2025-01-08 * Latest release with adjusted workflow ### server/v0.7.5 - 2025-01-07 * Env var capital letters ## Connect client ### client/v0.12.1 `latest` - 2026-05-19 * Chore(client): expose BTRFS resize configuration * Fix(client): skip auto-discovered mounts under /proc in overlay setup * Chore: bump go_modules group dependencies across components ### client/v0.12.0 - 2026-04-16 * Feat(client): support agent forwarding in SSH server * Chore(deps): pin dependencies * Update CI actions ### client/v0.11.1 - 2026-03-24 * Fix(client): git cloning failing with conflicts on mounted datalink and preexisting files ### client/v0.11.0 - 2026-03-02 * Fix: x/net vulnerability * Fix(client): add new version to matrix * Fix: slow/flaky tests * Fix: update dependencies to fix security vulnerabilities * Refactor(client): refactor executor package * Fix(client): apply suggested security fixes ### client/v0.10.0 - 2026-02-11 * Moved Docker service management to the Connect-client. * Add: SSH Connectivity: * Server implementation (initialize SSH server when enabled) * Fingerprint verification * Add SSH connection activity tracking and notifications ### client/v0.9.0 - 2025-12-05 - Add: disk size and auto resizing based on compute environment - Add: version module and add support for client version - Fix: security vulnerabilities for crypto ssh library and slack nebula - Upgrade go (from v1.24.3 to 1.25.3) and caddyserver (from 2.10.0 to 2.10.2) - Bump server to 0.9.0 ### client/v0.8.7 - 2025-10-14 * * Fix(vscode): incorrect path in Dockerfile ### client/v0.8.6 - 2025-10-14 * Fix(vscode): incorrect path in Dockerfile ### client/v0.8.5 - 2025-07-29 * Feat: add eStargz support to client images * Feat: send squash notifications to platform * Feat: extract Fusion version ### client/v0.8.4 - 2025-07-18 * Feat: enable path-based routing (optional `CONNECT_TOOL_PATH_PREFIX` as base URL) * Feat: install pip for VS Code images * Feat: enable GHA runner cache to improve build time performance ### client/v0.8.3 - 2025-06-19 * Fix: return normal err when server closes connection ### client/v0.8.2 - 2025-06-17 * Add R-IDE option and remove unused scripts ### client/v0.8.1 - 2025-05-29 * Feat: delay running notification until the downstream is connectable * Feat: Spot instance termination watcher implementation * Feat: simplify `sessionid` functionality interface * Update x/net dependency (from v0.36.0 to v0.40.0) * Update go-jose library v3 (from 3.0.3 to 3.0.4) and v4 (from 4.0.4 to 4.0.5) * Bump golang.org/x/net (from v0.35.0 to v0.36.0) * Bump dependencies that were using vulnerable golang.org/x/crypto (from v0.33.0 to v0.35.0) * Upgrade go (from v1.23.0 to v1.24.3) and xcaddy (from v2.9.1 to v2.10.0) * Upgrade go in Dockerfiles (from v1.23 to v1.24) ### client/v0.8.0-rc - 2025-03-19 * fix: swap connector after closing previous ### client/v0.7.7 - 2025-03-07 * Feat: add 10 minutes waiting period before failing notifying Platform ### client/v0.7.6 - 2025-03-03 * Feat: micromamba based RStudio * Feat: client mux implementation * Feat: in case view scope is missing from access token, redirect with auth callback error query parameter * Feat: removal of `go-gost`, implement `connect-tunnel`, and upgrade go (from v1.20 to v1.23) * Feat: server connect-tunnel implementation * Upgrade xcaddy version * Use Fusion v2.4.9 ### client/v0.7.5 - 2024-11-18 * Updated Fusion version (from v2.4.2 to v2.4.6) and use released Nextflow language server (v1.0.0) VS Code extension ### client/v0.7.4 - 2024-10-28 * Feat: default to run, specify entrypoint ### client/v0.7.2-rc 2024-09-26 * Feat: add micromamba to VS Code Docker image ### client/v0.7.1 - 2024-09-17 * Feat: workflows for publishing versioned images for dev/staging/prod * Feat: template to test clients locally against dev * Bump clients version * Bump version to fixed one used for release * Bump Fusion to v2.3.5 --- ## Container image templates Seqera provides four container image templates: JupyterLab, R-IDE, Visual Studio Code, and Xpra. The image templates install a limited number of packages when the Studio session container is built. You can install additional packages as needed during a Studio session. The image template tag includes the version of the analysis application, an optional incompatibility flag, and the Seqera Connect version. Connect is the proprietary Seqera web server client that manages communication with the container. The image template tag has the format: ```ignore title="Image template tag" -[u]- ``` - ``: Third-party analysis application that follows its own semantic versioning `..`, such as `4.2.5` for JupyterLab. - ``: Optional analysis application update version, such as `u1`, for instances where a backwards incompatible change is introduced. - ``: Seqera Connect client version, such as `0.12` or `0.12.0`. The Seqera Connect client version string has the format: ```ignore title="Seqera version tag subset" .. ``` - ``: Signifies major version changes in the underlying Seqera Connect client. - ``: Signifies breaking changes in the underlying Seqera Connect client. - ``: Signifies patch (non-breaking) changes in the underlying Seqera Connect client. When pushed to the container registry, an image template is tagged with the following tags: - `-.`, such as `4.2.3-0.9`. When you add a new container template image, this is the tag displayed in Seqera Platform. - `-..`, such as `4.2.3-0.9.0`. To view the latest versions of the images, see [public.cr.seqera.io](https://public.cr.seqera.io/). You can also augment the Seqera-provided image templates or use your own custom container image templates. This is the recommended approach for managing reproducible analysis environments. For more information, see [Custom environments][custom-envs]. ## JupyterLab 4.2.5 The default user is the `root` account. The following [conda-forge](https://conda-forge.org/) packages are available by default: - `python=3.13.0` - `pip=24.2` - `jedi-language-server=0.41.4` - `jupyterlab=4.2.5` - `jupyter-collaboration=1.2.0` - `jupyterlab-git=0.50.1` - `jupytext=1.16.4` - `jupyter-dash=0.4.2` - `ipywidgets=7.8.4` - `pandas[all]=2.2.3` - `scikit-learn=1.5.2` - `statsmodels=0.14.4` - `itables=2.2.2` - `seaborn[stats]=0.13.2` - `altair=5.4.1` - `plotly=5.24.1` - `r-ggplot2=3.5.1` - `nb_black=1.0.7` - `qgrid=1.3.1` To install additional Python packages during a running Studio session, execute `!pip install ` commands in your notebook environment. Install additional system-level packages in a terminal window with `apt install `. To see all JupyterLab image templates, including security scan results, or to inspect the container specification, see [public.cr.seqera.io/repo/platform/data-studio-jupyter][ds-jupyter]. ## R-IDE 4.4.1 The default user is the `root` account. To install R packages during a running Studio session, execute `install.packages("")` commands in your notebook environment. Install additional system-level packages in a terminal window with `apt install `. To see all R-IDE image templates, including security scan results, or to inspect the container specification, see [https://public.cr.seqera.io/repo/platform/data-studio-ride][ds-ride]. ## Visual Studio Code 1.93.1 [Visual Studio Code][def-vsc] is an integrated development environment (IDE) that supports many programming languages. The default user is the `root` account. The container template image ships with the latest stable version of [Nextflow] and the [VS Code extension for Nextflow][nf-lang-server] to make troubleshooting Nextflow workflows easier. To install additional extensions during a running Studio session, select **Extensions**. Install additional system-level packages in a terminal window with `apt install `. To see all Visual Studio Code image templates, including security scan results, or to inspect the container specification, see [public.cr.seqera.io/platform/data-studio-vscode][ds-vscode]. ### Docker-in-docker A common use of VS Code in Studios is developing and troubleshooting Nextflow pipelines, which requires running Docker inside the Dockerized container. The recommended method is: **1. Create an [AWS Cloud][aws-cloud] compute environment:** By default, this type of compute environment is optimized for running Nextflow pipelines. :::tip Many standard nf-core pipelines such as [*nf-core/rnaseq*](https://nf-co.re/rnaseq) require at least 4 CPUs and 16 GB memory. In **Advanced options**, specify an instance type with at least these resources (e.g., `m5d.xlarge`). ::: **2. Run only one Studio session per compute environment:** The session and Nextflow can then use all the available CPU and memory. :::tip The nf-core pipeline template was updated, and many existing pipelines don't yet use the new multi-line shell command in `nextflow.config`. To ensure compatibility with the latest version of Nextflow (which ships with the VS Code container template image), include the following in your pipeline `nextflow.config` file. ```bash // Set bash options process.shell = [ "bash", "-C", // No clobber - prevent output redirection from overwriting files. "-e", // Exit if a tool returns a non-zero status/exit code "-u", // Treat unset variables and parameters as an error "-o", // Returns the status of the last command to exit.. "pipefail" // ..with a non-zero status or zero if all successfully execute ] ``` ::: ## Xpra 6.2.0 [Xpra][def-xpra], known as _screen for X_, gives you remote access to individual X11 graphical applications. The container template image also installs NVIDIA Linux x64 (AMD64/EM64T) drivers for Ubuntu 22.04 for running GPU-enabled applications. To use these GPU drivers, your compute environment must specify GPU instance families. The default user is the `root` account. The image is based on `ubuntu:jammy`. Install additional system-level packages during a running Studio session in a terminal window with `apt install `. To see all Xpra image templates, including security scan results, or to inspect the container specification, see [public.cr.seqera.io/repo/platform/data-studio-xpra][ds-xpra]. ## EFS file system limitations If you configure your compute environment to include an EFS file system with **EFS file system > EFS mount path**, you must explicitly specify the mount path. The mount path cannot be the same as your compute environment work directory. If the EFS file system is mounted as your compute environment work directory, snapshots cannot be saved and sessions fail. To mount an EFS volume in a Studio session (for example, if your organization has a custom, managed, and standardized software stack in an EFS volume), add the EFS volume to the compute environment (system ID and mount path). The volume is available at the specified mount path in the session. For more information on AWS Batch configuration, see [AWS Batch][aws-batch]. {/* links */} [aws-cloud]: ../compute-envs/aws-cloud [aws-batch]: ../compute-envs/aws-batch [custom-envs]: ./custom-envs [build-status]: ./custom-envs#build-status [ds-jupyter]: https://public.cr.seqera.io/repo/platform/data-studio-jupyter [ds-vscode]: https://public.cr.seqera.io/repo/platform/data-studio-vscode [ds-xpra]: https://public.cr.seqera.io/repo/platform/data-studio-xpra [ds-ride]: https://public.cr.seqera.io/repo/platform/data-studio-ride [def-vsc]: https://code.visualstudio.com/ [Nextflow]: https://nextflow.io/ [nf-lang-server]: https://marketplace.visualstudio.com/items?itemName=nextflow.nextflow [def-xpra]: https://github.com/Xpra-org/xpra --- ## Custom environments In addition to the Seqera-provided container images, you can build custom container environments by augmenting the Seqera-provided images with Conda packages or by supplying your own base container image. Studios uses the [Wave][wave-home] service to build custom container images. For ready-to-use examples, see [Example custom Studios][example-studios]. ## Conda packages Augment a Seqera-provided image with Conda packages to add the tools you need to a Studio session. :::info[**Prerequisites**] You need the following: - Wave configured. See [Wave containers][wave]. - A target repository set per workspace by the workspace Admin, in **Settings** > **Studios** > **Container repository**. - Workspace credentials with push access to the target repository. ::: ### Conda package syntax {#conda-package-syntax} When adding a new Studio, you can install Conda packages in the container image. The supported schema is identical to the Conda `environment.yml` file. For more information, see [Creating an environment file manually][env-manually]. ```yaml title="Example environment.yml" channels: - conda-forge dependencies: - numpy - pip: - matplotlib - seaborn ``` To create a Studio with custom Conda packages, see [Add a Studio][add-s]. ## Custom container image {#custom-containers} For advanced use cases, you can build your own container image. Public container registries are supported by default. [Amazon Elastic Container Registry (ECR)][ecr] and [Azure Container Registry (ACR)][acr] are the currently supported private container registries. :::info[**Prerequisites**] You need the following: - A container image. - Access to a container image repository, either a public container registry or a private Amazon ECR or Azure ACR repository. ::: ### Dockerfile configuration {#dockerfile} For your custom container image, you must use a Seqera-provided base image and include several additional build steps for compatibility with Studios. To create a Studio with a custom image, see [Add a Studio][add-s]. Custom images must include an `io.seqera.connect.version` label specifying the `connect-client` version used. Seqera Platform uses this label to determine available functionality when configuring and launching the Studio. :::note Studios starts without this label, but certain features (such as SSH connectivity) are unavailable. ::: #### Ports The container must use the value of the `CONNECT_TOOL_PORT` environment variable as the listening port for any interactive software you include in your custom container. #### Signals Upon termination, the container's main process must handle the `SIGTERM` signal and perform any necessary cleanup. After a 30-second grace period, the container receives the `SIGKILL` signal. #### Minimal Dockerfile The minimal Dockerfile includes directives to: - Pull a Seqera-provided base image with prerequisite binaries. - Set an image label indicating the version used. - Copy the `connect` binary into the build. - Set the container entry point. Customize the following Dockerfile to include any additional software you require: ```docker title="Minimal Dockerfile" # Add a default Connect client version. Can be overridden by build arg ARG CONNECT_CLIENT_VERSION="0.12" # Seqera base image # highlight-next-line FROM public.cr.seqera.io/platform/connect-client:${CONNECT_CLIENT_VERSION} AS connect # highlight-start # 1. Add connect version label to image metadata ARG CONNECT_CLIENT_VERSION LABEL io.seqera.connect.version="${CONNECT_CLIENT_VERSION}" # 2. Add connect binary COPY --from=connect /usr/bin/connect-client /usr/bin/connect-client # 3. Install connect dependencies RUN /usr/bin/connect-client --install # 4. Configure connect as the entrypoint ENTRYPOINT ["/usr/bin/connect-client", "--entrypoint"] # highlight-end ``` For example, to run a Python-based HTTP server, build a container from the following Dockerfile. When a Studio runs the custom template environment, the value for the `CONNECT_TOOL_PORT` environment variable is provided dynamically. ```docker title="Example Dockerfile with Python HTTP server" # Add a default Connect client version. Can be overridden by build arg ARG CONNECT_CLIENT_VERSION="0.12" # Seqera base image # highlight-next-line FROM public.cr.seqera.io/platform/connect-client:${CONNECT_CLIENT_VERSION} AS connect FROM ubuntu:20.04 RUN apt-get update --yes && apt-get install --yes --no-install-recommends python3 # highlight-start ARG CONNECT_CLIENT_VERSION LABEL io.seqera.connect.version="${CONNECT_CLIENT_VERSION}" COPY --from=connect /usr/bin/connect-client /usr/bin/connect-client RUN /usr/bin/connect-client --install ENTRYPOINT ["/usr/bin/connect-client", "--entrypoint"] # highlight-end # highlight-next-line CMD ["/usr/bin/bash", "-c", "python3 -m http.server $CONNECT_TOOL_PORT"] ``` ### Custom container image examples For example custom Studio environment container images, see the [custom Studios examples repository][custom-studios-examples]. ### Inspect container augmentation build status {#build-status} You can inspect the progress of a custom container image build, including any errors if the build fails. A link to the [Wave service][wave-home] container build report is available for every build. If the build fails, the Studio session has the **build-failed** status, and the build error details are available in the session's **Error report** tab. To inspect the status of a build, complete the following: 1. Select the **Studios** tab in Seqera Platform. 1. From the list of sessions, select the name of the session with `building` or `build-failed` status, then select **View**. 1. In the **Details** tab, scroll to **Build reports** and select **Summary** to open the Wave service container build report for your build. 1. Optional: If the build failed, select the **Error report** tab to view the build errors. {/* links */} [add-s]: ./add-studio [aws-batch]: ../compute-envs/aws-batch [wave]: https://docs.seqera.io/platform-enterprise/enterprise/configuration/wave [custom-studios-examples]: https://github.com/seqeralabs/custom-studios-examples [wave-home]: https://seqera.io/wave/ [env-manually]: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually [example-studios]: ./example-studios [ecr]: https://aws.amazon.com/ecr/ [acr]: https://azure.microsoft.com/en-us/products/container-registry --- ## Example custom Studios Seqera provides a collection of example custom Studio environments for common bioinformatics and data science applications. Each example includes a Dockerfile and a pre-built container image you can deploy immediately or use as a template for your own custom Studio. Any application that serves its interface over HTTP can run in a Studio session. All example Dockerfiles and pre-built images are available via individual branches in the [custom-studios-examples](https://github.com/seqeralabs/custom-studios-examples) GitHub repository. For instructions on building your own custom container image from scratch, see [Custom environments][custom-envs]. | GitHub repository branch | Description | Pre-built image URL | |---|---|---| | [Marimo](https://github.com/seqeralabs/custom-studios-examples/tree/marimo) | Reactive Python notebook | `ghcr.io/seqeralabs/custom-studios-examples/marimo` | | [Streamlit](https://github.com/seqeralabs/custom-studios-examples/tree/streamlit) | Interactive web apps (MultiQC demo) | `ghcr.io/seqeralabs/custom-studios-examples/streamlit` | | [CELLxGENE](https://github.com/seqeralabs/custom-studios-examples/tree/cellxgene) | Single-cell data visualization | `ghcr.io/seqeralabs/custom-studios-examples/cellxgene` | | [Shiny](https://github.com/seqeralabs/custom-studios-examples/tree/shiny) | R-based interactive web apps | `ghcr.io/seqeralabs/custom-studios-examples/shiny` | | [TTYD](https://github.com/seqeralabs/custom-studios-examples/tree/ttyd) | Web-based terminal with Samtools | `ghcr.io/seqeralabs/custom-studios-examples/ttyd` | :::note Pre-built images may not reflect the latest version of the Seqera Connect client, system libraries, nor packages. See the [GitHub repository releases](https://github.com/seqeralabs/custom-studios-examples/releases) for current image tags. ::: ## Deploy an example Studio {#deploy} To deploy any example, follow the [Add a Studio][add-s] workflow either: 1. Select the **Import from Git repository** option. Copy and paste the repository path in the **Git repository URL** field. Then select the branch name in the auto-populated **Revision** field. 1. Select **Custom container template**, and enter the pre-built image URL from the table above. For environment variables and detailed setup instructions, see the `README.md` in each example's branch. For more information about managing Studios, see [Manage Studios][manage]. ### Provide files to Studios {#provide-files} Studios uses [Fusion][fusion] to mount cloud storage as a local filesystem inside the Studio container. When you mount a cloud bucket, its contents are available at `/workspace/data//`. There are two approaches to make files available to your custom Studio: #### Environment variables {#env-vars} Some examples define environment variables that accept cloud storage paths (such as `s3://bucket/path/to/file.csv`). When you create a Studio, set the value of these variables in the **Environment variables** section of the **Compute and Data** tab. The container translates the cloud path to the corresponding local path at `/workspace/data/` automatically. #### Data-links {#data-links} Data-links point to specific cloud storage paths. When you create a data-link, the linked directory appears in the running Studio at `/workspace/data//`. Once you [Add data-links](../data/data-explorer#add-data-repository-links), applications that support a file browser or path input can then access data at `/workspace/data//`. ## Overview of example Studios ### Marimo [Marimo](https://marimo.io/) is an open-source reactive Python notebook. Unlike traditional notebooks, Marimo automatically re-executes cells when their dependencies change, which makes it well-suited to iterative analysis where inputs change frequently. It also supports SQL natively and can publish notebooks as standalone shareable apps. The Marimo Studio uses the [uv](https://github.com/astral-sh/uv) package manager and comes pre-installed with common data science packages including scikit-learn, pandas, and altair. Access your pipeline outputs by mounting the relevant S3 buckets when you create the Studio, located at `/workspace/data/` inside the session. ### Streamlit [Streamlit](https://streamlit.io/) is an open-source Python framework for building interactive web applications. Hosting a Streamlit app in Studios gives it direct access to your S3 data through Fusion. This means no credentials to configure, no data to move or copy. The example Studio ships with a [MultiQC](https://multiqc.info/) demo app that illustrates a typical bioinformatics use case: interactive quality control reports served directly from pipeline output stored in S3. The same pattern applies to any Streamlit app you want to host within your Seqera workspace. ### CELLxGENE [CELLxGENE](https://chanzuckerberg.github.io/cellxgene/) is an interactive visualization tool for single-cell and spatial omics data. It supports exploration, analysis, and annotation of single-cell datasets in `.h5ad` format. The CELLxGENE Studio loads a dataset directly from S3 on startup using environment variables you set when creating the Studio. A default public dataset (PBMCs 3k) is pre-configured so you can verify the Studio is working before connecting your own data. ### Shiny [Shiny](https://shiny.posit.co/) is a popular framework for building interactive web applications in R or Python. The example Studio runs a demonstration R Shiny app that generates plots and output tables from CSV input data stored in S3. Running Shiny in Studios means your app runs inside your own cloud infrastructure, with access to pipeline outputs through Fusion. Each user who connects to the Studio gets their own private session, making it suitable for sharing results with colleagues who need to interact with the data directly rather than view a static report. ### TTYD [TTYD](https://tsl0922.github.io/ttyd/) is a web-based terminal emulator. The example Studio provides browser-based terminal access to a container with [Samtools](http://www.htslib.org/) pre-installed — useful when you need command-line access to a specific bioinformatics tool without the overhead of a full IDE. This pattern is straightforward to adapt: replace the Samtools base image with any containerized tool that supports `apt-get` or `yum`, then add the TTYD and Connect client layers. It's a practical option for giving colleagues access to a tool in a controlled, reproducible environment without requiring them to configure anything locally. ## Build an example image locally {#build-locally} To build any example image locally, clone the repository branch and run the Docker build command: ```bash git clone --branch --single-branch https://github.com/seqeralabs/custom-studios-examples.git docker build --platform linux/amd64 --build-arg CONNECT_CLIENT_VERSION=0.12 -t . ``` Replace `` with the branch name (such as `marimo` or `streamlit`) and `` with your preferred image tag. Then push the built image to your container registry, then use the image URI when you [deploy the Studio](#deploy). ## Extend or contribute examples {#extend} You can use these examples as a starting point for your own custom Studios. Any application that serves its graphical interface over an HTTP port can run in Studios. For detailed instructions on building custom container images, see [Custom environments](./custom-envs.md). To contribute new examples to the repository, see the [contributing guidelines][contribute] in the GitHub repository. {/* links */} [contribute]: https://github.com/seqeralabs/custom-studios-examples#contributing [fusion]: https://docs.seqera.io/fusion/ [custom-container]: ./add-studio-custom-container [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [containers]: ./add-studio-custom-container [manage]: ./managing [add-s]: ./add-studio [custom-envs]: ./custom-envs --- ## Manage Studios Select the **Studios** tab in Platform to: - Start, stop, or connect to an existing session. - Dynamically filter the list of Studios using the search bar. - Open a detailed view that displays configuration information. :::note - If you're not able to see the Studios tab, contact your Platform administrator. - Review the user roles documentation for details about role permissions. ::: ## Start a Studio session Select the three dots next to the status message for the Studio you want to start, then select **Start**. You can optionally change the configuration of the Studio, then select **Start in new tab**. Once the session is running, you can connect to it. A session will run until it is stopped manually or it encounters a technical issue. :::note A session consumes resources until it's **stopped**. ::: Once a Studio session is in a **running** state, you can connect to it, obtain a public link to the session to share with collaborators inside your workspace, and stop it. ## Start an existing Studio as a new session You can use any existing Studio as the foundation for adding a new session. This functionality creates a clone of the session, including its checkpoint history, preserving any modifications made to the original Studio. When you create a session in this way, future changes are isolated from the original session. When adding a new session from an existing session or checkpoint, the following fields cannot be changed: - **Studio template** - **Original Studio session and checkpoint** - **Compute environment** - **Installed Conda packages** - **Session duration** To add a new session from an existing **stopped** session, complete the steps described in [Add a Studio][add-s]. Additionally, you can add a new session from any existing Studio checkpoint except the currently running checkpoint. From the detail page, select the **Checkpoints** tab and in the **Actions** column, select **Add as new Studio**. This is useful for interactive analysis experimentation without impacting the state of the original Studio. ## Start a new session from a checkpoint You can start a new session from an existing stopped session. This will inherit the history of the parent checkpoint state. From the list of **stopped** Studios in your workspace, select the three dots next to the status message for the Studio you want to start and select **Add as new**. Alternatively, select the **Checkpoints** tab on the detail page, select the three dots in the **Actions** column, and then select **Add as new Studio** to start a new session. ## Stop a Studio session To stop a running session, select the three dots next to the status message and then select **Stop**. The status will change from **running** to **stopped**. When a session is stopped, the compute resources it's using are deallocated. You can stop a session at any time, except when it is **starting**. Stopping a running session creates a new checkpoint. ## Restart a stopped session When you restart a stopped session, the session uses the most recent checkpoint. ## Delete a Studio :::note This functionality is available to all user roles excluding the **View** role. ::: You can only delete a Studio when it's **stopped**. Select the three dots next to the status message and then select **Delete**. The Studio is deleted immediately and can't be recovered. ## Star/favourite a Studio To star a Studio, select the star icon in the list of Studios or on a Studio's details page. A starred Studio shows a filled yellow star. To unstar it, select the star icon again. ## Search The **Search studios** bar filters by one or more `:` entries: - `status`: Search Studios with a specific status. - `username`: Search Studios created by a specific user. - `computeEnvName`: Search Studios in a specific compute environment. - `is:starred`: Search Studios that have been starred by the user. The field suggests valid keywords as you type. Search covers all Studios in a workspace. Enter a query in the Search studios field. Platform identifies each valid `keyword:value` substring, combines the remaining text into a single freeform string, and filters Studios using all of these criteria. ## Connect to a Studio To connect to a running session, select the three dots next to the status message and choose **Connect**. :::warning An active connection to a session will not prevent administrative actions that might disrupt that connection. For example, a session can be stopped by another workspace user while you are active in the session, the underlying credentials can be changed, or the compute environment can be deleted. These are independent actions and the user in the session won't be alerted to any changes - the only alert will be a server connection error in the active session browser tab. ::: Once connected, the session will display the status of **running** in the list, and any connected user's avatar will be displayed under the status in both the list of Studios and in each Studio's detail page. ## Collaborate in a Studio session :::note Collaborators need valid workspace permissions to connect to the running Studio. ::: To share a link to a running session with collaborators inside your workspace, select the three dots next to the status message for the session you want to share, then select **Copy Studio URL**. Using this link, other authenticated users can access the session directly. Seqera-managed container templates offer varying levels of multi-user collaboration: - **JupyterLab:** Supports multi-user collaboration via the `jupyter-collaboration` package. Each connected user has a randomly assigned color-coded avatar and the user cursor inherits the same color for easily differentiating multiple connected users. - **VS Code:** Supports multi-user collaboration by default, but each connected user is not readily distinguishable. For a more fully-featured collaborative experience, install the [Microsoft Live Share extension][liveshare] or [P2P Live Share][p2p-liveshare]. - **R-IDE:** By default, multi-user collaboration is not supported. When an additional user connects to the running session, the previously connected user is notified and forcibly disconnected. - **Xpra:** Supports multi-user collaboration by default and is similar to a remote desktop experience. Connected users are not readily distinguishable. :::note RStudio Professional Server supports multi-user collaboration. Add your own custom container and include your Posit Workbench license code as a environment variable to take advantage of this. ::: Multi-user collaboration in custom containers is dependent on the container configuration. ## Limit Studio access to a specific cloud bucket subdirectory {#cloud-bucket-subdirectory} For a cloud bucket that is writeable, as enabled by including the bucket in a compute environment's **Allowed S3 bucket** list, you can limit write access to that bucket from within a Studio session. To limit read-write access to a specific subdirectory, complete the following steps: 1. From your Seqera instance, select the **Data Explorer** tab. 1. Select **Add Cloud Bucket**. 1. Complete the following fields: - **Provider**: Select your cloud provider. - **Bucket path**: Enter the full path to the subdirectory of the bucket that you want to use with your Studio, such as `s3://1000genomes/data`. - **Name**: Enter a name for this cloud bucket, such as *1000-genomes-data-dir*, to indicate the bucket name and subdirectory path. - **Credentials**: Select your provider credentials. - Optional: **Description**: Enter a description for this cloud bucket. 1. Select **Add** to create a custom data-link to a subdirectory in the cloud bucket. When defining a new Studio, you can configure the **Mounted data** by selecting the custom data-link created by the previous steps. ## Migrate a Studio from an earlier container image template :::warning Due to the nature of fully customizable, containerized applications, users can modify environments leading to a variety of configurations and outcomes. This is therefore a best effort to support Studio migrations and a successful outcome is not guaranteed. ::: As Studios matures and new versions of JupyterLab, R-IDE, Visual Studio Code, and Xpra are released, new Seqera-provided image templates will be periodically released including updated versions of Seqera Connect. The most recent container template images will be tagged `recommended` and earlier template images will be tagged `deprecated`. Temporary container templates tagged with `experimental` are not supported and should not be used in production environments. :::tip Always use the `recommended` tagged template image for new Studios. Only two earlier minor versions of [Seqera Connect][connect] are supported by Seqera. ::: To migrate a Studio to a more recent container version and Seqera Connect: 1. Select the Studio to migrate. 1. Select **Add as new**. By default this selects the latest session checkpoint. 1. In the **General config** section, change the image template selection in the drop-down list to use the `latest` tagged version of the same interactive environment. 1. For the **Summary** section, ensure that the specified configuration is correct. 1. Immediately start the new, duplicated Studio session by selecting **Add and start**. 1. **Connect** to the new running Studio session. 1. Make a note of any package or environment errors displayed. 1. **Stop** the running Studio session. 1. Go back to the original Studio: 1. **Start** the session. 1. **Connect** to the session. 1. Uninstall any packages related to the errors: 1. JupyterLab: Execute `!pip uninstall ` or `apt remove ` to uninstall system-level packages. 1. R-IDE: Execute `uninstall.packages("")` to uninstall R packages or `apt remove ` to uninstall system-level packages. 1. Visual Studio Code: Select the **Manage** gear button at the right of an extension entry and then choose **Uninstall** from the drop-down. 1. Xpra: Use `apt remove ` to uninstall system-level packages. 1. **Stop** the running Studio session. A new checkpoint is created. 1. Repeat Step 1 **Add as new** using the new, most recent created checkpoint from the steps above. ## Migrate a Studio between compute environments You can switch an existing Studio to a different compute environment from the Studio's **Edit** screen, provided the new compute environment has the same working directory as the current one. This works for any switch, for example scaling resources up or down, moving between regions, or changing compute environment types in the same cloud provider. You can migrate in place to preserve the Studio's checkpoints and state, or migrate from scratch to copy specific files into a fresh Studio. ### Migrate in place (recommended) Use this path to preserve the Studio's [checkpoint][checkpoints] history, installed packages, and session state. When the new compute environment points at the same `workDir` as the current one, the Studio's existing checkpoints in the `.studios/checkpoints` folder remain reachable. Switching the compute environment binds the Studio to the new one while preserving its checkpoints and state. :::note Object storage bucket names are globally unique within a single cloud provider but not across providers. In-place migration is therefore limited to compute environments in the same cloud provider, for example AWS Batch to AWS Cloud, both backed by S3. ::: :::info[**Prerequisites**] You need the following: - A stopped Studio. - A new compute environment in the `AVAILABLE` status, configured with the same `workDir` as the current one. - [Credentials][credentials] on the new compute environment with read and write access to the `workDir` bucket. ::: #### Steps 1. From the **Studios** tab, open the details for the Studio you want to migrate. 1. Select **Edit**. 1. In the **Compute environment** drop-down, select the new compute environment. 1. Review the resource labels on the form (see [Resource label changes](#resource-labels-on-migration)). 1. Save your changes. 1. Start the Studio. The new session restores from the latest checkpoint stored in the shared `workDir`. The **Compute environment** field is editable only on the **Edit** screen. The **Add** and **Start** screens keep the Studio bound to its original compute environment. #### Compatible compute environments The drop-down lists only compute environments compatible with the Studio's current one. A compute environment is compatible when it: - Uses the same `workDir` as the Studio's current compute environment. - Is in the `AVAILABLE` status. The Studio's current compute environment is always listed first, even when it would not be selectable on its own. #### Resource label changes {#resource-labels-on-migration} When you select a different compute environment, the form syncs the Studio's [resource labels][resource-labels]: - Labels inherited from the **previous** compute environment are removed. - Labels that belong to the **Studio itself** (not inherited from a compute environment) are preserved. - The **new** compute environment's resource labels are added. For example, you switch a Studio with labels `[ce-a-1, ce-a-2, studio-1]` from compute environment `CE-A` to compute environment `CE-B`, whose resource labels are `[ce-b-1]`. The Studio's labels become `[studio-1, ce-b-1]`. ### Migrate from scratch Use this path when you don't need the Studio's checkpoint history and only want to copy specific files, such as datasets, notebooks, or scripts, into a fresh Studio backed by the new compute environment. :::note This path does not carry over checkpoints, installed packages, or environment customizations from the original Studio. Copy anything you want to keep through a shared bucket. ::: Move files between the source and target Studios through a shared bucket that both compute environments can read and write. The following example uses AWS S3: 1. Start the existing Studio. Confirm that its compute environment lists a shared S3 bucket in **Allowed S3 buckets**, and that the bucket is mounted on the Studio as a [data link](#studio-session-data-links). 1. Inside the running Studio, copy any files you want to save into the mount at `/workspace/data/`. 1. Create the new compute environment configured with the same shared S3 bucket in **Allowed S3 buckets**, then [add a new Studio][add-s] that uses it. 1. Start the new Studio with the shared bucket mounted, then copy files from `/workspace/data/` into the local Studio workspace. For common migration issues, see [Studios troubleshooting][studios-troubleshooting]. :::tip [AWS Cloud][aws-cloud] is the recommended runtime for new Studios. It starts sessions faster and manages resources more simply than [AWS Batch][aws-batch] for single-VM Studio workloads. To switch an existing Studio from AWS Batch to AWS Cloud, use the in-place migration steps. ::: ## Studio session statuses Sessions have the following possible statuses: - **building**: When a custom environment is building the template image for a new session. The [Wave] service performs the build action. For more information on this status, see [Inspect custom container template build status][build-status]. - **build-failed**: When a custom environment build has failed. This is a non-recoverable error. Logs are provided to assist with troubleshooting. For more information on this status, see [Inspect custom container template build status][build-status]. - **starting**: The Studio is initializing. - **running**: When a session is **running**, you can connect to it, copy the URL, or stop it. In addition, the session can continue to process requests/run computations in the absence of an ongoing connection. - **stopping**: The recently-running session is in the process of being stopped. - **stopped**: When a session is stopped, the associated compute resources are deallocated. You can start or delete the session when it's in this state. - **errored**: This state most often indicates that there has been an error starting the session but it is in a **stopped** state. :::note There might be errors reported by the session itself but these will be overwritten with a **running** status if the session is still running. ::: ## Connect to a Studio via SSH (public preview) :::info[**Prerequisites**] - SSH access enabled for your workspace - Your SSH public key added to your Seqera Platform user profile - **SSH Connection** toggle enabled when adding the Studio - The Studio is in a **running** state. - **Connect client**: Version 0.10.0 or later ::: Direct SSH connections to running Studio containers support standard SSH clients, terminal access, and [VS Code Remote SSH](https://code.visualstudio.com/docs/remote/ssh). JupyterLab, R-IDE, VS Code, and Xpra container templates are supported. :::note If you didn't enable SSH when you initially added your Studio, stop and enable **SSH Connection** before restarting the Studio. ::: ### Terminal access Connect to a Studio using standard SSH: ```bash ssh @@ -p 2222 ``` **Example:** ```bash ssh alice@a01ac8894@connect.example.com -p 2222 ``` Where: - ``: Your Seqera Platform username - ``: The Studio session ID (visible in the Studios list) - ``: Your connect proxy domain - Port: `2222` (default SSH proxy port) The session ID is displayed in the Studio details page and the Studios list. ### VS Code Remote SSH Connect to a Studio using VS Code Remote SSH: 1. Install the [Remote - SSH extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) in VS Code. 2. **Required:** Disable local server mode in your VS Code settings: - Open VS Code Settings (Code > Preferences > Settings or Cmd+,) - Search for `remote.SSH.useLocalServer` - Set to `false` Alternatively, add this to your `settings.json`: ```json { "remote.SSH.useLocalServer": false, "remote.SSH.enableRemoteCommand": true, "remote.SSH.useLocalServer": false, "remote.SSH.preconnect": "" } ``` :::warning VS Code's local server mode (SSH multiplexing over SOCKS) is not supported. Connections will fail if this setting is enabled. ::: 3. Connect to the Studio: - Open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P) - Run **Remote-SSH: Connect to Host** - Select your configured host or enter the SSH connection string directly - VS Code opens a new window connected to your Studio Once connected, you can: - Access the Studio filesystem - Open folders and files - Use the integrated terminal - Install VS Code extensions in the remote environment - Debug code running in the Studio - Install packages ### Claude Code desktop app The Claude Code desktop app requires later Connect versions than other SSH connection methods. :::info[**Prerequisites**] You need the following: - Connect server and proxy version 0.12.1 or later - Connect client version 0.13.0 or later ::: The app reads `~/.ssh/config`, but its **SSH Host** field accepts a hostname only. It cannot parse the `@` pair. Define a host alias, then reference the alias in the app. 1. Add an entry to `~/.ssh/config`: ``` Host my-studio HostName connect.connect.cloud.seqera.io User alice@a01ac8894 Port 2222 IdentityFile ~/.ssh/id_ed25519 ``` Put the `@` pair in `User`, and only the connect domain in `HostName`. 2. Add an SSH connection in the app: - **SSH Host**: `my-studio` - **SSH Port**: `2222` :::warning Set **SSH Port** explicitly. The app ignores the `Port` value in `~/.ssh/config` and defaults to port 22. The connection then fails with a handshake timeout. ::: If the connection fails, see [SSH connections](../troubleshooting_and_faqs/studios_troubleshooting#ssh-connections-public-preview). ### SSH authentication SSH connections use public key authentication: 1. Platform validates your credentials and workspace permissions. 2. Your SSH client uses your private key for authentication. 3. The connection is encrypted end-to-end. For troubleshooting SSH connection issues, see [Studios troubleshooting](../troubleshooting_and_faqs/studios_troubleshooting#ssh-connections-public-preview). ## Studio session data-links You can configure a Studio session to mount one or more data-links, where cloud buckets that you have configured in your compute environment are read-only, or read-write available to the session. If your compute environment includes a cloud bucket in the **Allowed S3 bucket** list, the bucket is writeable from within a session when that bucket is included as a data-link. You can limit write access to just a subdirectory of a bucket by creating a custom data-link for only that subdirectory in Data Explorer, and then mount the data-link to the Studio session. For example, if you have the following S3 buckets: - `s3://biopharmaXs`: Entire bucket - `s3://biopharmaX/experiments/project-A/experiment-1/data`: Subdirectory to mount in a Studio session Mounted data links are exposed at the `/workspace/data/` directory path inside a Studio session. For example, the bucket subdirectory `s3://biopharmaX/experiments/project-A/experiment-1/data`, when mounted as a data-link, is exposed at `/workspace/data/biopharmaxs-project-a-experiment-1-data`. For more information, see [Limit Studio access to a specific cloud bucket subdirectory][cloud-bucket-subdirectory]. ## Studio session checkpoints When starting a Studio session, a *checkpoint* is automatically created. A checkpoint saves all changes made to the root filesystem and stores it in the attached compute environment's pipeline work directory in the `.studios/checkpoints` folder with a unique name. The current checkpoint is updated every five minutes during a session. :::warning Checkpoints vary in size depending on libraries installed in your session environment. This can potentially result in many large files stored in the compute environment's pipeline work directory and saved to cloud storage. This storage will incur costs based on the cloud provider. Due to the architecture of Studios, you cannot delete any checkpoint files to save on storage costs. Deleting a Studio session's checkpoints will result in a corrupted Studio session that cannot be started nor recovered. ::: When you stop and start a session, or start a new session from a previously created checkpoint, changes such as installed software packages and configuration files are restored and made available. Changes made to mounted data are not included in a checkpoint. Checkpoints can be renamed and the name has to be unique per Studio. Spaces in checkpoint names are converted to underscores automatically. Checkpoint files in the compute environment work directory may be shared by multiple Studios. Each checkpoint file is cleaned up asynchronously after the last Studio referencing the checkpoint is deleted. :::note The cleanup process is a best effort and not guaranteed. Seqera attempts to remove the checkpoint, but it can fail if, for example, the compute environment credentials used do not have sufficient permissions to delete objects from storage buckets. ::: ## Session volume automatic resizing By default, a session allocates an initial 2 GB of storage. Available disk space is continually monitored and if the available space drops below a 1 GB threshold, the file system is dynamically resized to include an additional 2 GB of available disk space. This approach ensures that a session doesn't initially include unnecessary free disk space, while providing the flexibility to accommodate installation of large software packages required for data analysis. The maximum storage allocation for a session is limited by the compute environment disk boot size. By default, this is 30 GB. This limit is shared by all sessions running in the same compute environment. If the maximum allocation size is reached, it is possible to reclaim storage space using a snapshot. Stop the active session to trigger a snapshot from the active volume. The snapshot is uploaded to cloud storage with Fusion. When you start from the newly saved snapshot, all previous data is loaded, and the newly started session will have 2 GB of available space. {/* links */} [contact]: https://support.seqera.io/ [aws-cloud]: ../compute-envs/aws-cloud [aws-batch]: ../compute-envs/aws-batch [google-cloud]: ../compute-envs/google-cloud [custom-envs]: ./custom-envs [build-status]: ./custom-envs#build-status [cloud-bucket-subdirectory]: ./managing#cloud-bucket-subdirectory [checkpoints]: ./managing#studio-session-checkpoints [resource-labels]: ../troubleshooting_and_faqs/resource-labels [studios-troubleshooting]: ../troubleshooting_and_faqs/studios_troubleshooting [credentials]: ../credentials/overview [ds-jupyter]: https://public.cr.seqera.io/repo/platform/data-studio-jupyter [ds-ride]: https://public.cr.seqera.io/repo/platform/data-studio-ride [def-vsc]: https://code.visualstudio.com/ [Nextflow]: https://nextflow.io/ [nf-lang-server]: https://marketplace.visualstudio.com/items?itemName=nextflow.nextflow [ds-vscode]: https://public.cr.seqera.io/repo/platform/data-studio-vscode [def-xpra]: https://github.com/Xpra-org/xpra [ds-xpra]: https://public.cr.seqera.io/repo/platform/data-studio-xpra [Wave]: https://seqera.io/wave/ [build-status]: ./custom-envs#build-status [add-s]: ./add-studio [conda-syntax]: ./custom-envs#conda-package-syntax [custom-image]: ./custom-envs#custom-containers [connect]: ./connect [liveshare]: https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare [p2p-liveshare]: https://open-vsx.org/extension/kermanx/p2p-live-share --- ## Overview(Studios) Studios provides interactive analysis environments that pair a container image with a compute environment and your preferred tools, such as JupyterLab notebooks, an [R-IDE](https://github.com/seqeralabs/r-ide), Visual Studio Code, or Xpra remote desktops. Each Studio session runs as an individual interactive environment for live data analysis. On Seqera Cloud, the free tier permits only one running Studio session at a time. To run simultaneous sessions, [contact Seqera][contact] for a Seqera Cloud Pro license. - [Container image templates](./container-images): Provided templates for JupyterLab, R-IDE, Visual Studio Code, and Xpra. - [Custom environments](./custom-envs): Augment the Seqera-provided images with Conda packages or your own base container template image. - [Add a Studio](./add-studio): Configuration options for creating, running, and customizing Studio sessions. - [Manage Studios](./managing): Manage Studios and collaborator access. - [Connect changelog](./connect): Release notes for the Seqera Connect client. :::note Studios supports [AWS Cloud][aws-cloud], [Azure Cloud][azure-cloud], [Google Cloud][google-cloud], and [AWS Batch][aws-batch] compute environments that **do not** have Fargate enabled. ::: {/* links */} [aws-cloud]: ../compute-envs/aws-cloud [azure-cloud]: ../compute-envs/azure-cloud [aws-batch]: ../compute-envs/aws-batch [google-cloud]: ../compute-envs/google-cloud [contact]: https://support.seqera.io/ --- ## Tower Agent Tower Agent connects Seqera Platform to high-performance computing (HPC) clusters that do not accept inbound SSH connections. ## When to use the agent Use Tower Agent if your HPC cluster has any of these constraints: - **No public-facing login node.** The cluster is behind a bastion host, VPN, or jump server, with login nodes that have no routable public IP. - **Strict inbound firewall rules.** Security teams allow outbound traffic but block unsolicited inbound connections, including SSH from third parties. - **Multi-factor authentication.** Login requires a hardware token or TOTP. Automated SSH from an external service is impractical. - **Air-gapped or regulated environments.** Clinical, pharmaceutical, and regulated research clusters are often isolated for compliance. - **No shared service accounts.** Some institutions require every job to run under an individual user identity rather than a shared account. If your cluster accepts inbound SSH from Seqera Platform, the standard SSH-based or managed-identity compute environment is simpler to operate (no persistent process to manage). Use Tower Agent when SSH is not an option. ## Connection model The default Seqera Platform HPC model opens an SSH connection to the cluster login node, submits the Nextflow head job, and monitors execution from there. That model requires the cluster to be reachable from the internet. Tower Agent reverses the connection direction. The agent runs on a node that can submit jobs to the scheduler (typically the login node) and opens a persistent outbound authenticated WebSocket connection to Seqera. Seqera sends pipeline commands (submit jobs, check status, stream logs) through that channel. The agent executes them locally as the user who started it. ```mermaid flowchart RL subgraph login["Login node"] direction TB agent["tw-agent"] scheduler["Slurm / LSF / PBS Pro / Grid Engine"] workers["Worker nodes"] agent -->|submits| scheduler scheduler --> workers end login ==>|outbound secure channel| seqera["Seqera Platform(Cloud or Enterprise)"] ``` This approach has three properties: - **Jobs run as you.** The agent submits to the scheduler as the Linux user who launched it. Job accounting, quotas, and audit logs reflect the correct identity, with no shared service account. - **No new firewall rules required.** The cluster only needs outbound HTTPS, the same traffic any browser already makes. - **Credentials stay on the cluster.** SSH keys, Kerberos tickets, and scheduler credentials never leave the cluster. Seqera does not authenticate to your HPC. The agent authenticates locally. Seqera Platform handles pipeline launch, monitoring, logs, resource metrics, and run reports. The agent forwards commands and returns results. ## Connect an HPC cluster Connecting your cluster to Seqera Platform takes six steps: generate an access token, create credentials, install the agent on a login node, start it under tmux, create an HPC compute environment, and launch a pipeline. Complete them in order. :::info[**Prerequisites**] You need the following: - SSH access to a login node, or any node that can submit jobs to your scheduler. - Outbound HTTPS access from that node to `api.cloud.seqera.io`. - A Seqera Platform account with a workspace you can add credentials to. ::: ### Generate a personal access token The agent authenticates to Seqera Platform with a personal access token (PAT) tied to your user account. 1. Log in to Seqera Platform. 2. Open your user menu and select **Your tokens**. 3. Select **Add token**, give it a descriptive name (for example, `hpc-agent-token`), and create it. 4. Copy the token immediately. You cannot view it again after leaving the page. ### Create Tower Agent credentials Create a Tower Agent credential in the workspace where you run pipelines. The agent uses the credential's connection ID to identify itself to Seqera Platform. 1. In your workspace, go to **Credentials** and select **Add credentials**. 2. Select **Tower Agent** as the provider. 3. Enter a name for the credential. 4. Accept the auto-generated **Agent Connection ID** or enter a custom one. Note it down. The ID in the credential must exactly match the ID you pass when starting the agent. 5. To let a single agent serve all workspace members, enable **Shared agent**. For per-user identity on submitted jobs, leave this disabled and ask each user to run their own agent. 6. Select **Add**. ### Install the agent on the login node The agent is a single self-contained binary with no other dependencies to install. 1. SSH into the login node and download the latest agent binary: ```bash curl -fSL https://github.com/seqeralabs/tower-agent/releases/latest/download/tw-agent-linux-x86_64 > tw-agent chmod +x ./tw-agent ``` 2. Optionally, move it to a directory in your `$PATH`: ```bash mkdir -p ~/bin mv tw-agent ~/bin/ ``` 3. Create the default work directory if it does not already exist: ```bash mkdir -p ~/work ``` :::note On most HPC clusters, home directories have small quotas. Use `--work-dir` to point the agent at a scratch filesystem (for example, `/scratch/$USER/nextflow-work`). ::: ### Start the agent inside tmux The agent must run continuously to accept incoming requests from Seqera. If you run it directly in an SSH session and disconnect, the process exits when the session closes. The standard solution on HPC is a terminal multiplexer. Both [tmux](https://github.com/tmux/tmux) and [GNU Screen](https://www.gnu.org/software/screen/) decouple processes from the terminal that started them. Your session runs inside a background server on the login node, and your terminal attaches to that server. If you detach or get disconnected, the session keeps running. SSH back in later and reattach to resume. Start a new tmux session: ```bash tmux new -s tower-agent ``` Inside tmux, export your access token and start the agent with your connection ID: ```bash export TOWER_ACCESS_TOKEN= ./tw-agent ``` When the agent logs that it has connected to Seqera Platform, detach from tmux with **Ctrl-b**, then **d**. You return to the login shell, and the agent keeps running in the background. Verify the session is still active: ```bash tmux ls # tower-agent: 1 windows (created ...) [detached] ``` You can now log out. The agent keeps running. :::tip[tmux quick reference] | Action | Command | |---|---| | Start a new named session | `tmux new -s agent` | | Detach from current session | Ctrl-b then d | | List existing sessions | `tmux ls` | | Reattach to a session | `tmux attach -t agent` | | Kill a session | `tmux kill-session -t agent` | ::: :::note If your site reboots login nodes on a schedule, restart the agent afterwards. Some clusters support systemd user services for persistent processes. Check with your HPC administrators if tmux is not sufficient for your site. ::: ### Create an HPC compute environment Create an HPC compute environment that uses your Tower Agent credential. Seqera routes every pipeline launch in this environment through the agent. In Seqera Platform: 1. Go to **Compute environments** and select **Add compute environment**. 2. Select your HPC scheduler (Slurm, LSF, PBS Pro, or Grid Engine). 3. Under **Credentials**, select the Tower Agent credential you created earlier. 4. Set the work directory to a path the agent can access on the login node. 5. Complete the remaining fields: head queue, compute queue, and any environment variables or run scripts your site requires. 6. Select **Create**. Seqera validates the environment by running a test command through the agent. See [HPC compute environments](../../compute-envs/hpc) for full field descriptions. ### Launch a pipeline Select a pipeline from your workspace **Launchpad**, select your new HPC compute environment, and launch. Seqera sends the launch request to the agent. The agent submits the Nextflow head job to your scheduler, and the head job dispatches tasks to compute nodes. You get the same monitoring, logs, and metrics as any other compute environment. ## Configuration reference ### CLI options Run the agent with a connection ID and any options: ```bash tw-agent [OPTIONS] AGENT_CONNECTION_ID ``` **Parameters** | Parameter | Description | |---|---| | `AGENT_CONNECTION_ID` | Agent connection ID that identifies this agent. Must match the **Agent Connection ID** in the credential. | **Options** | Option | Default | Description | |---|---|---| | `-t`, `--access-token=` | — | Seqera personal access token. Required unless `TOWER_ACCESS_TOKEN` is set. | | `-u`, `--url=` | `https://api.cloud.seqera.io` | Seqera API endpoint URL. If not set, `TOWER_API_ENDPOINT` is used. | | `-w`, `--work-dir=` | `~/work` | Path where pipeline scratch data is stored. You can change it when launching a pipeline. | | `-h`, `--help` | — | Show the help message and exit. | | `-V`, `--version` | — | Print version information and exit. | ### Environment variables The agent reads the following environment variables: | Variable | Description | |---|---| | `TOWER_ACCESS_TOKEN` | Seqera personal access token. Required if `--access-token` is not set. | | `TOWER_API_ENDPOINT` | Seqera API endpoint URL. Defaults to `https://api.cloud.seqera.io`. | | `TOWER_AGENT_HEARTBEAT` | Heartbeat interval in seconds. Defaults to `45`. Reduce this value if your network drops idle connections. | ## Troubleshooting For agent and connection issues, see [Tower Agent troubleshooting](../../troubleshooting_and_faqs/troubleshooting#tower-agent). --- ## Illumina DRAGEN DRAGEN is a platform provided by Illumina that offers accurate, comprehensive, and efficient secondary analysis of next-generation sequencing (NGS) data with a significant speed increase over tools that are commonly used for such tasks. The improved performance offered by DRAGEN is possible due to the use of Illumina proprietary algorithms in conjunction with a special type of hardware accelerator called field programmable gate arrays (FPGAs). For example, when using AWS, FPGAs are available via the [F1 instance type](https://aws.amazon.com/ec2/instance-types/f1/). ## Run DRAGEN on Seqera Platform We have extended the [Batch Forge](../../compute-envs/aws-batch#automatic-configuration-of-batch-resources) feature for AWS Batch to support DRAGEN. Batch Forge ensures that all of the appropriate components and settings are automatically provisioned when creating an AWS Batch compute environment. When deploying data analysis workflows, some tasks will need to use normal instance types (e.g., for non-DRAGEN processing of samples) and others will need to be executed on F1 instances. If the DRAGEN feature is enabled, Batch Forge will create an additional AWS Batch compute queue which only uses F1 instances, to which DRAGEN tasks will be dispatched. ## Get started To showcase the capability of this integration, we have implemented a proof of concept pipeline called [*nf-dragen*](https://github.com/seqeralabs/nf-dragen). To run it, sign into Seqera Platform, navigate to the [Community Showcase](https://tower.nf/orgs/community/workspaces/showcase/launchpad) and select the *nf-dragen* pipeline. You can run this pipeline at your convenience without any extra setup. Note however that it will be deployed in the compute environment owned by the Community Showcase. To deploy the pipeline on your own AWS cloud infrastructure, follow the instructions in the next section. ## Deploy DRAGEN in your own workspace DRAGEN is a commercial technology provided by Illumina, so you will need to purchase a license from them. To run on Seqera, you will need to obtain the following information from Illumina: 1. DRAGEN AWS private AMI ID 2. DRAGEN license username 3. DRAGEN license password Batch Forge automates most of the tasks required to set up an AWS Batch compute environment. See [AWS Batch](../../compute-envs/aws-batch) for more details. In order to enable support for DRAGEN acceleration, simply toggle the **Enable DRAGEN** option when setting up the compute environment via Batch Forge. In the **DRAGEN AMI ID** field, enter the AWS AMI ID provided by Illumina. Then select the instance type from the drop-down. :::note The Region you select must contain DRAGEN F1 instances. ::: ## Using DRAGEN v4.4.4 AMI with F2 instances You can deploy DRAGEN pipelines on Seqera Platform using AWS F2 instances with the DRAGEN v4.4.4 AMI. This enables access to the latest DRAGEN features and improved performance. For Seqera Platform Enterprise, F2 instance support starts from version 25.2.0. ### Configuration steps Before launching the pipeline, you need to add a new library mount in the Nextflow configuration. This is done via **Advanced options > Nextflow config** in the Seqera Platform UI. If you are using Fusion: ``` aws.batch.volumes = '/scratch/fusion:/tmp,/opt/edico,/var/lib/edico,/lib64/libdragen.so.4.4.4' ``` If you are not using Fusion: ``` aws.batch.volumes = '/opt/edico,/var/lib/edico,/lib64/libdragen.so.4.4.4' ``` :::note The DRAGEN v4.4.4 AMI must be selected when configuring your environment. Ensure your AWS Region supports F2 instances and the DRAGEN v4.4.4 AMI. ::: ## Pipeline implementation and deployment See the [dragen.nf](https://github.com/seqeralabs/nf-dragen/blob/master/modules/local/dragen.nf) module implemented in the [nf-dragen](https://github.com/seqeralabs/nf-dragen) pipeline for reference. Any Nextflow processes that run DRAGEN must: 1. Define the `dragen` label in your Nextflow process: The `label` directive allows you to annotate a process with mnemonic identifiers of your choice. Seqera will use the `dragen` label to determine which processes need to be executed on DRAGEN F1 instances. ``` process DRAGEN { label 'dragen' } ``` See the [Nextflow label docs](https://docs.seqera.io/nextflow/process.html?highlight=label#label) for more information. 2. Define secrets in Seqera: At Seqera, we use secrets to safely encrypt sensitive information when running licensed software via Nextflow. This enables our team to use the DRAGEN software safely via the `nf-dragen` pipeline without the need to configure the license key. These secrets will be provided securely to the `--lic-server` option when running DRAGEN on the CLI to validate the license. In the nf-dragen pipeline, we have defined two secrets called `DRAGEN_USERNAME` and `DRAGEN_PASSWORD`, which you can add to Seqera from the [Secrets](../../secrets/overview) tab. ## Limitations DRAGEN integration with Seqera Platform is currently only available for use on AWS, however, we plan to extend the functionality to other supported platforms like Azure in the future. --- ## Fusion v2 file system Fusion v2 is a lightweight container-based client that enables containerized tasks to access data in Amazon S3, Google Cloud, or Azure Blob Storage buckets using POSIX file access semantics. Depending on your data handling requirements, Fusion can improve pipeline throughput and reduce cloud computing costs. See [here](https://docs.seqera.io/fusion) for more information on Fusion's features. ### Fusion mechanics The Fusion file system implements a lazy download and upload algorithm that runs in the background to transfer files in parallel to and from object storage into a container-local temporary folder. This means that the performance of the disk volume used to carry out your computation is key to achieving maximum performance. By default, Fusion uses the container `/tmp` directory as a temporary cache, so the size of the volume can be much lower than the actual needs of your pipeline processes. Fusion has a built-in garbage collector that constantly monitors remaining disk space and deletes old cached entries when necessary. ### Fusion performance and cost considerations Fusion v2 improves pipeline throughput for containerized tasks by simplifying direct access to cloud data storage. Compute instance performance, local storage, and networking influence pipeline execution — the following guidelines are important when creating a compute environment that uses Fusion: - Fusion requires compute instances with attached local storage: - We recommend at least 200 GB storage with a random read speed of 1000 MBps or more. Machines with local disks that do not meet this requirement may encounter issues where local storage cannot keep up with streaming data. - Based on internal benchmarking, we recommend instances with 16 vCPUs and 128 GB memory or more for large, long-lived production pipelines. Seqera benchmarking runs of [nf-core/rnaseq](https://github.com/nf-core/rnaseq) used profile `test_full`, consisting of an input dataset with 16 FASTQ files and a total size of approximately 123.5 GB. - Dedicated networking and fast I/O influence pipeline performance and are important to consider when selecting compute instances. ### Configure Seqera Platform compute environments with Fusion See the compute environment page for your cloud provider for Fusion configuration instructions: - [AWS Batch](../../compute-envs/aws-batch) - [Amazon EKS](../../compute-envs/eks) - [Azure Batch](../../compute-envs/azure-batch) - [Google Cloud Batch](../../compute-envs/google-cloud-batch) - [Google Kubernetes Engine](../../compute-envs/gke) --- ## Developer tools When working with the Seqera Platform API and tw CLI, you might encounter the following issues. ## API #### Maximum results returned ``` {object} length parameter cannot be greater than 100 (current value={value_sent}) ``` This error occurs when you request more results than the maximum page size of 100. To resolve, paginate the results across multiple API calls with the `max` and `offset` parameters: ```bash curl -X GET "https://$TOWER_SERVER_URL/workflow/$WORKFLOW_ID/tasks? workspaceId=$WORKSPACE_ID&max=100" \ -H "Accept: application/json" \ -H "Authorization: Bearer $TOWER_ACCESS_TOKEN" curl -X GET "https://$TOWER_SERVER_URL/workflow/$WORKFLOW_ID/tasks? workspaceId=$WORKSPACE_ID&max=100&offset=100" \ -H "Accept: application/json" \ -H "Authorization: Bearer $TOWER_ACCESS_TOKEN" ``` ## tw CLI #### Connection errors with AWS Batch compute environments Creating or viewing an AWS Batch compute environment that uses the `SPOT_PRICE_CAPACITY_OPTIMIZED` [allocation strategy](../compute-envs/aws-batch#advanced-options) fails on tw CLI versions earlier than v0.8, which don't support it. To resolve, upgrade to CLI v0.9 or later, where this was [addressed](https://github.com/seqeralabs/tower-cli/issues/332). #### Segmentation faults Legacy tw CLI versions can produce segmentation faults on older operating systems. To resolve, upgrade the tw CLI to the latest version. If the fault persists, use the Java [JAR-based build](https://github.com/seqeralabs/tower-cli/releases/download/v0.8.0/tw.jar). #### `You are trying to connect to an insecure server…` ``` ERROR: You are trying to connect to an insecure server: http://hostname:port/api if you want to force the connection use '--insecure'. NOT RECOMMENDED! ``` This error occurs when your Seqera host accepts connections over insecure HTTP instead of HTTPS. To resolve, configure the host to accept HTTPS connections. If it can't, add the `--insecure` flag **before** the CLI command: ```bash tw --insecure info ``` :::caution HTTP must not be used in production environments. ::: #### Relaunch a run Relaunch a run with the [`tw runs relaunch`](../launch/cache-resume#relaunch-a-workflow-run) command: ``` tw runs relaunch -i 3adMwRdD75ah6P -w 161372824019700 Workflow 5fUvqUMB89zr2W submitted at [org / private] workspace. tw runs list -w 161372824019700 Pipeline runs at [org / private] workspace: ID | Status | Project Name | Run Name | Username | Submit Date ----------------+-----------+----------------+-----------------+-------------+------------------------------- 5fUvqUMB89zr2W | SUBMITTED | nf/hello | magical_darwin | seqera-user | Tue, 10 Sep 2022 14:40:52 GMT 3adMwRdD75ah6P | SUCCEEDED | nf/hello | high_hodgkin | seqera-user | Tue, 10 Sep 2022 13:10:50 GMT ``` --- ## AWS When running pipelines on AWS, you might encounter the following issues. ## Elastic Block Store (EBS) #### Volumes remain active after job completion On large AWS Batch clusters (hundreds of compute nodes or more), EC2 API rate limits can cause the automatic deletion of unattached EBS volumes to fail. Orphaned volumes that remain after jobs complete incur additional costs. EBS autoscaling relies on an AWS-provided script on each container host that calls the EC2 API to delete each volume when its job finishes. When deletion fails, find orphaned volumes in the EC2 console or with a Lambda function and delete them manually. See [Controlling your AWS costs by deleting unused Amazon EBS volumes](https://aws.amazon.com/blogs/mt/controlling-your-aws-costs-by-deleting-unused-amazon-ebs-volumes/). ## Elastic Container Service (ECS) #### ECS agent Docker image pull frequency When Batch Forge creates an AWS Batch environment, it sets the ECS agent's `ECS_IMAGE_PULL_BEHAVIOUR` in the EC2 launch template: - Seqera Enterprise v22.01 or later: `once` - Seqera Enterprise v21.12 or earlier: `default` See the [AWS ECS documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html) for the difference between these values. :::note This behavior can't be changed within Seqera Platform. ::: ## Container errors #### `CannotPullContainerError … "Too Many Requests (HAP429)"` ``` CannotPullContainerError: Error response from daemon: error parsing HTTP 429 response body: invalid character 'T' looking for beginning of value: "Too Many Requests (HAP429)" ``` This error occurs when you exceed Docker Hub's rate limit of 100 anonymous pulls per 6 hours. To resolve, add the following to your launch template: ```bash echo ECS_IMAGE_PULL_BEHAVIOR=once >> /etc/ecs/ecs.config ``` #### `CannotInspectContainerError` ``` Essential container in task exited - CannotInspectContainerError: Could not transition to inspecting; timed out after waiting 30s ``` To resolve: 1. Upgrade your [ECS agent](https://github.com/aws/amazon-ecs-agent/releases) to [1.54.1](https://github.com/aws/amazon-ecs-agent/pull/2940) or later. See [Check for ECS Container Instance Agent Version](https://www.trendmicro.com/cloudoneconformity/knowledge-base/aws/ECS/latest-agent-version.html) to check your version. 2. Provision more storage for your EC2 instance, preferably with EBS autoscaling for scalability. 3. If the error includes `command exit status: 123` and a permissions-denied error on a system command, make the ECS agent binary executable (`chmod u+x`). ## Queues #### Distribute tasks across multiple AWS Batch queues You can identify only a single work queue when you define an AWS Batch compute environment, but you can distribute tasks across multiple queues in your pipeline configuration. Add a snippet like the following to your `nextflow.config`, or the **Advanced options > Nextflow config file** field of the launch form, to distribute processes across two queues by name: ```groovy # nextflow.config process { withName: foo { queue: `TowerForge-1jJRSZmHyrrCvCVEOhmL3c-work` } } process { withName: bar { queue: `custom-second-queue` } } ``` ## GPUs #### `CUDA safe call. System has unsupported display driver / CUDA driver combination` ``` CUDA safe call. System has unsupported display driver / CUDA driver combination exiting ``` This error occurs when the container's CUDA runtime is newer than the NVIDIA driver on the compute environment's AMI. To resolve, do one of the following: - Update the AMI to one with a newer NVIDIA driver. Use the latest AWS-recommended GPU-optimized ECS AMI (the default when **Enable GPUs** is set), or build a custom AMI with a driver version that meets the container's CUDA requirement. See the [NVIDIA CUDA compatibility matrix](https://docs.nvidia.com/deploy/cuda-compatibility/) for the minimum driver version. - Pin the container to a supported CUDA version. Use a container image built against a CUDA runtime the installed driver supports. NVIDIA Parabricks, for example, publishes image tags for each CUDA version. Select one that matches the AMI's driver. To confirm the active driver on a failed task, see the **Driver version** field in [GPU metrics](../compute-envs/overview#gpu-metrics). ## Spot instances **Tasks fail with exit code `143`, or no exit code, and the log contains `Host EC2 (instance i-xxxxxxxxx) terminated`** AWS reclaimed the Spot instance running the task. See [Manage AWS Spot interruptions](../compute-envs/aws-spot-interruptions) for retry and fallback strategies. ## Storage #### Write to S3 buckets that enforce AES256 server-side encryption :::note Requires Seqera v21.10.4 and Nextflow [22.04.0](https://github.com/nextflow-io/nextflow/releases/tag/v22.04.0) or later. ::: To save files to an S3 bucket with a policy that [enforces AES256 server-side encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html), configure the [nf-launcher](https://quay.io/repository/seqeralabs/nf-launcher?tab=tags) script that invokes the Nextflow head job: 1. Add the following to the **Advanced options > Nextflow config file** field of the **Launch Pipeline** screen: ```groovy aws { client { storageEncryption = 'AES256' } } ``` 2. Add the following to the **Advanced options > Pre-run script** field: ```bash export TOWER_AWS_SSE=AES256 ``` --- ## Azure When running pipelines on Azure, you might encounter the following issues. ## Batch compute environments #### Use separate Batch pools for head and compute nodes :::warning After September 30, 2025 low-priority VMs are only available in user subscription pool allocation mode Batch accounts. See the [Microsoft migration guide](https://learn.microsoft.com/en-us/azure/batch/low-priority-vms-retirement-migration-guide). ::: The default Azure Batch implementation in Seqera Platform uses a single pool for head and compute nodes, and all jobs spawn dedicated (on-demand) VMs. To save costs by running compute jobs on low-priority VMs, use separate pools for head and compute jobs: 1. Create two Batch pools in Azure: - One dedicated pool - One [low-priority](https://learn.microsoft.com/en-us/azure/batch/batch-spot-vms#differences-between-spot-and-low-priority-vms) pool :::note Both pools must meet the requirements of a pre-existing pool, as detailed in the [Nextflow documentation](https://docs.seqera.io/nextflow/azure#requirements-on-pre-existing-named-pools). ::: 2. Create a manual [Azure Batch](../compute-envs/azure-batch#manual) compute environment in Seqera Platform. 3. In **Compute pool name**, specify your dedicated Batch pool. 4. Specify the low-priority pool with the `process.queue` [directive](https://docs.seqera.io/nextflow/process#queue) in your `nextflow.config` file, either through the launch form or your pipeline repository. ## Azure Kubernetes Service (AKS) #### `.../.git/HEAD.lock: Operation not supported` This error occurs when your Nextflow pod uses an Azure Files (SMB) persistent volume for storage. The `jgit` library that Nextflow uses attempts a filesystem link operation that Azure Files (SMB) [doesn't support](https://docs.microsoft.com/en-us/azure/storage/files/files-smb-protocol?tabs=azure-portal#limitations). To resolve, add the following to your pipeline's [**Pre-run script**](../launch/advanced#pre-and-post-run-scripts) field: ```bash cat < ~/.gitconfig [core] supportsatomicfilecreation = true EOT ``` ## SSL #### SSL CA certificate errors This can occur when a tool or library in your task container requires SSL certificates to validate an external data source. To resolve, mount the SSL certificates into the container. #### `Connections using insecure transport are prohibited while --require_secure_transport=ON` This Azure SQL database error occurs because Azure's default MySQL configuration enforces SSL connections between the server and client, as described in [SSL/TLS connectivity in Azure Database for MySQL](https://learn.microsoft.com/en-us/azure/mysql/single-server/concepts-ssl-connection-security). To resolve, append `useSSL=true&enabledSslProtocolSuites=TLSv1.2&trustServerCertificate=true` to your `TOWER_DB_URL` connection string: ``` TOWER_DB_URL: jdbc:mysql://mysql:3306/tower?permitMysqlScheme=true/azuredatabase.com/tower?serverTimezone=UTC&useSSL=true&enabledSslProtocolSuites=TLSv1.2&trustServerCertificate=true ``` --- ## Datasets(Troubleshooting_and_faqs) When working with datasets, you might encounter the following issues. ## Common issues #### Dataset upload fails with the API When you upload a dataset through the Seqera UI or CLI, Seqera performs some steps automatically. Uploading through the API requires two additional steps: 1. Explicitly define the MIME type of the file you upload. 2. Make two API calls: first create a dataset object, then upload the samplesheet to it. Create the dataset object: ```bash curl -X POST "https://api.cloud.seqera.io/workspaces/$WORKSPACE_ID/datasets/" -H "Content-Type: application/json" -H "Authorization: Bearer $TOWER_ACCESS_TOKEN" --data '{"name":"placeholder", "description":"A placeholder for the data we will submit in the next call"}' ``` Upload the samplesheet to the dataset object: ```bash curl -X POST "https://api.cloud.seqera.io/workspaces/$WORKSPACE_ID/datasets/$DATASET_ID/upload" -H "Accept: application/json" -H "Authorization: Bearer $TOWER_ACCESS_TOKEN" -H "Content-Type: multipart/form-data" -F "file=@samplesheet_full.csv; type=text/csv" ``` :::tip You can also upload a dataset to a workspace with the [`tw` CLI](https://github.com/seqeralabs/tower-cli): ```bash tw datasets add --name "cli_uploaded_samplesheet" ./samplesheet_full.csv ``` ::: #### Datasets converted to `application/vnd.ms-excel` data type ``` "Given file is not a dataset file. Detected media type: 'application/vnd.ms-excel'. Allowed types: 'text/csv, text/tab-separated-values'" ``` This issue occurs in Firefox on Seqera versions earlier than 22.2.0. To resolve, upgrade to 22.2.0 or later, or use Chrome. #### TSV-formatted datasets not shown In Seqera version 22.2, TSV datasets were unavailable in the input data drop-down on the launch form. This was fixed in version 22.4.1. --- ## Nextflow When running Nextflow pipelines with Seqera Platform, you might encounter the following issues. ## Nextflow configuration #### Default Nextflow DSL version From [Nextflow 22.03.0-edge](https://github.com/nextflow-io/nextflow/releases/tag/v22.03.0-edge), DSL2 is the default syntax. To minimize disruption to existing pipelines, versions 22.1.x and later default Nextflow head jobs to DSL1 for a transition period (end date to be confirmed). Force your Nextflow head job to use DSL2 syntax with one of the following: - Add `export NXF_DEFAULT_DSL=2` in the **Advanced options > Pre-run script** field of the launch form. - Specify `nextflow.enable.dsl = 2` at the top of your Nextflow workflow file. - Provide the `-dsl2` flag when you invoke the Nextflow CLI, for example `nextflow run ... -dsl2`. #### Invoke Nextflow CLI run arguments during launch From [Nextflow v22.09.1-edge](https://github.com/nextflow-io/nextflow/releases/tag/v22.09.1-edge), you can specify [Nextflow CLI run arguments](https://docs.seqera.io/nextflow/cli.html?highlight=dump#run) when you launch a pipeline from Seqera. Set the `NXF_CLI_OPTS` environment variable in a [pre-run script](../launch/advanced#pre-and-post-run-scripts): ```bash export NXF_CLI_OPTS='-dump-hashes' ``` #### Cloud execution: `--outdir` artifacts not available Nextflow resolves relative paths against the current working directory. On a classic grid HPC, this is usually a subdirectory of `$HOME`. In a cloud execution environment, the path resolves relative to the _container file system_. Output files are lost when the container terminates. See [this Nextflow issue](https://github.com/nextflow-io/nextflow/issues/2661#issuecomment-1047259845) for details. To resolve, specify the absolute path to your persistent storage with the `NXF_FILE_ROOT` environment variable in your [`nextflow.config`](../launch/advanced#nextflow-config-file) file. Nextflow then resolves relative paths so that output files are written to persistent storage rather than ephemeral container storage. #### Ignore the Singularity cache To ignore the Singularity cache, add this to your workflow: `process.container = 'file:///some/singularity/image.sif'`. #### `Cannot read project manifest … path=nextflow.config` This warning occurs when the source Git repository's default branch does not contain `main.nf` and `nextflow.config` files, regardless of whether the pipeline uses a non-default revision or branch (e.g., `dev`). To resolve, create empty `main.nf` and `nextflow.config` files in the default branch. The pipeline can then run and use the `main.nf` and `nextflow.config` from your target revision. #### Use multiple configuration files for different environments The main `nextflow.config` file is always imported by default. Instead of managing multiple `nextflow.config` files, each customized for an environment, create environment-specific config files and import them as [config profiles](https://docs.seqera.io/nextflow/config#config-profiles) in the main `nextflow.config`: ```groovy profiles { test { includeConfig 'conf/test.config' } prod { includeConfig 'conf/prod.config' } uat { includeConfig 'conf/uat.config' } } ``` #### AWS S3 upload file size limits You might see the following message in your Nextflow log: ``` WARN: Failed to publish file: s3:// ``` These messages are often caused by AWS S3 object size limits when using multipart upload. See the [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html), particularly _maximum number of parts per upload_. To resolve, adjust the head job resources and configuration: - Head Job CPUs: 16 - Head Job Memory: 60000 - [Pre-run script](../launch/advanced#pre-and-post-run-scripts): `export NXF_OPTS="-Xms20G -Xmx40G"` - Increase the chunk size and slow the transfers in `nextflow.config`: ```groovy aws { batch { maxParallelTransfers = 5 maxTransferAttempts = 3 delayBetweenAttempts = 30 } client { uploadChunkSize = '200MB' maxConnections = 10 maxErrorRetry = 10 uploadMaxThreads = 10 uploadMaxAttempts = 10 uploadRetrySleep = '10 sec' } } ``` #### Nextflow cannot parse a params file ``` Cannot parse params file: /ephemeral/example.json - Cause: Server returned HTTP response code: 403 for URL: https://api.tower.nf/ephemeral/example.json ``` Ephemeral endpoints can be consumed only once. Nextflow versions earlier than 22.04 can call the same endpoint more than once, which causes this error. To resolve, upgrade Nextflow to version 22.04.x or later. #### Prevent uploading intermediate files to the AWS S3 work directory Nextflow only unstages files and folders that you explicitly define as process outputs. If your workflow has processes that generate folder-type outputs, ensure each process also purges any intermediate files in those folders. Otherwise, Nextflow copies the intermediate files during task unstaging. This adds storage costs and lengthens execution times. #### Values in the repository `nextflow.config` change during launch Some values in your pipeline repository's `nextflow.config` can change when the pipeline is launched from Seqera, because Seqera applies a set of default values that override the pipeline configuration. For example, this block is specified in your `nextflow.config`: ```groovy aws { region = 'us-east-1' client { uploadChunkSize = 209715200 // 200 MB } ... } ``` When the job starts on the AWS Batch compute environment, `uploadChunkSize` changes: ```groovy aws { region = 'us-east-1' client { uploadChunkSize = 10485760 // 10 MB } ... } ``` This happens because Seqera applies its 10 MB default instead of the value in your `nextflow.config`. To force the Seqera-invoked job to use your value, add the setting in the workspace launch form's [**Nextflow config file** field](../launch/launchpad). For the example above, add `aws.client.uploadChunkSize = 209715200 // 200 MB`. Values affected by this behavior include: - `aws.client.uploadChunkSize` - `aws.client.storageEncryption` #### `Missing output file(s) [X] expected by process [Y]` with Fusion v1 Fusion v1 causes tasks that run for less than 60 seconds to fail, because Nextflow doesn't yet detect the output file the task generated. This limitation is inherited from the Goofys driver used in the Fusion v1 implementation. [Fusion v2](../supported_software/fusion/overview.md) resolves this issue. If you can't update to Fusion v2, instruct Nextflow to wait 60 seconds after the task completes. In **Pipeline settings > Advanced options > Nextflow config file**, add: ```groovy process.afterScript = 'sleep 60' ``` #### Jobs remain in RUNNING status after canceling a run Your instance's behavior when you cancel a run depends on the Nextflow [`errorStrategy`](https://docs.seqera.io/nextflow/process#errorstrategy) defined in your process script. If `errorStrategy` is set to `finish`, canceling (or otherwise interrupting) a run starts an orderly shutdown, which instructs Nextflow to wait for submitted jobs to complete. To terminate all jobs when you cancel a run, set `errorStrategy` to `terminate` in your Nextflow config: ```groovy process terminateError { errorStrategy 'terminate' script: } ``` #### Cached tasks run from scratch on relaunch When you relaunch a pipeline, Seqera relies on Nextflow's `resume` functionality to continue the execution. This skips previously completed tasks and uses cached results in downstream tasks, rather than running the completed tasks again. Nextflow calculates each task's unique ID (hash) from the task's: - Input values - Input files - Command line string - Container ID - Conda environment - Environment modules - Any executed scripts in the bin directory A change in any of these values changes the task hash, and a changed hash means the task runs again on relaunch. To debug an unexpected relaunch, run the pipeline twice with `dumpHashes=true` set in your Nextflow config file (**Advanced options > Nextflow config file** in the pipeline settings). Nextflow then dumps the task hashes for both executions in the `nextflow.log` file. Compare the log files to find where the hashes diverge. See [Demystifying Nextflow resume](https://www.nextflow.io/blog/2019/demystifying-nextflow-resume.html) for more on the `resume` mechanism. #### `Incorrect string value` ``` [scheduled-executor-thread-2] - WARN o.h.e.jdbc.spi.SqlExceptionHelper - SQL Error: 1366, SQLState: HY000 [scheduled-executor-thread-2] - ERROR o.h.e.jdbc.spi.SqlExceptionHelper - (conn=34) Incorrect string value: '\xF0\x9F\x94\x8D |...' for column 'error_report' at row 1 [scheduled-executor-thread-2] - ERROR i.s.t.service.job.JobSchedulerImpl - Unable to save status of job id=18165; name=nf-workflow-26uD5XXXXXXXX; opId=nf-workflow-26uD5XXXXXXXX; status=UNKNOWN ``` Runs fail when your Nextflow script or config contains illegal characters, such as emojis or other non-UTF8 characters. To resolve, validate your script and config files for illegal characters before you run again. #### Run fails: Nextflow script exceeds 64 KiB The Groovy shell that Nextflow uses to execute your workflow has a hard limit on string size (64 KiB). Check the size of your scripts with `ls -llh`. If a script is larger than 65,535 bytes, consider these mitigations: 1. Remove unnecessary code or comments from the script. 2. Move long script bodies into a separate script file in the pipeline `/bin` directory. 3. Use DSL2 so you can move each function, process, and workflow definition into its own script and include them as [modules](https://docs.seqera.io/nextflow/module). ## Nextflow Launcher #### nf-launcher image compatibility Your Seqera installation knows the [nf-launcher image](https://quay.io/repository/seqeralabs/nf-launcher?tab=tags) version it needs and sets this value automatically when launching a pipeline. If you're restricted from using public container registries, see Seqera Enterprise release [instructions](https://docs.seqera.io/changelog/seqera-enterprise/v25.1) for the specific image to set as the default when invoking pipelines. #### Specify the Nextflow version Each Seqera Platform release uses a specific nf-launcher image by default. This image is loaded with a specific Nextflow version that any workflow in the container uses by default. To run a job with a different Nextflow version, use the [**Nextflow version**](../launch/advanced#nextflow-version) selector in the pipeline or launch advanced options. Setting `NXF_VER` in a pre-run script or the pipeline configuration is no longer recommended; a value set there overrides the selector. ## Spot instance failures and retries Up to version 24.10, Nextflow silently retried Spot instance failures up to five times on AWS Batch and Google Batch. These retries were controlled by cloud-specific configuration parameters (e.g., `aws.batch.maxSpotAttempts`) and happened in cloud infrastructure without explicit visibility to Nextflow. From version 24.10, the default Spot reclamation retry setting changed to `0` on AWS and Google. By default, no _internal_ retries are attempted on these platforms. Spot reclamations now cause an immediate failure, exposed to Nextflow like any other generic failure (returning, for example, `exit code 1` on AWS). Nextflow treats these failures like any other job failure unless you configure a retry strategy. #### Impact on existing workflows If you rely on silent Spot retries (the previous default), you might now see more tasks fail with these characteristics: - **AWS**: Generic failure with `exit code 1`. You might see messages indicating the host machine was terminated. - **Google**: Spot reclamation typically produces a specific code, but is now surfaced as a recognizable task failure in Nextflow logs. Because the default for Spot retries is now zero, you must enable a retry strategy for Nextflow to handle reclaimed Spot instances automatically. For more information, see the [Spot Instance failures and retries](https://docs.seqera.io/nextflow/updating-spot-retries) guide. ## Nextflow syntax parser Up to version 25.10, Nextflow uses the v1 syntax parser (also known as the legacy parser) by default. The v2 parser introduces stricter validation and is available as an opt-in through `NXF_SYNTAX_PARSER=v2`. From version 26.04, Nextflow uses the v2 syntax parser by default. Pipelines that run without modification under the v1 parser can fail under v2. #### Pin the v1 parser To run existing pipelines unchanged under Nextflow 26, set `NXF_SYNTAX_PARSER` to `v1` in a [pre-run script](../launch/advanced#pre-and-post-run-scripts): ```bash export NXF_SYNTAX_PARSER=v1 ``` This restores the legacy parser behavior. For migration guidance to the v2 parser, see [Preparing for strict syntax](https://docs.seqera.io/nextflow/strict-syntax). --- ## Resource labels(Troubleshooting_and_faqs) When working with resource labels on AWS, Azure, and Google Cloud, you might encounter the following issues. ## Common issues #### Tags not appearing in cost reports Resource labels are applied to your cloud resources but don't appear in your provider's cost reporting tools. This is usually a propagation delay or a cost-reporting configuration gap. To resolve: - Allow up to 24 hours for tags to appear in the AWS cost allocation console. - For Azure, enable tag inheritance and allow 24 hours for processing. - Verify that resources are actively running and generating usage data. #### Permission errors Tagging fails, or cost data is inaccessible, when the credentials associated with the compute environment lack tagging or billing permissions. To resolve: - Ensure the compute environment credentials have the permissions required to tag resources. - For Google Cloud, verify billing account administrator access. - For Azure, confirm billing profile contributor permissions and permissions to view Cost Management reports. #### Missing tag values in cloud provider resources Resources launch without the expected tags, or dynamic label values are empty. This usually means the labels aren't attached to the compute environment the workflow ran on. To resolve: - Verify that resource labels are applied to the correct compute environment. - Check that workflows use the tagged compute environment. - For dynamic resource labels, ensure variables use the correct syntax: `${sessionId}`, `${userName}`, or `${workflowId}`. #### Costs missing for manually created AWS Batch queues Costs for some AWS Batch runs never appear in Cost Explorer or your data exports, even though resource labels are applied. This happens when the compute environment or job queue was created manually, outside of Batch Forge, and so doesn't inherit Seqera's cost-allocation tags. To resolve: - Add the relevant cost-allocation tag (for example, `project=`) to the manually created compute environments, job queues, and related resources in the AWS console. - Prefer Batch Forge-created compute environments where possible, so tags propagate automatically. #### Cost data missing from the AWS data export Resource labels are applied and cost-allocation tags are activated, but split or unblended cost fields are missing or show zero in your data export. To resolve: - Confirm that the cost-allocation tag keys are activated in the **AWS Billing and Cost Management console** of the payer (billing) account. - Enable [split cost allocation data](https://docs.aws.amazon.com/cur/latest/userguide/enabling-split-cost-allocation-data.html) in your Cost and Usage Report preferences — without it, downstream reporting returns blended-only or zero values. - Allow a 24–48 hour delay for cost data to appear, then inspect the export (for example, query the Parquet files with Amazon Athena) to confirm the tag keys and their costs are present. #### Resource label tag keys look different in the AWS Cost and Usage Report Tag keys or values in the AWS Cost and Usage Report (CUR) don't match the resource labels you applied, breaking Athena or QuickSight queries. This is expected CUR normalization: in CUR (version 2), colons (`:`) are rewritten as underscores (`_`), and mixed- or upper-case characters are lowercased and separated with underscores (for example, `costCenter` becomes `cost_center`). To resolve: - Design resource-label keys and values that remain unambiguous after normalization. - Reference the normalized key names in your downstream Athena or QuickSight queries. --- ## Co-Scientist When installing or authenticating the Seqera CLI, you might encounter the following issues. ## Installation #### `seqera: command not found` If you see `seqera: command not found` after installation: 1. Verify the Seqera CLI installation location: ```bash which seqera ``` 1. Ensure the npm global `bin` directory is on your PATH. Find it with `npm config get prefix` or `npm bin -g`: ```bash # Check the npm global bin directory npm bin -g # Restart your terminal or run source ~/.bashrc # or ~/.zshrc ``` 1. If you installed the standalone binary, verify it is in a directory on your PATH: ```bash echo $PATH ``` #### npm permission errors If you encounter permission errors during installation: 1. Use the npm prefix option to install to a user-writable directory: ```bash npm install -g seqera --prefix ~/.npm-global ``` 1. Add the directory to your PATH: ```bash export PATH="$HOME/.npm-global/bin:$PATH" ``` #### `EACCES` permission errors on global install Avoid running `sudo npm install`. Either [fix npm permissions](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) or install Node through a version manager such as [nvm](https://github.com/nvm-sh/nvm). ## Authentication #### Browser doesn't open If the browser doesn't open automatically: 1. Check the terminal output for a URL. 1. Copy and paste the URL into your browser. 1. Complete authentication in the browser. #### Login timeout If authentication times out: 1. Ensure you have internet connectivity. 1. Check that `https://seqera.io` is accessible. 1. Log out and log in again. #### Token storage errors If you see errors related to credential storage: 1. Check that you have write permissions to `~/.config/seqera-ai/`: ```bash ls -la ~/.config/seqera-ai/ ``` 1. If the directory doesn't exist, create it: ```bash mkdir -p ~/.config/seqera-ai ``` #### Session expired If your session has expired, log out and log in again: ```bash seqera logout seqera login ``` --- ## Single sign-on These issues can occur when you configure or use [single sign-on (SSO)](../sso/single-sign-on) with your organization's corporate identity provider (IdP). ## Common issues #### Domain claiming is blocked Seqera blocks domain claiming when the organization has members with email addresses outside the claimed domain or existing workspace collaborators. The setup flow lists the affected users. To resolve, see [Prepare users before setup](../sso/single-sign-on#prepare-users-before-setup). #### The claimed domain is rejected or becomes unclaimable Another organization might already have claimed the domain, or enabled a connection with the same domain claim after you claimed it. Contact Seqera support. #### Domain verification fails or doesn't complete During [domain verification](../sso/single-sign-on#verify-your-domain), Auth0 can't verify the claimed domain, or the check stays pending. This issue occurs when the TXT record is missing or incorrect, or when DNS changes haven't propagated. To resolve: - Confirm that the TXT record uses the correct host or name, and that the **Record Value** matches the value from the Auth0 wizard. - Allow up to 48 hours for DNS propagation. - Confirm that the record is live with a DNS lookup, for example `dig TXT `. #### Users are not redirected to the corporate IdP Confirm that SSO is enabled for the organization and that the user's email domain matches the claimed domain. #### An IdP user can't sign in Confirm that the user has access to the application or connection configured in your IdP and that the user's email domain matches the domain claimed in Seqera. #### An existing user sees a linking problem during sign-in If Seqera can't link an existing account to the SSO identity, the user should contact an organization owner or Seqera support before trying again. ## IdP group provisioning (SCIM) #### Groups appear in the IdP but not in Seqera Confirm the bearer token configured in your IdP matches the latest token that Seqera issued. If you generated a new token after configuring the IdP, the previous token is revoked. #### `401 Unauthorized` in IdP provisioning logs The bearer token is invalid or expired. Generate a new token from **Organization settings > Group mapping** in Platform and replace it in the IdP. #### The catalog shows GUID-style identifiers instead of group names (Entra ID) Entra ID is emitting object IDs rather than display names. See [Group display names vs. object IDs](../sso/idp-delegation/group-catalog/scim-entra-id#group-display-names-vs-object-ids) for the two options. #### A group is assigned to the application but doesn't sync (Entra ID) Confirm the provisioning scope is set to **Sync only assigned users and groups**, and that the group is listed directly under **Users and groups** rather than nested inside another assigned group. --- ## Studios(Troubleshooting_and_faqs) When working with Studios, you might encounter the following issues. ## Sessions ### Session is stuck in **starting** If your Studio session doesn't advance from **starting** status to **running** status within 30 minutes, and you are a **Maintain** role or higher, select the three dots next to the status message for the Studio you want to stop, then select **Stop**. If you are not a **Maintain** or higher user but you have access to the AWS Console for your organization, check that the AWS Batch compute environment associated with the session is in the **ENABLED** state with a **VALID** status. You can also check the **Compute resources** settings. Contact your organization's AWS administrator if you don't have access to the AWS Console. If sufficient compute resources aren't available, select **Stop** for the session and any others that are running before trying again. If you have access to the AWS Console for your organization, you can terminate a specific session from the AWS Batch Jobs page (filtering by compute environment queue). ### Session is stuck in **stopping** If your Studio session doesn't advance from **stopping** status to **stopped** status within 10 minutes, select **Force stop** to skip the intermediate **canceling** status. Checkpoint revalidation restores your data when the session next starts. ### Session status is **errored** The `errored` status is generally related to problems creating the Studio session resources in the compute environment, such as invalid credentials, insufficient permissions, or network issues. It can also be related to insufficient compute resources set in your compute environment configuration. Contact your organization's AWS administrator if you don't have access to the AWS Console, and contact your Seqera account executive to investigate. ### Session can't be **stopped** If you can't stop a session, the Batch job running the session usually failed. If you have access to the AWS Console for your organization, stop the session from the compute environment screen. Contact your organization's AWS administrator if you don't have access to the AWS Console, and contact your Seqera account executive to investigate. ### Session performance is poor A slow or unresponsive session might be caused by its AWS Batch compute environment being used for other jobs, such as running Nextflow pipelines. The compute environment schedules jobs to the available compute resources. Sessions compete for resources with the Nextflow pipeline head job. Seqera does not currently give either precedence. If you have access to the AWS Console for your organization, check the jobs associated with the AWS Batch compute environment and compare the resources allocated with its **Compute resources** settings. ### Memory allocation of the session is exceeded The running container in the AWS Batch compute environment inherits the memory limits specified by the session configuration when adding or starting the session. The kernel then handles the memory as if running natively on Linux. Linux can overcommit memory, leading to possible out-of-memory errors in a container environment. The kernel has protections to prevent this, but when it happens, the kernel kills the process. This can manifest as a performance lag, killed subprocesses, or at worst, a killed session. Seqera creates automated snapshots of running sessions every five minutes. If the running container is killed, you lose only the changes made after the prior snapshot. ### Session with GPUs doesn't start Check whether the instance type you selected [supports GPU](https://aws.amazon.com/ec2/instance-types/). If you specify multiple GPUs, make sure that your compute environment can launch multi-GPU instances and that your maximum CPU configuration doesn't limit them. ### RStudio session initializes with error Connecting to a running RStudio session with R version 4.4.1 (2024-06-14) -- "Race for Your Life" returns a `[rsession-root]` error similar to the following: ``` ERROR system error 2 (No such file or directory) [path:/sys/fs/cgroup/memory/memory.limit_in_bytes]; OCCURRED AT rstudio::core::Error rstudio::core::FilePath::openForRead(std::shared_ptr >&) ... ``` You can safely ignore this error. It appears because logging is set to `stderr` by default so that all logs are shown during the session. **When starting an existing Studio session, extra processes are not automatically restarted** A process you start manually in a running Studio session (e.g., `eval $(ssh-agent)`) is not automatically restarted when the Studio restarts, because the Connect client does not manage user-initiated daemon processes. Automatically starting extra processes on each Studio restart would require a user-defined startup script or an integrated supervisor such as `s6`, `s6-overlay`, or `supervisord`, none of which are currently supported. ## Compute environments ### Session size limited by head job CPUs and memory When you add a compute environment, the Advanced options **Head job CPUs** and **Head job memory** for Nextflow also apply to any Studio session created in the compute environment, because the Nextflow runner job manages Studio sessions. To avoid constraining the resources of your Studio sessions, don't define these optional settings. ### New compute environment doesn't appear in the drop-down when migrating a Studio When [migrating a Studio to a different compute environment](../studios/managing#migrate-a-studio-between-compute-environments), the **Compute environment** drop-down filters out any compute environment that isn't compatible with the Studio's current one. Confirm the new compute environment is in the `AVAILABLE` status and uses the same `workDir` as the Studio's current compute environment. ### Studio fails to start after switching compute environments The new compute environment's [credentials](../credentials/overview) must have read and write access to the `workDir` bucket. Confirm they have the required S3 permissions on the checkpoint location. ### Resource labels change after switching compute environments When you switch a Studio to a different compute environment, labels inherited from the previous compute environment are removed and the new compute environment's labels are added automatically. If you need a label that was tied to the old compute environment, attach it to the Studio directly so that it survives future compute environment switches. See [Resource label changes](../studios/managing#resource-labels-on-migration). ## Data and storage ### All datasets are read-only By default, AWS Batch compute environments created with Batch Forge restrict S3 access to the working directory only, unless you specify additional **Allowed S3 Buckets**. If the compute environment does not have write access to the mounted dataset, the dataset is mounted as read-only. ### Running session does not show new data in object storage By default, Fusion does not resync objects from remotely mounted data-link(s) after initial mounting. If you have a running session with data mounted and the underlying storage is updated, the data is not resynced to the Studio session. You can change this behavior when you [add a Studio session](../studios/add-studio) by setting the `FUSION_REFRESH_TIMEOUT` environment variable to a number of seconds (e.g., `120`). Fusion refreshes the view of the mounted data links at that interval. :::note Setting the environment variable _inside_ an already running Studio session by executing the command `export FUSION_REFRESH_TIMEOUT=120` won't change the behavior of the outer Fusion session. Set the environment variable in the **General config** section during Studio creation. ::: :::warning Fusion waits two minutes before it uploads the working chunk. Always set `FUSION_REFRESH_TIMEOUT` to `120` or higher. Lower values can create orphaned chunks in the Studio environment that are never uploaded to object storage and cannot be recovered. ::: ## Custom environments and container images ### Failed custom environment rebuilds use the cached image Building a custom Studios image with the Wave service occasionally fails, typically because of conflicting libraries. If you rebuild the image with the same name and tag, Studios and Wave use the cached version if available. Change the version number or tag to pull a fresh image. The Elastic Container Service (ECS) agent's `ECS_IMAGE_PULL_BEHAVIOR` environment variable determines this behavior. In Seqera Platform Cloud, it is set to `once` when the compute environment is created. Enterprise installations might be configured differently. Contact your organization's administrator to learn more. ### Container template image security scan false positives When you run a software composition analysis (SCA) security scan (e.g., with Trivy) on the latest Seqera-provided VS Code image [container template](../studios/container-images), you might encounter multiple false-positive findings. VS Code defines extensions in a way that can cause some security scanners to incorrectly identify them as `npm` packages. This is a known limitation, discussed in the Trivy community [discussion](https://github.com/aquasecurity/trivy/discussions/6112). These are the false positive confirmed findings: | Component | Vulnerability id⁠ | | :--------------- | :------------------- | | handlebars:1.0.0 | CVE-2021-23383⁠ | | handlebars:1.0.0 | CVE-2021-23369⁠ | | handlebars:1.0.0 | CVE-2019-19919⁠ | | handlebars:1.0.0 | GHSA-q42p-pg8m-cqh6 | | handlebars:1.0.0 | GHSA-q2c6-c6pm-g3gh⁠ | | handlebars:1.0.0 | GHSA-g9r4-xpmj-mj65⁠ | | handlebars:1.0.0 | GHSA-2cf5-4w76-r9qv⁠ | | handlebars:1.0.0 | CVE-2019-20920⁠ | | handlebars:1.0.0 | CVE-2015-8861⁠ | | handlebars:1.0.0 | GMS-2015-33⁠ | | npm:1.0.1 | CVE-2019-16777⁠ | | npm:1.0.1 | CVE-2019-16776⁠ | | npm:1.0.1 | CVE-2019-16775⁠ | | npm:1.0.1 | CVE-2018-7408⁠ | | npm:1.0.1 | CVE-2016-3956⁠ | | npm:1.0.1 | CVE-2020-15095⁠ | | npm:1.0.1 | CVE-2013-4116⁠ | | npm:1.0.1 | GMS-2016-23⁠ | | grunt:1.0.0 | CVE-2022-1537⁠ | | grunt:1.0.0 | CVE-2020-7729⁠ | | grunt:1.0.0 | CVE-2022-0436⁠ | | pug:1.0.0 | CVE-2021-21353⁠ | | pug:1.0.0 | CVE-2024-36361⁠ | | json:1.0.0 | CVE-2020-7712⁠ | | ini:1.0.0 | CVE-2020-7788⁠ | | diff:1.0.0 | GHSA-h6ch-v84p-w6p9⁠ | ## SSH connections (public preview) ### Permission denied (publickey) ```bash ssh user@studio-session-id@connect.example.com # user@studio-session-id@connect.example.com: Permission denied (publickey). ``` If you receive a permission denied error, there are several possible causes: 1. Verify the user has the correct role and permissions in the workspace. 2. Check that the user's SSH public key is configured in their Seqera user profile. 3. Ensure SSH was enabled when starting the Studio using the **SSH Connection** toggle. The SSH setting defaults to disabled for new Studios. 4. Ensure the Studio is built with Connect client version 0.10.0 or later. ### VS Code Remote SSH not working If VS Code fails to connect or shows errors when using the Remote SSH extension, disable local server mode in VS Code settings: ```json { "remote.SSH.useLocalServer": false } ``` VS Code's local server mode uses SSH multiplexing over SOCKS proxy, which is not supported. See [Connect to a Studio via SSH - VS Code Remote SSH](../studios/managing#vs-code-remote-ssh) for detailed setup instructions. Additionally, you might need to update your `~/.ssh/config` file to connect directly to the Studio session: ```bash Host HostName User @ Port ``` ### AI coding assistant fails with `Pseudo-terminal will not be allocated` ```bash ssh alice@a01ac8894@connect.example.com -p 2222 # Pseudo-terminal will not be allocated because stdin is not a terminal. ``` This issue occurs when an AI coding assistant runs `ssh` as a subprocess, such as Claude Code in a terminal. The assistant doesn't attach a terminal to stdin, and the SSH client refuses to allocate a pseudo-terminal. To resolve, force pseudo-terminal allocation with `-tt`: ```bash ssh -tt alice@a01ac8894@connect.example.com -p 2222 ``` ### Claude Code desktop app fails with `Couldn't inspect the remote machine` ``` Connecting to remote host... Detecting remote OS and shell... Couldn't inspect the remote machine. ``` This issue occurs when the Connect server and proxy are earlier than version 0.12.1, or the Connect client is earlier than version 0.13.0. Earlier versions don't run remote commands through a shell, and the app's environment checks fail. To resolve, ensure your Studio runs Connect client 0.13.0 or later. See [Claude Code desktop app](../studios/managing#claude-code-desktop-app) for setup instructions. ### Claude Code desktop app fails with `Timed out while waiting for handshake` This issue occurs because the app ignores the `Port` value in `~/.ssh/config` and defaults to port 22. To resolve, set **SSH Port** to `2222` in the app's connection settings. See [Claude Code desktop app](../studios/managing#claude-code-desktop-app) for setup instructions. ### SSH connection string format **Correct format:** ```bash ssh @@ -p 2222 ``` **Example:** ```bash ssh alice@a01ac8894@connect.example.com -p 2222 ``` Where: - ``: Your Seqera Platform username - ``: The Studio session ID (8-character hex string visible in the Studios list) - ``: Your connect proxy domain - Port: `2222` (default SSH proxy port) ## Working in a Studio session ### View all mounted datasets In your interactive analysis environment, open a new terminal and type `ls -la /workspace/data`. This displays all the mounted datasets available in the current session. ### Enable AI coding assistants in Studios VS Code, RStudio, and Jupyter environments natively integrate with [GitHub Copilot][gh-copilot]. Enabling it requires a GitHub account and an active Copilot subscription. - **VS Code:** To enable GitHub Copilot in your VS Code session, install the extension and then sign in with your GitHub account. [Learn more][vscode-blog]. - **RStudio:** Enabling GitHub Copilot in your RStudio session requires RStudio configuration changes. By default, the Studio session user has root permissions and can make these changes. Restart RStudio afterward. [Learn more][posit-ghcopilot-guide]. - **Jupyter:** [Notebook Intelligence (NBI)][nbi] is an AI coding assistant and extensible AI framework for Jupyter. It can use GitHub Copilot or AI models from any other LLM Provider. [Learn more][nbi-blog]. {/* links */} [gh-copilot]: https://github.com/features/copilot [open-vscode-server]: https://github.com/gitpod-io/openvscode-server [open-vsx]: https://open-vsx.org/ [posit-ghcopilot-guide]: https://docs.posit.co/ide/user/ide/guide/tools/copilot.html [nbi]: https://github.com/notebook-intelligence/notebook-intelligence [nbi-blog]: https://blog.jupyter.org/introducing-notebook-intelligence-3648c306b91a [contact]: https://seqera.io/contact-us/ --- ## General When working with Seqera Platform, you might encounter the following issues. ## Common errors #### `timeout is not an integer or out of range` This error occurs on Seqera Platform v24.2 and later when Redis is outdated. Version 24.2 requires Redis 6.2 or later. To resolve, upgrade your Redis instance according to your cloud provider's instructions. #### `Unknown pipeline repository or missing credentials` from public GitHub repositories GitHub imposes [rate limits](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting) on repository pulls, including public repositories: unauthenticated requests are capped at 60 per hour and authenticated requests at 5000 per hour. This error is usually caused by the 60-per-hour cap. To resolve: 1. Ensure there's at least one GitHub credential in your workspace's **Credentials** tab. 2. Ensure the **Access token** field of every GitHub credential is populated with a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and **not** a user password. GitHub personal access tokens (PATs) are typically longer than passwords and include a `ghp_` prefix. For example: `ghp_IqIMNOZH6zOwIEB4T9A2g4EHMy8Ji42q4HA` 3. Confirm that your PAT provides the elevated threshold and that transactions are charged against it: `curl -H "Authorization: token ghp_LONG_ALPHANUMERIC_PAT" -H "Accept: application/vnd.github.v3+json" https://api.github.com/rate_limit` #### `No such variable` This error occurs when you execute a DSL1-based Nextflow workflow with [Nextflow 22.03.0-edge](https://github.com/nextflow-io/nextflow/releases/tag/v22.03.0-edge) or later. #### Sleep commands in Nextflow workflows The behavior of `sleep` commands in your Nextflow workflows depends on where they are used: - In an `errorStrategy` block, Nextflow uses the Groovy sleep function, which takes its value in milliseconds. - In a process script block, that language's sleep binary or method is used. For example, [this bash script](https://docs.seqera.io/nextflow/metrics) uses the bash sleep binary, which takes its value in seconds. #### Large number of batch job definitions Platform normally looks for an existing job definition that matches your workflow requirement. If nothing matches, it recreates the job definition. Use a bash script to clear job definitions. Tailor it to your needs, for example to deregister only job definitions older than a set number of days: ```bash jobs=$(aws --region eu-west-1 batch describe-job-definitions | jq -r .jobDefinitions[].jobDefinitionArn) for x in $jobs; do echo "Deregister $x"; sleep 0.01; aws --region eu-west-1 batch deregister-job-definition --job-definition $x; done ``` ## Containers #### Use rootless containers in Nextflow pipelines Most containers use the root user by default. Some users prefer a non-root user in the container to minimize the risk of privilege escalation. Because Nextflow and its tasks use a shared work directory to manage input and output data, rootless containers can cause file permission errors in some environments: ``` touch: cannot touch '/fsx/work/ab/27d78d2b9b17ee895b88fcee794226/.command.begin': Permission denied ``` This should not occur with AWS Batch from Seqera version 22.1.0. In other cases, force all task containers to run as root. Add one of the following to your [Nextflow configuration](../launch/advanced#nextflow-config-file): ```groovy // cloud executors process.containerOptions = "--user 0:0" // Kubernetes k8s.securityContext = [ "runAsUser": 0, "runAsGroup": 0 ] ``` ## Git integration #### `Get branches operation not supported by BitbucketServerRepositoryProvider provider` If you supplied the correct Bitbucket credentials and URL details in your `tower.yml` and still see this error, upgrade to at least v22.3.0. This version addresses SCM provider authentication issues and likely resolves the retrieval failure. ## Optimization #### `OutOfMemoryError: Container killed due to memory usage` Nextflow can underestimate the memory allocation for containerized tasks. As a workaround, add a `retry` error strategy to the failing process that increases the allocated memory on each retry: ```groovy process { errorStrategy = 'retry' maxRetries = 3 memory = { 1.GB * task.attempt } } ``` ## Plugins #### Use the Nextflow SQL DB plugin to query AWS Athena From [Nextflow 22.05.0-edge](https://github.com/nextflow-io/nextflow/releases/tag/v22.05.0-edge), your Nextflow pipelines can query data from AWS Athena. Add these items to your `nextflow.config`. Secrets are optional: ```groovy plugins { id 'nf-sqldb@0.4.0' } sql { db { 'athena' { url = 'jdbc:awsathena://AwsRegion=;S3OutputLocation=s3://' user = secrets.ATHENA_USER password = secrets.ATHENA_PASSWORD } } } ``` Then call the functionality in your workflow: ```groovy channel.sql.fromQuery("select * from test", db: "athena", emitColumns:true).view() ``` :::note This example uses the legacy `nf-sqldb@0.4.0` syntax. Newer plugin versions use an explicit `include { fromQuery } from 'plugin/nf-sqldb'` statement instead. See the [nf-sqldb documentation](https://github.com/nextflow-io/nf-sqldb). ::: See the [nf-sqldb discussion](https://github.com/nextflow-io/nf-sqldb/discussions/5) for more information. ## Repositories #### Private Docker registry integration Seqera-invoked jobs can pull container images from private Docker registries, such as JFrog Artifactory. The method depends on your computing platform. For **AWS Batch**, modify your EC2 launch template using [these AWS instructions](https://docs.aws.amazon.com/batch/latest/userguide/private-registry-auth.html). :::note This solution requires Docker Engine [17.07 or later](https://docs.docker.com/engine/release-notes/17.07/) to use `--password-stdin`. You might need to add commands to your launch template, depending on your security posture: ```bash cp /root/.docker/config.json /home/ec2-user/.docker/config.json && chmod 777 /home/ec2-user/.docker/config.json ``` ::: For **Azure Batch**, create a **Container registry**-type credential in your Seqera workspace and associate it with the Azure Batch compute environment in the same workspace. For **Kubernetes**, use an `imagePullSecret`, per [#2827](https://github.com/nextflow-io/nextflow/issues/2827). #### `Remote resource not found` This error occurs when the Nextflow head job fails to retrieve the repository credentials from Seqera. If your Nextflow log contains an entry like `DEBUG nextflow.scm.RepositoryProvider - Request [credentials -:-]`, check the protocol of your instance's `TOWER_SERVER_URL` value. It must be set to `https` rather than `http`, unless you use `TOWER_ENABLE_UNSAFE_MODE` to allow HTTP connections to Seqera in a test environment. ## Secrets #### `Missing AWS execution role arn` during launch The [ECS agent must have access](https://docs.aws.amazon.com/batch/latest/userguide/execution-IAM-role.html) to retrieve secrets from AWS Secrets Manager. Secrets-using pipelines launched in an AWS Batch compute environment encounter this error when an IAM execution role is not provided. See [Secrets](../secrets/overview). #### AWS Batch task failures with secrets You might encounter errors when executing pipelines that use secrets on AWS Batch: - If you use `nf-sqldb` version 0.4.1 or earlier and have secrets in your `nextflow.config`, you might see `nextflow.secret.MissingSecretException: Unknown config secret` errors in your Nextflow log. To resolve, explicitly define the `xpack-amzn` plugin in your configuration: ```groovy plugins { id 'xpack-amzn' id 'nf-sqldb' } ``` - If you have two or more processes that use the same container image but only some of them use secrets, your secret-using processes might fail during the initial run and then succeed when resumed. This is caused by a bug in how Nextflow (22.07.1-edge and earlier) registers jobs with AWS Batch. To resolve, upgrade Nextflow to version 22.08.0-edge or later. If you can't upgrade, use one of these workarounds: - Use a different container image for each process. - Define the same set of secrets in each process that uses the same container image. ## Tower Agent #### `Unexpected Exception in WebSocket … Operation timed out` Tower Agent reconnection logic was improved in version 0.5.0. [Update your Tower Agent](https://github.com/seqeralabs/tower-agent) before relaunching your pipeline. #### Reattach to a running agent When you SSH back to the login node, attach to the agent session at any time: ```bash tmux attach -t tower-agent ``` You can see the current log output. Detach again with **Ctrl-b**, then **d**, to leave the agent running. #### Agent process stopped If `tmux ls` shows no sessions, or attaching reveals the agent has exited, restart it as in [Tower Agent setup](../supported_software/agent/overview#start-the-agent-inside-tmux). Common causes: login node reboot, the process killed for exceeding login-node resource limits, or a revoked access token. #### Agent shows as disconnected in Seqera Platform If Seqera Platform shows the agent as disconnected while it's running on the cluster, verify that the **Agent Connection ID** in your workspace credential exactly matches the argument you passed to `tw-agent`. #### _Authentication errors_ on agent startup Personal access tokens can be revoked or expire. If the agent logs authentication errors, generate a new token in Seqera Platform and restart the agent with the updated `TOWER_ACCESS_TOKEN` value. #### _Permission denied_ on the work directory The agent needs read and write access to the work directory. If launches fail with permission errors, confirm that the directory exists and is owned by the user running the agent: ```bash mkdir -p ~/work ``` #### Enable trace logging To diagnose connection or execution issues in detail, enable trace-level logging: ```bash export TOWER_ACCESS_TOKEN= export LOGGER_LEVELS_IO_SEQERA_TOWER_AGENT=TRACE ./tw-agent ``` Trace logging shows WebSocket connection details, message exchanges, reconnection attempts, command execution details and exit codes, and full stack traces for errors. ## Google #### Spot VM preemption causes task interruptions Spot VMs reduce cost but increase the likelihood that a task is interrupted before completion. When Google Cloud reclaims a Spot VM, Google Cloud Batch terminates the task with exit code `50001`. Add a retry strategy to your Nextflow configuration so interrupted tasks are automatically re-executed. See [Spot Instances](https://docs.seqera.io/nextflow/google#spot-instances) in the Nextflow documentation. For example: ```groovy process { errorStrategy = { task.exitStatus == 50001 ? 'retry' : 'finish' } maxRetries = 5 } ``` #### Seqera service account permissions for Google Cloud Batch Grant the following roles to the custom service account that submits Batch jobs: - Batch Agent Reporter (`roles/batch.agentReporter`) - Batch Job Editor (`roles/batch.jobsEditor`) - Logs Writer (`roles/logging.logWriter`) - Logs Viewer (`roles/logging.logViewer`) - Service Account User (`roles/iam.serviceAccountUser`) - Storage Admin (`roles/storage.admin`), or bucket-level Storage access For detailed setup instructions, see [Service account permissions](../compute-envs/google-cloud-batch#service-account-permissions). ## Kubernetes #### `Invalid value: "xxx": must be less or equal to memory limit` This error can occur when you specify a value in the **Head Job memory** field while creating a Kubernetes-type compute environment. If you receive an error that includes `field: spec.containers[x].resources.requests` and `message: Invalid value: "xxx": must be less than or equal to memory limit`, your Kubernetes cluster might be configured with [system resource limits](https://kubernetes.io/docs/tasks/administer-cluster/manage-resources/) that deny the Nextflow head job's resource request. To isolate the component causing the problem, launch a pod directly on your cluster through your Kubernetes administration solution. For example: ```yaml --- apiVersion: v1 kind: Pod metadata: name: debug labels: app: debug spec: containers: - name: debug image: busybox command: ["sh", "-c", "sleep 10"] resources: requests: memory: "xxxMi" # or "xxxGi" restartPolicy: Never ``` ## On-premises HPC #### `java: command not found` When submitting jobs to your on-premises HPC (using either SSH or Tower Agent authentication), the following error might appear in your Nextflow logs, even with Java on your `PATH` environment variable: ``` java: command not found Nextflow is trying to use the Java VM defined for the following environment variables: JAVA_CMD: java NXF_OPTS: ``` Possible causes: 1. The queue where the Nextflow head job runs is in a different environment or node than your login node userspace. 2. If your HPC cluster uses modules, the Java module might not be loaded by default. To troubleshoot: 1. Open an interactive session with the head job queue. 2. Launch the Nextflow job from the interactive session. 3. If your cluster uses modules, add `module load ` in the **Advanced options > Pre-run script** field when creating your HPC compute environment in Seqera. 4. If your cluster doesn't use modules, source an environment with Java and Nextflow in the **Advanced options > Pre-run script** field when creating your HPC compute environment in Seqera. #### Pipeline submissions to HPC clusters fail for some users Nextflow launcher scripts fail if processed by a non-Bash shell, such as zsh or tcsh. You can identify this problem from these error entries: 1. Your `.nextflow.log` contains an error like `Invalid workflow status - expected: SUBMITTED; current: FAILED`. 2. Your Seqera **Error report** tab contains an error like: ``` Slurm job submission failed - command: mkdir -p /home//\//scratch; cd /home//\//scratch; echo | base64 -d > nf-.launcher.sh; sbatch ./nf-.launcher.sh - exit : 1 - message: Submitted batch job <#> ``` Connect to the head node over SSH and run `ps -p $$` to verify your default shell. If you see an entry other than Bash, fix it as follows: 1. Check which shells are available: `cat /etc/shells` 2. Change your shell: `chsh -s /usr/bin/bash` (the path to the binary might differ, depending on your HPC configuration). 3. If submissions continue to fail after the shell change, ask your Seqera Platform admin to restart the **backend** and **cron** containers, then submit again. #### Execution logs don't update in real time for HPC compute environments While a task runs on an HPC compute environment (such as Slurm, Grid Engine, LSF, or PBS Pro), the **Execution log** tab on the run details page does not refresh automatically. This is expected behavior. Real-time log streaming is supported only for compute environments that stream logs from a cloud logging service: AWS Batch, Azure Batch, Google Cloud Batch, Kubernetes, and the AWS Cloud and Azure Cloud environments. For HPC compute environments, Seqera Platform retrieves the task log from the task work directory (the task's `.command.log` file) instead of streaming it. To load the latest log content, change tabs or refresh the page. Other run details, such as run status, task counters, and metrics, update in real time regardless of the compute environment type. --- ## Workspaces(Troubleshooting_and_faqs) When working with workspaces, you might encounter the following issues. ## Common issues #### Seqera-invoked pipeline contacts a workspace other than the launch workspace You might see this entry in your Nextflow log: ``` Unexpected response for request http://TOWER_SERVER_URL/api/trace/TRACE_ID/begin?workspaceId=WORKSPACE_ID ``` If the workspace ID in this message differs from your launch workspace, Seqera retrieved an incorrect access token from a Nextflow configuration file. Check these locations for a hardcoded token: - The `tower.accessToken` block of your `nextflow.config`, either from the Git repository or an override in the launch form. - In an HPC cluster compute environment, a stateful `nextflow.config` in the credential user's home directory, for example `~/.nextflow/config`. To resolve, remove the hardcoded access token so that Seqera uses the launch workspace's token. # Seqera Platform CLI > Documentation for the Seqera Platform command-line interface. This file contains all documentation content in a single document following the llmstxt.org standard. ## Command Reference This reference documents all `tw` CLI commands for managing Seqera Platform resources. Each command page includes detailed descriptions, options, and examples. :::note The CLI performs operations in the user workspace context by default. Use the `TOWER_WORKSPACE_ID` environment variable or the `--workspace` parameter to specify an organization workspace ID. ::: ## --help flag Use `-h` or `--help` with any command to view available options: ```bash tw --help # List all commands tw -h # Show command options tw -h # Show subcommand options ``` Example: ```bash tw runs view -h # Help for viewing runs tw pipelines import -h # Help for import subcommand tw credentials add google -h # Help for specific provider ``` ## Commands by category ### Info - [**info**](reference/info) - Show system info and health status ### Resources - [**credentials**](reference/credentials) - Manage workspace credentials - [**compute-envs**](reference/compute-envs) - Manage compute environments - [**datasets**](reference/datasets) - Manage datasets - [**data-links**](reference/data-links) - Manage data links - [**labels**](reference/labels) - Manage workspace labels - [**secrets**](reference/secrets) - Manage secrets ### Pipelines and runs - [**pipelines**](reference/pipelines) - Manage pipelines - [**pipeline-schemas**](reference/pipeline-schemas) - Store pipeline schemas in Platform - [**launch**](reference/launch) - Launch a pipeline - [**runs**](reference/runs) - Manage pipeline runs - [**actions**](reference/actions) - Manage pipeline actions ### Organization and access - [**organizations**](reference/organizations) - Manage organizations - [**workspaces**](reference/workspaces) - Manage workspaces - [**teams**](reference/teams) - Manage teams - [**members**](reference/members) - Manage organization members - [**participants**](reference/participants) - Manage workspace participants - [**collaborators**](reference/collaborators) - Manage organization collaborators ### Interactive environments - [**studios**](reference/studios) - Manage studios ## Common patterns ### Output formats Export command results to JSON: ```bash tw --output=json ``` Use with `jq` for filtering: ```bash tw workspaces list --output=json | jq -r '.workspaces[].orgId' ``` ### Workspace context Specify workspace by ID: ```bash tw -w 123456789012345 ``` Or by organization/workspace name: ```bash tw -w myorg/myworkspace ``` Set default workspace: ```bash export TOWER_WORKSPACE_ID=123456789012345 ``` ## Next steps - See individual command references using the navigation - See [Installation](../../platform-cli-docs/docs/installation.md) for setup instructions and [Overview](../../platform-cli-docs/docs/overview.md) for CLI introduction --- ## Installation ### Option 1: Download latest binary 1. Download the latest [version][releases] for your OS from the CLI GitHub repository. 1. Rename the file and and make it executable: ```bash mv tw-* tw chmod +x ./tw ``` 1. Move the file to a directory accessible to your `$PATH` variable: ```bash sudo mv tw /usr/local/bin/ ``` ### Option 2: Install through Homebrew (Linux and macOS) Install tw-cli from the Seqera Homebrew tap: ```bash brew install seqeralabs/tap/tw ``` ### Configuration The CLI requires an access token to interact with Seqera Platform. Select **User tokens** from the user menu in the [Platform UI](https://cloud.seqera.io), then select **Add token** to create a new token. Copy the access token value and use it with the CLI in one of two ways: - **Environment variable**: 1. Export the token as a shell variable directly into your terminal: ```bash export TOWER_ACCESS_TOKEN= ``` 2. Add the `export` command to your `.bashrc`, `.zshrc`, or `.bash_profile` file for it to be permanently added to your environment. - **tw command flag**: Provide the access token directly in your `tw` command with `--access-token`: ```bash tw --access-token= ``` If required, configure the following optional environment variables using the same methods above: - `TOWER_WORKSPACE_ID`: Workspace ID. Default: Your user workspace. - `TOWER_API_ENDPOINT`: Seqera API URL. Default: `api.cloud.seqera.io`. :::tip Find your `TOWER_WORKSPACE_ID` from the **Workspaces** tab on your organization page. Alternatively, list all the workspaces your token can access with `tw workspaces list` and copy the workspace ID from the command output. ::: ### Health check Confirm the installation, configuration, and connection: ```bash tw info Details -------------------------+---------------------- Tower API endpoint | Tower API version | 1.25.0 Tower version | 24.2.0_cycle22 CLI version | 0.9.4 (f3e846e) CLI minimum API version | 1.15 Authenticated user | System health status ---------------------------------------+------------------ Remote API server connection check | OK Tower API version check | OK Authentication API credential's token | OK ``` ### Commands See [Commands](commands-reference) for detailed instructions to use the CLI. ### Autocompletion Activate autocompletion in your current session with this command: ```bash source <(tw generate-completion) ``` ### Custom SSL certificate authority store If you are using a Private CA SSL certificate not recognized by the default Java certificate authorities, use a [custom](https://www.baeldung.com/jvm-certificate-store-errors) `cacerts` store: ```bash tw -Djavax.net.ssl.trustStore=/absolute/path/to/cacerts -Djavax.net.ssl.trustStorePassword= info ``` Replace `` with your keystore password. If you did not set a password when creating the keystore, include the default keystore password `changeit` in the command above. You can also rename the binary to `tw-binary` and create a `tw` script to automatically include the custom `cacerts` store in every session: ```bash #!/usr/bin/env bash tw-binary -Djavax.net.ssl.trustStore=/absolute/path/to/cacerts -Djavax.net.ssl.trustStorePassword= $@ ``` ### Build binary development versions tw CLI is a platform binary executable created by a native compilation from Java GraalVM. To compile and build a development version of the binary: 1. If necessary, install [SDKMan!](https://sdkman.io/) 1. From the root of the tower-cli project, install GraalVM: ```bash sdk env install ``` This ensures that SDKMan uses the tower-cli project-specific `.sdkmanrc` configuration. 1. Install `native-image`: ```bash gu install native-image ``` 1. Export your Github credentials. Github requires authentication for public packages (the token only requires the `read:packages` scope): ```bash export GITHUB_USERNAME=... export GITHUB_TOKEN=... ``` 1. Create the native client: ```bash ./gradlew nativeCompile ``` This will install a locally compiled version of `tw` in the nativeCompile directory: ```bash Produced artifacts: /build/native/nativeCompile/tw (executable) ======================================================================================================================== Finished generating 'tw' in 1m 6s. [native-image-plugin] Native Image written to: /build/native/nativeCompile BUILD SUCCESSFUL in 1m 8s 6 actionable tasks: 2 executed, 4 up-to-date ``` 1. Run `tw`: ```bash ./build/native/nativeCompile/tw ``` ### Non-binary development versions Run a non-binary development version by executing the [`./tw`](https://github.com/seqeralabs/tower-cli/blob/master/tw) script in the root of the CLI repository. ### License [Mozilla Public License v2.0](https://github.com/seqeralabs/tower-cli/blob/master/LICENSE.txt) [releases]: https://github.com/seqeralabs/tower-cli/releases --- ## Overview Seqera Platform CLI brings concepts like pipelines and compute environments to the terminal. The CLI interacts with Platform to provide an interface to launch pipelines, manage cloud resources, and administer your analysis. ![tw](./_images/tw-screenshot.png) ### Key features - **A Nextflow-like experience**: tw CLI provides a developer-friendly environment. Pipelines can be launched with the CLI similarly to Nextflow but with the Platform benefits of monitoring, logging, resource provisioning, dataset management, and collaborative sharing. - **Infrastructure as Code**: All Platform resources, including pipelines and compute environments, can be described in a declarative manner. This enables a complete definition of an analysis environment that can be versioned and treated as code. It greatly simplifies configuration sharing and routine administration. - **Built on OpenAPI**: tw CLI interacts with Platform via the [Seqera Platform API](https://docs.seqera.io/platform-api) which uses the OpenAPI 3.0 specification. The CLI provides full control of the Platform application, allowing users to get maximum insights into pipeline submissions and execution environments. ### Availability The CLI can be installed on macOS, Windows, and Linux. It is compatible with [Seqera Platform Cloud](https://cloud.seqera.io/) and Enterprise versions 21.08 and later. See [Installation](../../platform-cli-docs/docs/installation.md) to get started. --- ## tw actions Manage pipeline actions. Run `tw actions -h` to view supported pipeline action operations. [Actions](https://docs.seqera.io/platform-cloud/pipeline-actions/overview) enable event-based pipeline execution, such as triggering a pipeline launch with a GitHub webhook whenever the pipeline repository is updated. ## tw actions list List pipeline actions. ```bash tw actions list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw actions list -w 123456789012345 ``` Example output: ```bash Actions for user-name user: ID | Name | Endpoint | Status | Source ------------------------+-------+-----------------------------------------------------------------------------------------------+--------+-------- 2b3c4d5e6f7g8h | Testy | https://api.cloud.seqera.io/actions/2b3c4d5e6f7g8h/launch?workspaceId=123456789012345 | ACTIVE | tower ``` ## tw actions view View pipeline action details. ```bash tw actions view [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Action unique identifier | No | `null` | | `-n`, `--name` | Action name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw actions view -n Testy -w 123456789012345 ``` Example output: ```bash Details for action 'Testy' --------------+------------------------------------------------------------------- ID | 2b3c4d5e6f7g8h Name | Testy Status | ACTIVE Pipeline URL | https://github.com/nextflow-io/rnaseq-nf Source | tower Hook URL | https://api.cloud.seqera.io/actions/2b3c4d5e6f7g8h/launch Last event | never Date created | Tue, 10 Jun 2025 09:02:12 GMT Last event | never Labels | No labels found Configuration: { "id" : "3c4d5e6f7g8h9i0j1k2l3m", "computeEnvId" : "4d5e6f7g8h9i0j1k2l3m4n", "pipeline" : "https://github.com/nextflow-io/rnaseq-nf", "workDir" : "s3://my-bucket", "configProfiles" : [ ], "userSecrets" : [ ], "workspaceSecrets" : [ ], "resume" : false, "pullLatest" : false, "stubRun" : false, "dateCreated" : "2025-06-10T09:02:12Z" } ``` ## tw actions add Add a pipeline action. ```bash tw actions add [OPTIONS] ``` Run `tw actions add -h` to view the list of supported event sources. Run `tw actions add -h` to view the required and optional fields for your event source. :::note Supported event sources: - **tower**: Manual webhook trigger via Platform UI or API - **github**: GitHub webhook events (push, pull request, etc.) ::: #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Action name. Must be unique per workspace. Names consist of alphanumeric, hyphen, and underscore characters. | Yes | `null` | | `--pipeline` | Pipeline repository URL. Must be a full Git repository URL (e.g., https://github.com/nextflow-io/hello). | Yes | `null` | | `-i`, `--id` | Action unique identifier | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format. Required if `TOWER_WORKSPACE_ID` environment variable is not set. | Yes* | `TOWER_WORKSPACE_ID` | | `-c`, `--compute-env` | Compute environment identifier where the pipeline will run. Defaults to workspace primary compute environment if omitted. Provide the name or identifier. | No | `null` | | `--work-dir` | Work directory path where workflow intermediate files are stored. Defaults to compute environment work directory if omitted. | No | `null` | | `-p`, `--profile` | Array of Nextflow configuration profile names to apply. | No | `null` | | `--params-file` | Pipeline parameters in JSON or YAML format. Provide the path to a file containing the content. | No | `null` | | `--revision` | Git revision, branch, or tag to use. | No | `null` | | `--config` | Nextflow configuration as text (overrides config files). Provide the path to a file containing the content. | No | `null` | | `--pre-run` | Add a script that executes in the nf-launch script prior to invoking Nextflow processes. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--post-run` | Add a script that executes after all Nextflow processes have completed. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--pull-latest` | Pull the latest version of the pipeline from the repository. | No | `null` | | `--stub-run` | Execute a stub run for testing (processes return dummy results). | No | `null` | | `--main-script` | Alternative main script filename. Default: `main.nf`. | No | `null` | | `--entry-name` | Workflow entry point name when using Nextflow DSL2. | No | `null` | | `--schema-name` | Name of the pipeline schema to use. | No | `null` | | `--user-secrets` | Array of user secrets to make available to the pipeline. | No | `null` | | `--workspace-secrets` | Array of workspace secrets to make available to the pipeline. | No | `null` | #### Example Command: ```bash tw actions add tower -n example-hello-action --pipeline=https://github.com/nextflow-io/hello -w 123456789012345 ``` Example output: ```bash Pipeline action 'example-hello-action' added at [my-organization / my-workspace] workspace with id '2b3c4d5e6f7g8h9i0j1k2l' ``` :::note The `--pipeline` parameter requires a full Git repository URL, not a saved pipeline name or ID. ::: ## tw actions update Update a pipeline action. ```bash tw actions update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-s`, `--status` | Action status (pause or active) | No | `null` | | `--new-name` | Updated action name. Must be unique per workspace. Names consist of alphanumeric, hyphen, and underscore characters. | No | `null` | | `-i`, `--id` | Action unique identifier | No | `null` | | `-n`, `--name` | Action name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `-c`, `--compute-env` | Compute environment identifier where the pipeline will run. Defaults to workspace primary compute environment if omitted. Provide the name or identifier. | No | `null` | | `--work-dir` | Work directory path where workflow intermediate files are stored. Defaults to compute environment work directory if omitted. | No | `null` | | `-p`, `--profile` | Array of Nextflow configuration profile names to apply. | No | `null` | | `--params-file` | Pipeline parameters in JSON or YAML format. Provide the path to a file containing the content. | No | `null` | | `--revision` | Git revision, branch, or tag to use. | No | `null` | | `--config` | Nextflow configuration as text (overrides config files). Provide the path to a file containing the content. | No | `null` | | `--pre-run` | Add a script that executes in the nf-launch script prior to invoking Nextflow processes. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--post-run` | Add a script that executes after all Nextflow processes have completed. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--pull-latest` | Pull the latest version of the pipeline from the repository. | No | `null` | | `--stub-run` | Execute a stub run for testing (processes return dummy results). | No | `null` | | `--main-script` | Alternative main script filename. Default: `main.nf`. | No | `null` | | `--entry-name` | Workflow entry point name when using Nextflow DSL2. | No | `null` | | `--schema-name` | Name of the pipeline schema to use. | No | `null` | | `--user-secrets` | Array of user secrets to make available to the pipeline. | No | `null` | | `--workspace-secrets` | Array of workspace secrets to make available to the pipeline. | No | `null` | #### Example Command: ```bash tw actions update -n example-hello-action --status disabled -w 123456789012345 ``` Example output: ```bash Pipeline action 'example-hello-action' updated at [my-organization / my-workspace] workspace with id '2b3c4d5e6f7g8h9i0j1k2l' ``` ## tw actions delete Delete a pipeline action. ```bash tw actions delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Action unique identifier | No | `null` | | `-n`, `--name` | Action name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw actions delete -n example-hello-action -w 123456789012345 ``` Example output: ```bash Pipeline action 'example-hello-action' deleted at [my-organization / my-workspace] workspace ``` ## tw actions labels Manage pipeline action labels. ```bash tw actions labels [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Action unique identifier | No | `null` | | `-n`, `--name` | Action name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | Personal workspace | | `--no-create` | Assign labels without creating the ones which were not found. | No | `null` | | `--operations`, `-o` | Type of operation (set, append, delete) [default: set]. | No | `set` | #### Example Command: ```bash tw actions labels -n Testy -w 123456789012345 test-environment,label2 ``` Example output: ```bash 'set' labels on 'action' with id '2b3c4d5e6f7g8h' at 123456789012345 workspace ``` :::note Requires either action name (`-n`) or action ID (`-i`). Labels are provided as a comma-separated list at the end of the command. ::: --- ## tw collaborators Manage organization collaborators. Run `tw collaborators -h` view all the required and optional fields for managing organization collaborators. ## tw collaborators list List organization collaborators. ```bash tw collaborators list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-o`, `--organization` | Organization name or identifier | Yes | `null` | | `-f`, `--filter` | Filter members by username prefix | No | `null` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display (default: ) | No | `null` | #### Example Command: ```bash tw collaborators list -o seqeralabs ``` Example output: ```bash Collaborators for 888481802873456 organization: ID | Username | Email -----------------+----------------------+-------------------- 131369427314567 | external_user1 | user1@domain.com 127726720173456 | external_user2 | user2@domain.com 591511577845678 | external_user3 | user3@domain.com 132868466675789 | external_user4 | user4@domain.com 178756942629012 | external_user5 | user5@domain.com ``` --- ## tw compute-envs Manage compute environments. Compute environments define the execution platform where a pipeline runs. A compute environment is composed of the credentials, configuration, and storage options related to a particular computing platform. See [Compute environments](https://docs.seqera.io/platform-cloud/compute-envs/overview) for more information on supported providers. Run `tw compute-envs -h` to view the list of supported compute environment operations. ## tw compute-envs add Add a new compute environment. ```bash tw compute-envs add [OPTIONS] ``` Run `tw compute-envs add -h` to view the list of supported providers. Run `tw compute-envs add -h` to view the required and optional fields for your provider. You must add the credentials for your provider before creating your compute environment. #### Example Command: ```bash tw compute-envs add aws-batch forge --name=my_aws_ce \ --credentials= --region=eu-west-1 --max-cpus=256 \ --work-dir=s3:// --wait=AVAILABLE ``` Example output: ```bash New AWS-BATCH compute environment 'my_aws_ce' added at user workspace ``` This command will: - Use **Batch Forge** to automatically manage the AWS Batch resource lifecycle (`forge`) - Use the credentials previously added to the workspace (`--credentials`) - Create the required AWS Batch resources in the AWS Ireland (`eu-west-1`) region - Provision a maximum of 256 CPUs in the compute environment (`--max-cpus`) - Use an existing S3 bucket to store the Nextflow work directory (`--work-dir`) - Wait until the compute environment has been successfully created and is ready to use (`--wait`) See the [compute environment](https://docs.seqera.io/platform-cloud/compute-envs/overview) page for your provider for detailed information on Batch Forge and manual compute environment creation. ## tw compute-envs update Update a compute environment. ```bash tw compute-envs update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `--new-name` | New compute environment name. | No | `null` | | `-i`, `--id` | Compute environment unique identifier. | No | `null` | | `-n`, `--name` | Compute environment name. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw compute-envs update -n AWSCloudCE2 --new-name AWSCloud-primary -w 123456789012345 ``` Example output: ```bash Compute environment 'AWSCloudCE2' updated at [my-organization / my-workspace] workspace ``` ## tw compute-envs delete Delete a compute environment. ```bash tw compute-envs delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-i`, `--id` | Compute environment unique identifier. | No | `null` | | `-n`, `--name` | Compute environment name. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw compute-envs delete --name=my_aws_ce ``` Example output: ```bash Compute environment '1sxCxvxfx8xnxdxGxQxqxH' deleted at user workspace ``` ## tw compute-envs view View compute environment details. ```bash tw compute-envs view [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-i`, `--id` | Compute environment unique identifier. | No | `null` | | `-n`, `--name` | Compute environment name. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw compute-envs view -n AWSBatchCE -w 123456789012345 ``` Example output: ```bash Compute environment at [my-organization / my-workspace] workspace: ---------------+------------------------------- ID | 7g8h9i0j1k2l3m4n5o6p7q Name | AWSBatchCE Platform | aws-batch Last updated | Thu, 10 Jul 2025 11:23:28 GMT Last activity | Thu, 10 Jul 2025 11:24:20 GMT Created | Thu, 10 Jul 2025 11:22:49 GMT Status | AVAILABLE Labels | Configuration: { "discriminator" : "aws-batch", "region" : "eu-west-2", "executionRole" : "arn:aws:iam::123456789012:role/TowerForge-7g8h9i0j1k2l3m4n5o6p7q-ExecutionRole", "waveEnabled" : true, "fusion2Enabled" : true, "nvnmeStorageEnabled" : true, "fusionSnapshots" : false, "forge" : { "type" : "SPOT", "minCpus" : 0, "maxCpus" : 500, "gpuEnabled" : false, "instanceTypes" : [ ], "subnets" : [ ], "securityGroups" : [ ], "disposeOnDeletion" : true, "allowBuckets" : [ ], "efsCreate" : false, "dragenEnabled" : false, "fargateHeadEnabled" : false }, "workDir" : "s3://my-bucket", "environment" : [ ] } ``` ## tw compute-envs list List compute environments. ```bash tw compute-envs list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw compute-envs list -w 123456789012345 ``` Example output: ```bash Compute environments at [my-organization / my-workspace] workspace: ID | Status | Platform | Name | Last activity --------------------------+-----------+--------------+-------------+------------------------------- 5e6f7g8h9i0j1k2l3m4n5o | AVAILABLE | eks-platform | AWS-EKS | never 6f7g8h9i0j1k2l3m4n5o6p | AVAILABLE | gke-platform | gke-ce | never 7g8h9i0j1k2l3m4n5o6p7q | AVAILABLE | aws-batch | AWSBatchCE | Thu, 10 Jul 2025 11:24:20 GMT 8h9i0j1k2l3m4n5o6p7q8r | AVAILABLE | aws-cloud | AWSCloud | never 9i0j1k2l3m4n5o6p7q8r9s | AVAILABLE | gke-platform | GKE-CE2 | never 0j1k2l3m4n5o6p7q8r9s0t | AVAILABLE | google-batch | GCPBatch | never * 1k2l3m4n5o6p7q8r9s0t1 | AVAILABLE | aws-cloud | AWSCloudCE2 | never ``` ## tw compute-envs export Export compute environment configuration as a JSON file. ```bash tw compute-envs export [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-i`, `--id` | Compute environment unique identifier. | No | `null` | | `-n`, `--name` | Compute environment name. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw compute-envs export -n AWSCloud-primary -w 123456789012345 > /tmp/cloudce-export.json ``` Example output: ```bash (empty) ``` ## tw compute-envs import Import a compute environment configuration from a JSON file. ```bash tw compute-envs import [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-n`, `--name` | Name for the imported compute environment. | Yes | `null` | | `-c`, `--credentials` | Credentials identifier to use when multiple credentials match the compute environment. Use this to specify which credentials should be associated with the imported compute environment. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `--overwrite` | Overwrite the compute environment if it already exists. | No | `false` | | `` | Path to the JSON file containing the compute environment configuration (exported using `tw compute-envs export`). | Yes | `null` | #### Example Command: ```bash tw compute-envs import -n example-imported-ce -c 2l3m4n5o6p7q8r9s0t1u2v /tmp/cloudce-export.json -w 123456789012345 ``` Example output: ```bash New AWS-CLOUD compute environment 'example-imported-ce' added at [my-organization / my-workspace] workspace ``` :::note If multiple credentials match the imported compute environment, you must provide the `-c` flag with the credentials identifier to specify which credentials to use. You can find available credentials using `tw credentials list`. ::: ## tw compute-envs primary Manage the primary compute environment. ```bash tw compute-envs primary [OPTIONS] ``` ### tw compute-envs primary get Get the primary compute environment. ```bash tw compute-envs primary get [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw compute-envs primary get -w 123456789012345 ``` Example output: ```bash Primary compute environment for workspace '[my-organization / my-workspace]' is 'AWSCloud-primary (1k2l3m4n5o6p7q8r9s0t1)' ``` ### tw compute-envs primary set Set a compute environment as primary. ```bash tw compute-envs primary set [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-i`, `--id` | Compute environment unique identifier. | No | `null` | | `-n`, `--name` | Compute environment name. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw compute-envs primary set -n AWS-EKS -w 123456789012345 ``` Example output: ```bash Primary compute environment for workspace '[my-organization / my-workspace]' was set to 'AWS-EKS (5e6f7g8h9i0j1k2l3m4n5o)' ``` --- ## tw credentials To launch pipelines in a Platform workspace, you need [credentials](https://docs.seqera.io/platform-cloud/credentials/overview) for: 1. Compute environments 2. Pipeline repository Git providers 3. (Optional) [Tower agent](https://docs.seqera.io/platform-cloud/supported_software/agent/overview) — used with HPC clusters 4. (Optional) Container registries, such as docker.io ## tw credentials add Add workspace credentials. ```bash tw credentials add [OPTIONS] ``` Run `tw credentials add -h` to view a list of providers. Run `tw credentials add -h` to view the required fields for your provider. ### Common Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-n`, `--name` | Credentials name. Must be unique per workspace. | Yes | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | Personal workspace | :::note Additional provider-specific options are required depending on the provider type. Use `tw credentials add -h` to see all available options for your provider. You can add multiple credentials from the same provider in the same workspace. ::: ### Compute environment credentials Platform requires credentials to access your cloud compute environments. See the [compute environment page](https://docs.seqera.io/platform-cloud/compute-envs/overview) for your cloud provider for more information. Command: ```bash tw credentials add aws --name=my_aws_creds --access-key=AKIAIOSFODNN7EXAMPLE --secret-key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` Example output: ```bash New AWS credentials 'my_aws_creds (1sxCxvxfx8xnxdxGxQxqxH)' added at user workspace ``` ### Git credentials Platform requires access credentials to interact with pipeline Git repositories. See [Git integration](https://docs.seqera.io/platform-cloud/git/overview) for more information. Command: ```bash tw credentials add github -n=my_GH_creds -u=my-github-user -p=ghp_exampletoken1234567890abcdefghij ``` Example output: ```bash New GITHUB credentials 'my_GH_creds (xxxxx3prfGlpxxxvR2xxxxo7ow)' added at user workspace ``` ### Container registry credentials Configure credentials for the Nextflow Wave container service to authenticate to private and public container registries. See [Container registry credentials](https://docs.seqera.io/platform-cloud/credentials/container_registry_credentials) for more information. :::note Container registry credentials are only used by the Wave container service. See [Wave containers](https://docs.seqera.io/wave) for more information. ::: Command: ```bash tw credentials add container-reg --name=my_registry_creds --username=my-registry-user --password=my-secure-password-123 --registry=docker.io ``` Example output: ```bash New CONTAINER-REG credentials 'my_registry_creds (2tyCywygy9yoyeyHyRyryI)' added at user workspace ``` ## tw credentials update Update workspace credentials. ```bash tw credentials update [OPTIONS] ``` Run `tw credentials update -h` to view a list of providers. Run `tw credentials update -h` to view the required fields for your provider. #### Common Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-i`, `--id` | Credentials unique identifier | No | `null` | | `-n`, `--name` | Credentials name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | Personal workspace | :::note Additional provider-specific options vary depending on the provider type. Use `tw credentials update -h` to see all available options for your provider. Either credentials ID (`-i`) or name (`-n`) is required to identify which credentials to update. ::: #### Example Command: ```bash tw credentials update aws -n aws-credentials -a AKIAIOSFODNN7EXAMPLE -w 123456789012345 ``` Example output: ```bash AWS credentials 'aws-credentials' updated at [my-organization / my-workspace] workspace ``` ## tw credentials delete Delete workspace credentials. ```bash tw credentials delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-i`, `--id` | Credentials unique identifier | No | `null` | | `-n`, `--name` | Credentials name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw credentials delete --name=my_aws_creds ``` Example output: ```bash Credentials '1sxCxvxfx8xnxdxGxQxqxH' deleted at user workspace ``` ## tw credentials list List workspace credentials. ```bash tw credentials list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw credentials list ``` Example output: ```bash Credentials at user workspace: ID | Provider | Name | Last activity ------------------------+-----------+------------------------------------+------------------------------- 1x1HxFxzxNxptxlx4xO7Gx | aws | my_aws_creds_1 | Wed, 6 Apr 2022 08:40:49 GMT 1sxCxvxfx8xnxdxGxQxqxH | aws | my_aws_creds_2 | Wed, 9 Apr 2022 08:40:49 GMT 2x7xNsf2xkxxUIxXKxsTCx | ssh | my_ssh_key | Thu, 8 Jul 2021 07:09:46 GMT 4xxxIeUx7xex1xqx1xxesk | github | my_github_cred | Wed, 22 Jun 2022 09:18:05 GMT ``` --- ## tw data-links Data-links allow you to work with public and private cloud storage buckets in [Data Explorer](https://docs.seqera.io/platform-cloud/data/data-explorer) in the specified workspace. AWS S3, Azure Blob Storage, and Google Cloud Storage are supported. The full list of operations are: - `list`: List data-links in a workspace - `add`: Add a custom data-link to a workspace - `update`: Update a custom data-link in a workspace - `delete`: Delete a custom data-link from a workspace - `browse`: Browse the contents of a data-link in a workspace - `upload`: Upload files and directories to a data-link in a workspace - `download`: Download files and directories from a data-link in a workspace ## tw data-links list List data links. ```bash tw data-links list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-c`, `--credentials` | Credentials identifier. **Required for private cloud storage buckets** | No | `null` | | `--wait` | Wait for all data links to be fetched to cache | No | `null` | | `-n`, `--name` | Filter by data-link name | No | `null` | | `--visibility` | Filter by visibility: hidden, visible, or all | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display (default: ) | No | `null` | Run `tw data-links list -h` to view all the optional fields for listing data-links in a workspace. If a workspace is not defined, the `TOWER_WORKSPACE_ID` workspace is used by default. data-links can be one of two types: - `v1-cloud-`: Cloud data-links auto-discovered using credentials attached to the workspace. - `v1-user-`: Custom data-links created by users. #### Example Command: ```bash tw data-links list -w seqeralabs/showcase ``` Example output: ```bash data-links at [seqeralabs / showcase] workspace: ID | Provider | Name | Resource ref | Region -------------------------------------------+----------+--------------------------------+-----------------------------------------------------------------+----------- v1-cloud-833bb845bd9ec1970c4a7b0bb7b8c4ad | aws | e2e-data-explorer-tests-aws | s3://e2e-data-explorer-tests-aws | eu-west-2 v1-cloud-60700a33ec3fae68d424cf948fa8d10c | aws | nf-tower-bucket | s3://nf-tower-bucket | eu-west-1 v1-user-09705781697816b62f9454bc4b9434b4 | aws | vscode-analysis-demo | s3://seqera-development-permanent-bucket/studios-demo/vscode/ | eu-west-2 v1-user-0dede00fabbc4b9e2610261822a2d6ae | aws | seqeralabs-showcase | s3://seqeralabs-showcase | eu-west-1 v1-user-171aa8801cabe4af71500335f193d649 | aws | projectA-rnaseq-analysis | s3://seqeralabs-showcase/demo/nf-core-rnaseq/ | eu-west-1 v1-user-bb4fa9625a44721510c47ac1cb97905b | aws | genome-in-a-bottle | s3://giab | us-east-1 v1-user-e7bf26921ba74032bd6ae1870df381fc | aws | NCBI_Sequence_Read_Archive_SRA | s3://sra-pub-src-1/ | us-east-1 Showing from 0 to 99 from a total of 16 entries. ``` #### Filtering example List filtered by data-link name. Command: ```bash tw data-links list -w seqeralabs/showcase -n 1000genomes ``` Example output: ```bash data-links at [seqeralabs / showcase] workspace: ID | Provider | Name | Resource ref | Region ------------------------------------------+----------+-------------+------------------+----------- v1-user-6d8f44c239e2a098b3e02e918612452a | aws | 1000genomes | s3://1000genomes | us-east-1 Showing from 0 to 99 from a total of 1 entries. ``` ## tw data-links add Add a data link. ```bash tw data-links add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Data link name | Yes | `null` | | `-d`, `--description` | Data link description | No | `null` | | `-u`, `--uri` | Data link URI | Yes | `null` | | `-p`, `--provider` | Cloud provider: aws, azure, or google | Yes | `null` | | `-c`, `--credentials` | Credentials identifier. **Required for private cloud storage buckets** | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | Run `tw data-links add -h` to view all the required and optional fields for adding a custom data-link to a workspace. Users with the workspace `MAINTAIN` role and above can add custom data-links. The data-link `name`, `uri`, and `provider` (`aws`, `azure`, or `google`) fields are required. If adding a custom data-link for a private bucket, the credentials identifier field is also required. Adding a custom data-link for a public bucket doesn't require credentials. #### Example ```bash tw data-links add -w seqeralabs/showcase -n FOO -u az://seqeralabs.azure-benchmarking \ -p azure -c seqera_azure_credentials ``` Example output: ```bash data-link created: ID | Provider | Name | Resource ref | Region ------------------------------------------+----------+------+------------------------------------+-------- v1-user-152116183ee325463901430bb9efb8c9 | azure | FOO | az://seqeralabs.azure-benchmarking | ``` ## tw data-links delete Delete a data link. ```bash tw data-links delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Data link identifier | No | `null` | | `-n`, `--name` | Data link name | No | `null` | | `--uri` | Data link URI (e.g., s3://bucket-name) | No | `null` | Run `tw data-links delete -h` to view all the required and optional fields for deleting a custom data-link from a workspace. Users with the `MAINTAIN` role and above for a workspace can delete custom data-links. :::note `tw data-links delete` removes only the data-link record from Seqera Platform. It does not delete the files in cloud storage. To delete those files, use your cloud provider's tools. ::: #### Example Command: ```bash tw data-links delete -w seqeralabs/showcase -i v1-user-152116183ee325463901430bb9efb8c9 ``` Example output: ```bash data-link 'v1-user-152116183ee325463901430bb9efb8c9' deleted at '138659136604200' workspace. ``` ## tw data-links update Update a data link. ```bash tw data-links update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Data link identifier | Yes | `null` | | `-n`, `--name` | Data link name | Yes | `null` | | `-d`, `--description` | Data link description | No | `null` | | `-c`, `--credentials` | Credentials identifier. **Required for private cloud storage buckets** | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | Run `tw data-links update -h` to view all the required and optional fields for updating a custom data-link in a workspace. Users with the `MAINTAIN` role and above for a workspace can update custom data-links. #### Example Command: ```bash tw data-links update -w seqeralabs/showcase -i v1-user-152116183ee325463901430bb9efb8c9 -n BAR ``` Example output: ```bash data-link updated: ID | Provider | Name | Resource ref | Region ------------------------------------------+----------+------+------------------------------------+-------- v1-user-152116183ee325463901430bb9efb8c9 | azure | BAR | az://seqeralabs.azure-benchmarking | ``` ## tw data-links browse Browse data link contents. ```bash tw data-links browse [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-c`, `--credentials` | Credentials identifier. **Required for private cloud storage buckets** | No | `null` | | `-p`, `--path` | Path to browse within the data link | No | `null` | | `-f`, `--filter` | Filter results by prefix | No | `null` | | `-t`, `--token` | Next page token for pagination | No | `null` | | `--page` | Page number to display | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Data link identifier | No | `null` | | `-n`, `--name` | Data link name | No | `null` | | `--uri` | Data link URI (e.g., s3://bucket-name) | No | `null` | Run `tw data-links browse -h` to view all the required and optional fields for browsing a data-link in a workspace. Define the data-link ID using the required `-i` or `--id` argument, which can be found by first using the list operation for a workspace. In the example below, a name is defined to only retrieve data-links with names that start with the given word. #### Example Command: ```bash tw data-links browse -w seqeralabs/showcase -i v1-user-6d8f44c239e2a098b3e02e918612452a ``` Example output: ```bash Content of 's3://1000genomes' and path 'null': Type | Name | Size --------+--------------------------------------------+---------- FILE | 20131219.populations.tsv | 1663 FILE | 20131219.superpopulations.tsv | 97 FILE | CHANGELOG | 257098 FILE | README.alignment_data | 15977 FILE | README.analysis_history | 5289 FILE | README.complete_genomics_data | 5967 FILE | README.crams | 563 FILE | README.ebi_aspera_info | 935 FILE | README.ftp_structure | 8408 FILE | README.pilot_data | 2082 FILE | README.populations | 1938 FILE | README.sequence_data | 7857 FILE | README_missing_files_20150612 | 672 FILE | README_phase3_alignments_sequence_20150526 | 136 FILE | README_phase3_data_move_20150612 | 273 FILE | alignment.index | 3579471 FILE | analysis.sequence.index | 54743580 FILE | exome.alignment.index | 3549051 FILE | sequence.index | 67069489 FOLDER | 1000G_2504_high_coverage/ | 0 FOLDER | alignment_indices/ | 0 FOLDER | changelog_details/ | 0 FOLDER | complete_genomics_indices/ | 0 FOLDER | data/ | 0 FOLDER | hgsv_sv_discovery/ | 0 FOLDER | phase1/ | 0 FOLDER | phase3/ | 0 FOLDER | pilot_data/ | 0 FOLDER | release/ | 0 FOLDER | sequence_indices/ | 0 FOLDER | technical/ | 0 ``` ## tw data-links download Download data link contents. ```bash tw data-links download [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-c`, `--credentials` | Credentials identifier. **Required for private cloud storage buckets** | Yes | `null` | | `-o`, `--output-dir` | Output directory for downloaded files | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Data link identifier | No | `null` | | `-n`, `--name` | Data link name | No | `null` | | `--uri` | Data link URI (e.g., s3://bucket-name) | No | `null` | Run `tw data-links download -h` to view all the required and optional fields for downloading files and directories from a data-link in a workspace. #### Download files Command: ```bash tw data-links download -n my-bucket -c 1sxCxvxfx8xnxdxGxQxqxH -w 123456789012345 path/to/file.txt ``` Example output: ```bash Downloading file: file.txt .... Progress: [========================================] 100% (269/269 KBs, ETA: 0.0s) Successfully downloaded files Type | File count | Path ------+------------+----------------------------------- FILE | 1 | file.txt ``` #### Download directories Command: ```bash tw data-links download -n my-bucket -c 1sxCxvxfx8xnxdxGxQxqxH -w 123456789012345 path/to/my-directory/ ``` Example output: ```bash Downloading file: my-directory/file.txt .... Progress: [========================================] 100% (5/5 bytes, ETA: 0.0s) Successfully downloaded files Type | File count | Path --------+------------+--------------- FOLDER | 1 | my-directory/ ``` ## tw data-links upload Upload files to a data link. ```bash tw data-links upload [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-c`, `--credentials` | Credentials identifier. **Required for private cloud storage buckets** | Yes | `null` | | `-o`, `--output-dir` | Destination directory in the data link | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Data link identifier | No | `null` | | `-n`, `--name` | Data link name | No | `null` | | `--uri` | Data link URI (e.g., s3://bucket-name) | No | `null` | Run `tw data-links upload -h` to view all the required and optional fields for uploading files and directories to a data-link in a workspace. #### Upload files Command: ```bash tw data-links upload -n my-bucket -c 1sxCxvxfx8xnxdxGxQxqxH -w 123456789012345 path/to/file.txt ``` Example output: ```bash Fetching data-links. Waiting DONE status....FETCHING.........DONE [DONE] Uploading file: file.txt .... Progress: [========================================] 100% (269/269 KBs, ETA: 0.0s) Successfully uploaded files Type | File count | Path ------+------------+----------------------------------- FILE | 1 | file.txt ``` #### Upload directories Command: ```bash tw data-links upload -n my-bucket -c 1sxCxvxfx8xnxdxGxQxqxH -w 123456789012345 path/to/my-directory/ ``` Example output: ```bash Uploading file: my-directory/file.txt .... Progress: [========================================] 100% (5/5 bytes, ETA: 0.0s) Successfully uploaded files Type | File count | Path --------+------------+--------------- FOLDER | 1 | my-directory/ ``` --- ## tw datasets Run `tw datasets -h` to view the list of supported operations. [Datasets](https://docs.seqera.io/platform-cloud/data/datasets) are CSV (comma-separated values) and TSV (tab-separated values) files stored in a workspace, used as inputs during pipeline execution. The most commonly used datasets for Nextflow pipelines are samplesheets, where each row consists of a sample, the location of files for that sample (such as FASTQ files), and other sample details. ## tw datasets add Add a dataset. ```bash tw datasets add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Dataset name. Must be unique per workspace. Names consist of alphanumeric, hyphen, and underscore characters. | Yes | `null` | | `-d`, `--description` | Optional dataset description. | No | `null` | | `--header` | Treat first row as header | No | `null` | | `--overwrite` | Overwrite the dataset if it already exists | No | `false` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | Yes | `TOWER_WORKSPACE_ID` | Run `tw datasets add -h` to view the required and optional fields for adding a dataset. Add a preconfigured dataset file to a workspace (include the `--header` flag if the first row of your samplesheet file is a header). #### Example Command: ```bash tw datasets add --name=samplesheet1 --header samplesheet_test.csv -w 123456789012345 ``` Example output: ```bash Dataset 'samplesheet1' added at [my-organization / my-workspace] workspace with id '60gGrD4I2Gk0TUpEGOj5Td' ``` :::note The maximum supported dataset file size is 10 MB. ::: ## tw datasets delete Delete a dataset. ```bash tw datasets delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Dataset unique identifier | No | `null` | | `-n`, `--name` | Dataset name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | Yes | `TOWER_WORKSPACE_ID` | To delete a workspace dataset, specify either the dataset name (`-n` flag) or ID (`-i` flag). #### Example Command: ```bash tw datasets delete -i 6tYMjGqCUJy6dEXNK9y8kh ``` Example output: ```bash Dataset '6tYMjGqCUJy6dEXNK9y8kh' deleted at 97652229034604 workspace ``` ## tw datasets download Download a dataset. ```bash tw datasets download [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `--dataset-version` | Dataset version to download | No | `null` | | `-i`, `--id` | Dataset unique identifier | No | `null` | | `-n`, `--name` | Dataset name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | Yes | `TOWER_WORKSPACE_ID` | View a stored dataset's contents. #### Example Command: ```bash tw datasets download -n samplesheet1 ``` Example output: ```bash sample,fastq_1,fastq_2,strandedness WT_REP1,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357070_1.fastq.gz,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357070_2.fastq.gz,auto WT_REP1,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357071_1.fastq.gz,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357071_2.fastq.gz,auto WT_REP2,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357072_1.fastq.gz,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357072_2.fastq.gz,reverse RAP1_UNINDUCED_REP1,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357073_1.fastq.gz,,reverse RAP1_UNINDUCED_REP2,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357074_1.fastq.gz,,reverse RAP1_UNINDUCED_REP2,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357075_1.fastq.gz,,reverse RAP1_IAA_30M_REP1,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357076_1.fastq.gz,https://raw.githubusercontent.com/nf-core/test-datasets/rnaseq/testdata/GSE110004/SRR6357076_2.fastq.gz,reverse ``` ## tw datasets list List datasets. ```bash tw datasets list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-f`, `--filter` | Filter datasets by name substring | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | Yes | `TOWER_WORKSPACE_ID` | Run `tw datasets list -h` to view the optional fields for listing and filtering datasets. #### Example Command: ```bash tw datasets list -f data ``` Example output: ```bash Datasets at 97652229034604 workspace: ID | Name | Created ------------------------+----------+------------------------------- 6vBGj6aWWpBuLpGKjJDpZy | dataset2 | Tue, 27 Aug 2024 14:49:32 GMT ``` ## tw datasets view View dataset details. ```bash tw datasets view [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Dataset unique identifier | No | `null` | | `-n`, `--name` | Dataset name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | Yes | `TOWER_WORKSPACE_ID` | Run `tw datasets view -h` to view the required and optional fields for viewing a stored dataset's details. #### Example Command: ```bash tw datasets view -n samplesheet1 ``` Example output: ```bash Dataset at 97652229034604 workspace: -------------+------------------------------- ID | 60gGrD4I2Gk0TUpEGOj5Td Name | samplesheet1 Description | Media Type | text/csv Created | Mon, 19 Aug 2024 07:59:16 GMT Updated | Mon, 19 Aug 2024 07:59:17 GMT ``` ### tw datasets view versions Display dataset versions. ```bash tw datasets view versions [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-i`, `--id` | Dataset identifier | No | `null` | | `-n`, `--name` | Dataset name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | Personal workspace | :::note Either dataset ID (`-i`) or name (`-n`) is required to identify which dataset to view versions for. ::: #### Example Command: ```bash tw datasets view versions -n my-reference-data -w 123456789012345 ``` Example output: ```bash Versions for dataset 'my-reference-data' at [my-organization / my-workspace] workspace: Version | Created | Size --------|--------------------------------|-------- v1.0 | Mon, 19 Aug 2024 07:59:16 GMT | 1.2 MB v1.1 | Tue, 20 Aug 2024 10:15:23 GMT | 1.3 MB v2.0 | Wed, 21 Aug 2024 14:30:45 GMT | 2.1 MB ``` ## tw datasets update Update a dataset. ```bash tw datasets update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `--new-name` | Updated dataset name. Must be unique per workspace. Names consist of alphanumeric, hyphen, and underscore characters. | No | `null` | | `-d`, `--description` | Updated dataset description. | No | `null` | | `--header` | Treat first row as header | No | `null` | | `-f`, `--file` | Data file to upload | No | `null` | | `-i`, `--id` | Dataset unique identifier | No | `null` | | `-n`, `--name` | Dataset name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | Yes | `TOWER_WORKSPACE_ID` | Run `tw datasets update -h` to view the required and optional fields for updating a dataset. #### Example Command: ```bash tw datasets update -n dataset1 --new-name=dataset2 -f samplesheet_test.csv ``` Example output: ```bash Dataset 'dataset1' updated at 97652229034604 workspace with id '6vBGj6aWWpBuLpGKjJDpZy' ``` ## tw datasets url Get dataset URL. ```bash tw datasets url [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `--dataset-version` | Dataset version for URL | No | `null` | | `-i`, `--id` | Dataset unique identifier | No | `null` | | `-n`, `--name` | Dataset name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | Yes | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw datasets url -i 3m4n5o6p7q8r9s0t1u2v3w -w 123456789012345 ``` Example output: ```bash Dataset URL ----------- https://api.cloud.seqera.io/workspaces/123456789012345/datasets/3m4n5o6p7q8r9s0t1u2v3w/v/1/n/samplesheet.csv ``` --- ## tw info Show system info and health status. #### Example Command: ```bash tw info ``` Example output: ```bash Details -------------------------+----------------------------- Tower API endpoint | https://api.cloud.seqera.io Tower API version | 1.97.0 Tower version | 26.1.0-cycle37 CLI version | 0.20.0 (ef1335d) CLI minimum API version | 1.37.0 Authenticated user | sai-user System health status ---------------------------------------+---- Remote API server connection check | OK Tower API version check | OK Authentication API credential's token | OK ``` --- ## tw labels Manage workspace [labels](https://docs.seqera.io/platform-cloud/labels/overview) and [resource labels](https://docs.seqera.io/platform-cloud/resource-labels/overview). Run `tw labels -h` to view supported label operations. ## tw labels add Add a label. ```bash tw labels add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Label name | Yes | `null` | | `-v`, `--value` | Label value | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | Run `tw labels add -h` to view the required and optional fields for adding a label. :::note [Resource labels](https://docs.seqera.io/platform-cloud/resource-labels/overview) consist of a `name=value` pair and can only be applied to compute environments, pipelines, runs, and actions. [Labels](https://docs.seqera.io/platform-cloud/labels/overview) require only a name and can be applied to pipelines, runs, and actions. ::: #### Examples **Example 1: Add a resource label (with value)** Command: ```bash tw labels add -n environment -v production -w 123456789012345 ``` Example output: ```bash Label 'environment=production' added at [my-organization / my-workspace] workspace with id '268741348267491' ``` **Example 2: Add a regular label (name only)** Command: ```bash tw labels add -n high-priority -w 123456789012345 ``` Example output: ```bash Label 'high-priority' added at [my-organization / my-workspace] workspace with id '268741348267492' ``` :::tip Resource labels (with values) are useful for cost tracking and filtering cloud resources. Regular labels are useful for categorizing and organizing pipelines, runs, and actions within Platform. ::: ## tw labels list List labels. ```bash tw labels list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-t`, `--type` | Label type: normal, resource, or all (default: all) | No | `all` | | `-f`, `--filter` | Filter labels by substring | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display (default: ) | No | `null` | Run `tw labels list -h` to view the optional fields for filtering labels. #### Example Command: ```bash tw labels list ``` Example output: ```bash Labels at 97652229034604 workspace: ID | Name | Value | Type -----------------+------------------------+-----------+---------- 116734717739444 | manual-fusion-amd64 | | Normal 120599302764779 | test-with-prefix | | Normal 128477232893714 | manual-fusion-arm64 | | Normal 214201679620273 | test-config-link | | Normal 244634136444435 | manual-nonfusion-amd64 | | Normal 9184612610501 | Resource1 | Value1 | Resource ``` ## tw labels update Update a label. ```bash tw labels update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Label identifier | Yes | `null` | | `-n`, `--name` | Label name | No | `null` | | `-v`, `--value` | Label value | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | Run `tw labels update -h` to view the required and optional fields for updating labels. #### Example Command: ```bash tw labels update -i 444555666777888 -n label3 -w 123456789012345 ``` Example output: ```bash Label with id '444555666777888' at '123456789012345' workspace updated to 'label3' ``` ## tw labels delete Delete a label. ```bash tw labels delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Label ID | Yes | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | Run `tw labels delete -h` to view the required and optional fields for deleting labels. #### Example Command: ```bash tw labels delete -i 203879852150462 ``` Example output: ```bash Label '203879852150462' deleted at '97652229034604' workspace ``` --- ## tw launch Launch a pipeline. ```bash tw launch [OPTIONS] ``` Run `tw launch -h` to view supported launch options. The `` parameter can be: - **Saved pipeline name**: Launch a pre-configured pipeline from your workspace Launchpad (e.g., `nf-hello-2026`) - **Git repository URL**: Launch directly from a pipeline repository (e.g., `https://github.com/nextflow-io/hello`) Use saved pipeline names for pre-configured workflows with specific parameters and compute environments. Use Git URLs for ad-hoc pipeline execution or when launching pipelines not yet saved to the workspace. ## Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `--params-file` | Pipeline parameters in JSON or YAML format. Provide the path to a file containing the content. | No | `null` | | `-c`, `--compute-env` | Compute environment identifier where the pipeline will run. Defaults to workspace primary compute environment if omitted. Provide the name or identifier. | No | `null` | | `-n`, `--name` | Custom run name for the workflow execution. | No | `null` | | `--work-dir` | Work directory path where workflow intermediate files are stored. Defaults to compute environment work directory if omitted. | No | `null` | | `-p`, `--profile` | Array of Nextflow configuration profile names to apply. | No | `null` | | `-r`, `--revision` | Git [revision, branch, or tag](https://docs.seqera.io/platform-cloud/pipelines/revision) to use. Use `--commit-id` to pin a specific commit within that revision. | No | `null` | | `--commit-id` | Specific Git commit hash to [pin](https://docs.seqera.io/platform-cloud/pipelines/revision) the pipeline execution to. | No | `null` | | `--version-id` | Launch a specific saved [pipeline version](https://docs.seqera.io/platform-cloud/pipelines/versioning) by version identifier. Available when launching a saved pipeline name from the Launchpad. | No | `null` | | `--version-name` | Launch a specific saved [pipeline version](https://docs.seqera.io/platform-cloud/pipelines/versioning) by version name. Available when launching a saved pipeline name from the Launchpad. | No | `null` | | `--wait` | Wait until workflow reaches specified status: SUBMITTED, RUNNING, SUCCEEDED, FAILED, CANCELLED | No | `null` | | `-l`, `--labels` | Labels to assign to each pipeline run. Provide comma-separated label values (use key=value format for resource labels). Labels will be created if they don't exist | No | `null` | | `--launch-container` | Container image to use for the Nextflow launcher. | No | `null` | | `--config` | Nextflow configuration as text (overrides config files). Provide the path to a file containing the content. | No | `null` | | `--pre-run` | Add a script that executes in the nf-launch script prior to invoking Nextflow processes. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--post-run` | Add a script that executes after all Nextflow processes have completed. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--pull-latest` | Pull the latest version of the pipeline from the repository. | No | `null` | | `--stub-run` | Execute a stub run for testing (processes return dummy results). | No | `null` | | `--main-script` | Alternative main script filename. Default: `main.nf`. | No | `null` | | `--entry-name` | Workflow entry point name when using Nextflow DSL2. | No | `null` | | `--schema-name` | Name of the pipeline schema to use. | No | `null` | | `--user-secrets` | Array of user secrets to make available to the pipeline. | No | `null` | | `--workspace-secrets` | Array of workspace secrets to make available to the pipeline. | No | `null` | | `--disable-optimization` | Turn off the optimization for the pipeline before launching. | No | `null` | | `--head-job-cpus` | Number of CPUs allocated for the Nextflow head job. | No | `null` | | `--head-job-memory` | Memory allocation for the Nextflow head job in megabytes. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw launch -w 123456789012345 nf-hello-2026 ``` Example output: ```bash Workflow 7q8r9s0t1u2v3 submitted at [my-organization-updated / my-workspace] workspace. https://cloud.seqera.io/orgs/my-organization-updated/workspaces/my-workspace/watch/7q8r9s0t1u2v3 ``` ## Pipeline versions and source revision For saved Launchpad pipelines, target a published version by name or ID: ```bash tw launch \ -w 123456789012345 \ --version-name my-pipeline-2 \ my-pipeline ``` If you do not provide `--version-id` or `--version-name`, the CLI launches the pipeline's default saved version. For direct Git URL launches, use `--revision` and optionally `--commit-id` to control the source revision: ```bash tw launch \ -w 123456789012345 \ --revision main \ --commit-id a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 \ https://github.com/nextflow-io/hello ``` --- ## tw members Run `tw members -h` to view supported member operations. Manage organization members. Organization membership management requires organization `OWNER` permissions. ## tw members list List organization members. ```bash tw members list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-o`, `--organization` | Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'. | Yes | `null` | | `-f`, `--filter` | Filter members by username prefix. Case-insensitive prefix matching on the username field (e.g., 'john' matches 'john.doe'). | No | `null` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display (default: ) | No | `null` | Run `tw members list -h` view all the optional fields for listing organization members. #### Example Command: ```bash tw members list -o TestOrg2 ``` Example output: ```bash Members for TestOrg2 organization: ID | Username | Email | Role -----------------+----------------------+---------------------------------+-------- 200954501314303 | user1 | user1@domain.com | MEMBER 277776534946151 | user2 | user2@domain.com | MEMBER 243277166855716 | user3 | user3@domain.com | OWNER ``` ## tw members add Add an organization member. ```bash tw members add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-u`, `--user` | User email address to invite. If the user doesn't have a Seqera Platform account, they will receive an invitation email to join the organization. | Yes | `null` | | `-o`, `--organization` | Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'. | Yes | `null` | Run `tw members add -h` view all the required and optional fields for adding organization members. #### Example Command: ```bash tw members add -u user1@domain.com -o DocTestOrg2 ``` Example output: ```bash Member 'user1' with ID '134534064600266' was added in organization 'TestOrg2' ``` ## tw members delete Remove an organization member. ```bash tw members delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-u`, `--user` | Username or email address of the member to remove. Removes the user from the organization and all associated teams and workspaces. Use 'tw members leave' to remove yourself. | Yes | `null` | | `-o`, `--organization` | Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'. | Yes | `null` | Run `tw members delete -h` view all the required and optional fields for deleting organization members. #### Example Command: ```bash tw members delete -u user1 -o TestOrg2 ``` Example output: ```bash Member 'user1' deleted from organization 'TestOrg2' ``` ## tw members update Update an organization member role. ```bash tw members update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-u`, `--user` | Username or email address of the member to update. Specify either their platform username or email address. | Yes | `null` | | `-r`, `--role` | Organization role to assign. OWNER: full administrative access including member management and billing. MEMBER: standard access with ability to create workspaces and teams. COLLABORATOR: limited access, cannot create resources but can participate in shared workspaces. | Yes | `null` | | `-o`, `--organization` | Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'. | Yes | `null` | Run `tw members update -h` view all the required and optional fields for updating organization members. #### Example Command: ```bash tw members update -u user1 -r OWNER -o TestOrg2 ``` Example output: ```bash Member 'user1' updated to role 'owner' in organization 'TestOrg2' ``` ## tw members leave Leave an organization. ```bash tw members leave [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-o`, `--organization` | Organization name or numeric ID to leave. Removes yourself from the organization and all associated teams and workspaces. Cannot be undone except by another member re-inviting you. | Yes | `null` | Run `tw members leave -o ` to be removed from the given organization's members. #### Example Command: ```bash tw members leave -o example-organization ``` Example output: ```bash You have been removed from organization 'example-organization' ``` --- ## tw organizations Run `tw organizations -h` to view supported workspace operations. Organizations are the top-level structure and contain workspaces, members, and teams. You can also add external collaborators to an organization. See [Organization management](https://docs.seqera.io/platform-cloud/orgs-and-teams/organizations) for more information. ## tw organizations list List organizations. ```bash tw organizations list [OPTIONS] ``` #### Example Command: ```bash tw organizations list ``` Example output: ```bash Organizations for user-name user: ID | Name -----------------+------------------------------ 111222333444556 | organization1 111222333444557 | organization7 111222333444558 | organization8 111222333444559 | organization3 111222333444560 | organization2 111222333444561 | organization4 111222333444555 | my-organization 111222333444562 | organization5 ``` ## tw organizations add Add an organization. ```bash tw organizations add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Organization unique name. Must be unique across Seqera Platform. Used as the organization identifier in URLs and API calls. Cannot be changed after creation without --new-name. | Yes | `null` | | `-f`, `--full-name` | Organization display name. The full, human-readable name for the organization shown in the UI. Can contain spaces and special characters. | Yes | `null` | | `--overwrite` | Overwrite existing organization. If an organization with this name already exists, delete it first before creating the new one. Use with caution as this permanently deletes the existing organization and all associated data. | No | `false` | | `-d`, `--description` | Organization description. Free-text description providing context about the organization's purpose, team, or projects. | No | `null` | | `-l`, `--location` | Organization location. Geographic location or region where the organization is based (e.g., 'San Francisco, CA' or 'EU'). | No | `null` | | `-w`, `--website` | Organization website URL. Public website or documentation site for the organization. Must be a valid URL (e.g., https://example.com). | No | `null` | Run `tw organizations add -h` to view the required and optional fields for adding your workspace. #### Example Command: ```bash tw organizations add -n TestOrg2 -f 2nd\ Test\ Organization\ LLC -l RSA ``` Example output: ```bash Organization 'TestOrg2' with ID '204336622618177' was added ``` ## tw organizations view View organization details. ```bash tw organizations view [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Organization numeric identifier. The unique ID assigned when the organization was created. | No | `null` | | `-n`, `--name` | Organization name. The unique organization name used as a human-readable identifier. | No | `null` | #### Example Command: ```bash tw organizations view -n my-organization ``` Example output: ```bash Details for organization 'My organization LLC' -------------+--------------------------------------------------- ID | 111222333444555 Name | my-organization Full Name | My organization LLC Description | Organization created with seqerakit CLI scripting Website | https://example.com/ ``` ## tw organizations update Update an organization. ```bash tw organizations update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `--new-name` | New unique name for the organization. Changes the organization's identifier. Must be unique across Seqera Platform. Updates URLs and API references. | No | `null` | | `-f`, `--full-name` | New display name for the organization. The full, human-readable name shown in the UI. Can contain spaces and special characters. | No | `null` | | `-i`, `--id` | Organization numeric identifier. The unique ID assigned when the organization was created. | No | `null` | | `-n`, `--name` | Organization name. The unique organization name used as a human-readable identifier. | No | `null` | | `-d`, `--description` | Organization description. Free-text description providing context about the organization's purpose, team, or projects. | No | `null` | | `-l`, `--location` | Organization location. Geographic location or region where the organization is based (e.g., 'San Francisco, CA' or 'EU'). | No | `null` | | `-w`, `--website` | Organization website URL. Public website or documentation site for the organization. Must be a valid URL (e.g., https://example.com). | No | `null` | #### Example Command: ```bash tw organizations update -n my-organization --new-name=my-organization-updated ``` Example output: ```bash Organization 'my-organization' was updated ``` ## tw organizations delete Delete an organization. ```bash tw organizations delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Organization numeric identifier. The unique ID assigned when the organization was created. | No | `null` | | `-n`, `--name` | Organization name. The unique organization name used as a human-readable identifier. | No | `null` | #### Example Command: ```bash tw organizations delete -n organization4 ``` Example output: ```bash Organization 'organization4' deleted ``` --- ## tw participants Run `tw participants -h` to view supported participant operations. Manage [workspace participants](https://docs.seqera.io/platform-cloud/orgs-and-teams/workspace-management). :::note The operations listed below require workspace `OWNER` or `ADMIN` permissions. ::: ## tw participants list List workspace participants. ```bash tw participants list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-t`, `--type` | Participant type to list (MEMBER, TEAM, COLLABORATOR). | No | `null` | | `-f`, `--filter` | Show only participants that it's name starts with the given word. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | Yes | `TOWER_WORKSPACE_ID` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display (default: ) | No | `null` | #### Example Command: ```bash tw participants list ``` Example output: ```bash Participants for 'my-tower-org/shared-workspace' workspace: ID | Participant Type | Name | Workspace Role ----------------+------------------+-----------------------------+---------------- 45678460861822 | MEMBER | user (user@mydomain.com) | owner ``` ## tw participants add Add a workspace participant. ```bash tw participants add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Team name, username or email for existing organization member. | Yes | `null` | | `-t`, `--type` | Type of participant (MEMBER, COLLABORATOR or TEAM). | Yes | `null` | | `--overwrite` | Overwrite the participant if it already exists. | No | `false` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | Yes | `TOWER_WORKSPACE_ID` | Run `tw participants add -h` to view the required and optional fields for adding a participant. To add a new participant to the workspace, use the `add` subcommand. When adding a COLLABORATOR type participant, the default role assigned is `Launch`. For MEMBER type participants, you can specify organization members who will have access to the workspace. See [Participant roles](https://docs.seqera.io/platform-cloud/orgs-and-teams/roles) for more information. #### Example Command: ```bash tw participants add --name=collaborator@mydomain.com --type=COLLABORATOR -w 123456789012345 ``` Example output: ```bash User 'collaborator@mydomain.com' was added as participant to [my-organization / my-workspace] workspace with role 'launch' ``` ## tw participants update Update a participant role. ```bash tw participants update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Team name, username or email for existing organization member. | Yes | `null` | | `-t`, `--type` | Type of participant (MEMBER, COLLABORATOR or TEAM). | Yes | `null` | | `-r`, `--role` | Workspace participant role (OWNER, ADMIN, MAINTAIN, LAUNCH, CONNECT or VIEW). | Yes | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | Yes | `TOWER_WORKSPACE_ID` | To update the role of a _Collaborator_ to `ADMIN` or `MAINTAIN`, use the `update` subcommand: #### Example Command: ```bash tw participants update --name=collaborator@mydomain.com --type=COLLABORATOR --role=MAINTAIN ``` Example output: ```bash Participant 'collaborator@mydomain.com' has now role 'maintain' for workspace 'shared-workspace' ``` ## tw participants delete Remove a workspace participant. ```bash tw participants delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Team name, username or email for existing organization member. | Yes | `null` | | `-t`, `--type` | Type of participant (MEMBER, COLLABORATOR or TEAM). | Yes | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | Yes | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw participants delete -n user2-name -t MEMBER -w 123456789012345 ``` Example output: ```bash Participant 'user2-name' was removed from 'my-workspace' workspace ``` :::note Requires participant name, type, and workspace ID. ::: ## tw participants leave Leave a workspace. ```bash tw participants leave [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | Yes | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw participants leave -w organization5/test-workspace ``` Example output: ```bash You have been removed as a participant from 'test-workspace' workspace ``` --- ## tw pipeline-schemas Run `tw pipeline-schemas -h` to view the list of supported operations. [Pipeline schemas](https://docs.seqera.io/platform-cloud/pipeline-schema/overview#seqera-platform-schema) let you persist a Nextflow parameter schema in Platform and reuse it when creating or updating saved pipelines. ## tw pipeline-schemas add Add a pipeline schema. ```bash tw pipeline-schemas add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-c`, `--content` | Path to a file containing the pipeline schema content. | Yes | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw pipeline-schemas add \ -c ./nextflow_schema.json \ -w 123456789012345 ``` Example output: ```bash New pipeline schema '98765' added at [my-organization / my-workspace] workspace ``` After uploading a schema, use the returned schema ID with `tw pipelines add --pipeline-schema-id` or `tw pipelines update --pipeline-schema-id` to attach the persisted schema to a saved pipeline. --- ## tw pipelines Run `tw pipelines -h` to view the list of supported operations. Pipelines define pre-configured workflows in a workspace. A saved pipeline includes the repository source, launch parameters, compute environment, and, in newer Platform releases, optional persisted schemas and multiple saved versions. ## Pipeline versioning Seqera Platform CLI `0.24` adds support for [pipeline versioning](https://docs.seqera.io/platform-cloud/pipelines/versioning) workflows: - create a saved pipeline with an initial version name - list saved versions for a pipeline - target a specific version by `--version-id` or `--version-name` - promote a version to default - update a versionable field and let Platform create a new version ## tw pipelines list List pipelines. ```bash tw pipelines list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-f`, `--filter` | Show only pipelines that contain the given word | No | `null` | | `--visibility` | Show pipelines: OWNER, MEMBER, COLLABORATOR [default: private]. | No | `private` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display | No | `null` | #### Example ```bash tw pipelines list -w 123456789012345 ``` Example output: ```bash Pipelines at [my-organization-updated / my-workspace] workspace: ID | Name | Repository | Visibility -----------------+----------------------+--------------------------------------+------------ 777888999000111 | rnaseq4 | https://github.com/nf-core/rnaseq | SHARED 888999000111222 | nf-core-rnaseq | https://github.com/nf-core/rnaseq | SHARED 999000111222333 | rnaseq2 | https://github.com/nf-core/rnaseq | SHARED 555666777888999 | nextflow-hello-saved | https://github.com/nextflow-io/hello | SHARED 000111222333444 | rnaseqapitest | https://github.com/nf-core/rnaseq | SHARED 111222333444555 | rnaseq3 | https://github.com/nf-core/rnaseq | SHARED ``` ## tw pipelines add Add a pipeline. ```bash tw pipelines add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Pipeline name. Must be unique within the workspace. | Yes | `null` | | `` | Pipeline repository URL. Must be a full Git repository URL. | Yes | `null` | | `-d`, `--description` | Pipeline description. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | | `--labels` | Labels to apply to the resource. Provide comma-separated label values (use key=value format for resource labels). Labels will be created if they do not exist. | No | `null` | | `--version-name` | Initial pipeline version name. | No | `null` | | `--pipeline-schema-id` | Pipeline schema identifier to attach to the saved pipeline. | No | `null` | | `-c`, `--compute-env` | Compute environment identifier where the pipeline will run. Defaults to workspace primary compute environment if omitted. Provide the name or identifier. | No | `null` | | `--work-dir` | Work directory path where workflow intermediate files are stored. Defaults to compute environment work directory if omitted. | No | `null` | | `-p`, `--profile` | Array of Nextflow configuration profile names to apply. | No | `null` | | `--params-file` | Pipeline parameters in JSON or YAML format. Provide the path to a file containing the content. | No | `null` | | `--revision` | Git [revision, branch, or tag](https://docs.seqera.io/platform-cloud/pipelines/revision) to use. Use `--commit-id` to pin a specific commit within that revision. | No | `null` | | `--commit-id` | Specific Git commit hash to pin the saved pipeline to. | No | `null` | | `--config` | Nextflow configuration as text (overrides config files). Provide the path to a file containing the content. | No | `null` | | `--pre-run` | Add a script that executes in the nf-launch script prior to invoking Nextflow processes. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--post-run` | Add a script that executes after all Nextflow processes have completed. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--pull-latest` | Pull the latest version of the pipeline from the repository. | No | `null` | | `--stub-run` | Execute a stub run for testing (processes return dummy results). | No | `null` | | `--main-script` | Alternative main script filename. Default: `main.nf`. | No | `null` | | `--entry-name` | Workflow entry point name when using Nextflow DSL2. | No | `null` | | `--schema-name` | Name of the pipeline schema to use. | No | `null` | | `--user-secrets` | Array of user secrets to make available to the pipeline. | No | `null` | | `--workspace-secrets` | Array of workspace secrets to make available to the pipeline. | No | `null` | #### Example ```bash tw pipelines add \ --name my-rnaseq \ --version-name v1.0 \ --pipeline-schema-id 98765 \ --revision main \ --commit-id a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 \ --params-file my-rnaseq-params.yaml \ -w 123456789012345 \ https://github.com/nextflow-io/rnaseq-nf ``` Example output: ```bash New pipeline 'my-rnaseq' added at [my-organization / my-workspace] workspace ``` Use `--pipeline-schema-id` with a schema uploaded by `tw pipeline-schemas add` to make that schema part of the saved pipeline definition in Platform. ## tw pipelines view View pipeline details. ```bash tw pipelines view [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline identifier | No | `null` | | `-n`, `--name` | Pipeline name | No | `null` | | `--version-id` | Pipeline version identifier | No | `null` | | `--version-name` | Pipeline version name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | If no version is specified, `view` shows the default saved version. #### Example ```bash tw pipelines view -n my-rnaseq --version-name v1.0 -w 123456789012345 ``` The output includes version metadata such as the version name, whether it is the default version, and the version hash, followed by the resolved launch configuration. ## tw pipelines update Update a pipeline. ```bash tw pipelines update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline identifier | No | `null` | | `-n`, `--name` | Pipeline name | No | `null` | | `--version-id` | [Pipeline version](https://docs.seqera.io/platform-cloud/pipelines/versioning) identifier to update. If omitted, the default saved version is updated. | No | `null` | | `--version-name` | [Pipeline version](https://docs.seqera.io/platform-cloud/pipelines/versioning) name to update. If omitted, the default saved version is updated. | No | `null` | | `-d`, `--description` | Pipeline description | No | `null` | | `--new-name` | Pipeline new name | No | `null` | | `--pipeline` | Nextflow pipeline URL | No | `null` | | `--allow-draft` | If versionable fields change, keep the new version as an unnamed draft instead of auto-naming and promoting it to default. | No | `false` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | | `--pipeline-schema-id` | [Pipeline schema](https://docs.seqera.io/platform-cloud/pipeline-schema/overview#seqera-platform-schema) identifier to attach to the saved pipeline. | No | `null` | | `-c`, `--compute-env` | Compute environment identifier where the pipeline will run. Defaults to workspace primary compute environment if omitted. Provide the name or identifier. | No | `null` | | `--work-dir` | Work directory path where workflow intermediate files are stored. Defaults to compute environment work directory if omitted. | No | `null` | | `-p`, `--profile` | Array of Nextflow configuration profile names to apply. | No | `null` | | `--params-file` | Pipeline parameters in JSON or YAML format. Provide the path to a file containing the content. | No | `null` | | `--revision` | Git [revision, branch, or tag](https://docs.seqera.io/platform-cloud/pipelines/revision) to use. Use `--commit-id` to pin a specific commit within that revision. | No | `null` | | `--commit-id` | Specific Git commit hash to pin the saved pipeline to. | No | `null` | | `--config` | Nextflow configuration as text (overrides config files). Provide the path to a file containing the content. | No | `null` | | `--pre-run` | Add a script that executes in the nf-launch script prior to invoking Nextflow processes. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--post-run` | Add a script that executes after all Nextflow processes have completed. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--pull-latest` | Pull the latest version of the pipeline from the repository. | No | `null` | | `--stub-run` | Execute a stub run for testing (processes return dummy results). | No | `null` | | `--main-script` | Alternative main script filename. Default: `main.nf`. | No | `null` | | `--entry-name` | Workflow entry point name when using Nextflow DSL2. | No | `null` | | `--schema-name` | Name of the pipeline schema to use. | No | `null` | | `--user-secrets` | Array of user secrets to make available to the pipeline. | No | `null` | | `--workspace-secrets` | Array of workspace secrets to make available to the pipeline. | No | `null` | Version-aware update behavior: - Non-versioned changes are applied in place. - Changing versioned launch fields such as repository revision can cause Platform to create a new saved version. - By default, the CLI auto-names that new version and promotes it to the default Launchpad version. - With `--allow-draft`, the CLI leaves the new [version](https://docs.seqera.io/platform-cloud/pipelines/versioning) as a draft so you can manage it later with `tw pipelines versions`. #### Example ```bash tw pipelines update \ --name my-rnaseq \ --version-name v1.0 \ --revision release-branch \ --allow-draft ``` Example output: ```bash Pipeline 'my-rnaseq' updated at [my-organization / my-workspace] workspace New draft version 'draft789' created. Use 'tw pipelines versions' to manage it. ``` ## tw pipelines versions list List saved [pipeline versions](https://docs.seqera.io/platform-cloud/pipelines/versioning). ```bash tw pipelines versions list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline identifier | No | `null` | | `-n`, `--name` | Pipeline name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | | `-f`, `--filter` | Search pipeline versions by name prefix. Also supports keyword filters: `versionName`, `versionId`, `versionHash`. | No | `null` | | `--is-published` | Show only published pipeline versions if `true`, draft versions only if `false`, or all versions by default. | No | all versions | | `--full-hash` | Show full-length hash values without truncation. | No | `false` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display | No | `null` | #### Example ```bash tw pipelines versions list \ -n my-rnaseq \ --is-published true \ --full-hash ``` This command shows each version's ID, name, default status, hash, creator, and creation time. ## tw pipelines versions manage Manage a [pipeline version](https://docs.seqera.io/platform-cloud/pipelines/versioning) name or default status. ```bash tw pipelines versions manage [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline identifier | No | `null` | | `-n`, `--name` | Pipeline name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | | `--version-id` | Pipeline version identifier | No | `null` | | `--version-name` | Pipeline version name | No | `null` | | `--new-name` | New name for the pipeline version | No | `null` | | `--set-default` | Set this version as the default | No | `null` | Provide at least one of `--new-name` or `--set-default`. #### Example ```bash tw pipelines versions manage \ -n my-rnaseq \ --version-id 7TnlaOKANkiDIdDqOO2kCs \ --set-default \ --new-name v2.0 ``` Example output: ```bash Pipeline version '7TnlaOKANkiDIdDqOO2kCs' of pipeline 'my-rnaseq' updated at workspace [my-organization / my-workspace] ``` ## tw pipelines delete Remove a pipeline. ```bash tw pipelines delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline identifier | No | `null` | | `-n`, `--name` | Pipeline name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | #### Example ```bash tw pipelines delete -n my-rnaseq -w 123456789012345 ``` ## tw pipelines export Export a pipeline. ```bash tw pipelines export [OPTIONS] [FILENAME] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline identifier | No | `null` | | `-n`, `--name` | Pipeline name | No | `null` | | `--version-id` | Pipeline version identifier | No | `null` | | `--version-name` | Pipeline version name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | If you do not provide a version selector, `export` uses the default saved version. #### Example ```bash tw pipelines export -n my-rnaseq --version-name v2.0 my-rnaseq-export.json ``` ## tw pipelines import Add a pipeline from file content. ```bash tw pipelines import [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Pipeline name | Yes | `null` | | `-c`, `--compute-env` | Compute environment name (defaults to value defined in the JSON file) | No | `null` | | `--overwrite` | Overwrite the pipeline if it already exists. | No | `false` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | #### Example ```bash tw pipelines import -n my-rnaseq-imported -w 123456789012345 my-rnaseq-export.json ``` ## tw pipelines labels Manage pipeline labels. ```bash tw pipelines labels [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline identifier | No | `null` | | `-n`, `--name` | Pipeline name | No | `null` | | `--no-create` | Assign labels without creating the ones that were not found. | No | `null` | | `--operations`, `-o` | Type of operation (`set`, `append`, `delete`) [default: `set`]. | No | `set` | #### Example ```bash tw pipelines labels -n my-rnaseq -w 123456789012345 project=demo ``` :::tip The `--params-file` flag is used to pass default launch parameters that are associated with the saved pipeline in the Launchpad. ::: :::tip The `--config` file must use [Nextflow configuration](https://docs.seqera.io/nextflow/config#config-syntax) syntax. ::: --- ## tw runs Manage pipeline runs. Run `tw runs -h` to view supported runs operations. Runs display all the current and previous pipeline runs in the specified workspace. Each new or resumed run is given a random name such as _grave_williams_ by default, which can be overridden with a custom value at launch. See [Run details](https://docs.seqera.io/platform-cloud/monitoring/run-details) for more information. As a run executes, it can transition through the following states: - `submitted`: Pending execution - `running`: Running - `succeeded`: Completed successfully - `failed`: Successfully executed, where at least one task failed with a terminate [error strategy](https://docs.seqera.io/nextflow/process#errorstrategy) - `cancelled`: Stopped manually during execution - `unknown`: Indeterminate status ## tw runs view View pipeline run details. ```bash tw runs view [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline run identifier. The unique workflow ID to display details for. Use additional flags to control which sections are shown. | Yes | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | | `--config` | Display Nextflow configuration used for this workflow execution. | No | `null` | | `--params` | Display pipeline parameters provided at launch time in JSON or YAML format. | No | `null` | | `--command` | Display the Nextflow run command used to execute this workflow. | No | `null` | | `--status` | Display current workflow execution status (SUBMITTED, RUNNING, SUCCEEDED, FAILED, CANCELLED). | No | `null` | | `--processes` | Display per-process execution progress showing pending, running, succeeded, failed, and cached task counts. | No | `null` | | `--stats` | Display workflow execution statistics including compute time, task counts, success/failure percentages, and cached task efficiency. | No | `null` | | `--load` | Display real-time resource usage including active tasks, CPU cores, memory consumption, and I/O metrics. | No | `null` | | `--utilization` | Display resource efficiency metrics showing CPU and memory utilization percentages across workflow execution. | No | `null` | | `--metrics-memory` | Display memory usage statistics per process including mean, min, max, and quartile distributions (RSS, virtual memory). | No | `null` | | `--metrics-cpu` | Display CPU usage statistics per process including mean, min, max, and quartile distributions (CPU time, CPU percentage). | No | `null` | | `--metrics-time` | Display task execution time statistics per process including mean, min, max, and quartile distributions (duration, realtime). | No | `null` | | `--metrics-io` | Display I/O statistics per process including mean, min, max, and quartile distributions (read bytes, write bytes, syscalls). | No | `null` | Run `tw runs view -h` to view all the required and optional fields for viewing a pipeline's runs. #### Example Command: ```bash tw runs view -i 2vFUbBx63cfsBY -w seqeralabs/showcase ``` Example output: ```bash Run at [seqeralabs / showcase] workspace: General ---------------------+------------------------------------------------- ID | 2vFUbBx63cfsBY Operation ID | b5d55384-734e-4af0-8e47-0d3abec71264 Run name | adoring_brown Status | SUCCEEDED Starting date | Fri, 31 May 2024 10:38:30 GMT Commit ID | b89fac32650aacc86fcda9ee77e00612a1d77066 Session ID | 9365c6f4-6d79-4ca9-b6e1-2425f4d957fe Username | user1 Workdir | s3://seqeralabs-showcase/scratch/2vFUbBx63cfsBY Container | No container was reported Executors | awsbatch Compute Environment | seqera_aws_ireland_fusionv2_nvme Nextflow Version | 23.10.1 Labels | star_salmon,yeast ``` ### tw runs view download Download pipeline run files. ```bash tw runs view download [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `--type` | Type of file to download. Options: 'stdout' (standard output), 'log' (Nextflow log), 'stderr' (standard error, tasks only), 'timeline' (execution timeline HTML, workflow only). Default: stdout. | No | `stdout` | | `-t` | Task numeric identifier. When specified, downloads task-specific files (.command.out, .command.err, .command.log). When omitted, downloads workflow-level files (nextflow.log, timeline.html). | No | `null` | ### tw runs view metrics Display pipeline run metrics. ```bash tw runs view -i [OPTIONS] metrics ``` This subcommand displays resource usage metrics for pipeline runs. You must specify the run ID using the `-i` flag from the parent `tw runs view` command. #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline run identifier (from parent command). | Yes | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | Personal workspace | | `-f`, `--filter` | Filter metrics by process name. Shows statistics only for processes matching the specified name. | No | `null` | | `-t`, `--type` | Metric types to display: cpu, mem, time, io. Comma-separated list. Default: all types. | No | `null` | | `-c`, `--columns` | Statistical columns to display: min, q1, q2, q3, max, mean. Shows quartile distribution of resource usage. Default: all columns. | No | `null` | | `-v`, `--view` | Table view format. Options: condensed (compact), extended (detailed). Default: condensed. | No | `null` | #### Example Command: ```bash tw runs view -i 2vFUbBx63cfsBY --workspace 123456789012345 metrics ``` Example output: ```bash Run metrics at [my-organization / my-workspace] workspace: Process metrics for run '2vFUbBx63cfsBY': Process Name | CPU (mean) | Memory (mean) | Time (mean) | Status ----------------|------------|---------------|-------------|-------- NFCORE_RNASEQ | 95.2% | 4.2 GB | 2h 15m | COMPLETED FASTQC | 82.1% | 2.1 GB | 45m | COMPLETED STAR_ALIGN | 98.5% | 32.5 GB | 1h 30m | COMPLETED ``` ### tw runs view tasks Display pipeline run tasks. ```bash tw runs view tasks [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-c`, `--columns` | Additional task columns to display beyond the default set. Available columns: taskId, process, tag, status, hash, exit, container, nativeId, submit, duration, realtime, pcpu, pmem, peakRss, peakVmem, rchar, wchar, volCtxt, invCtxt. Comma-separated list. | No | `null` | | `-f`, `--filter` | Filter tasks by name prefix. Shows only tasks with names starting with the specified string. | No | `null` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display (default: ) | No | `null` | ### tw runs view task Display pipeline run task details. ```bash tw runs view task [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-t` | Task numeric identifier. Unique identifier for the specific task execution within the workflow run. | Yes | `null` | | `--execution-time` | Display task execution timing details including submit time, start time, completion time, duration, and realtime. | No | `null` | | `--resources-requested` | Display resources requested by the task including CPUs, memory, disk space, and time allocation. | No | `null` | | `--resources-usage` | Display actual resource consumption including CPU percentage, memory usage (RSS, peak RSS, virtual memory), and I/O statistics. | No | `null` | ## tw runs list List pipeline runs. ```bash tw runs list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-f`, `--filter` | Filter pipeline runs by run name. Performs case-insensitive substring matching on the runName field. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display (default: ) | No | `null` | Run `tw runs list -h` to view all the required and optional fields for listing runs in a workspace. #### Example Command: ```bash tw runs list ``` Example output: ```bash Pipeline runs at [seqeralabs / testing] workspace: ID | Status | Project Name | Run Name | Username | Submit Date ----------------+-----------+----------------------------+---------------------------------+-----------------------+------------------------------- 49Gb5XVMud2e7H | FAILED | seqeralabs/nf-aggregate | distraught_archimedes | user1 | Fri, 31 May 2024 16:22:10 GMT 4anNFvTUwRFDp | SUCCEEDED | nextflow-io/rnaseq-nf | nasty_kilby | user1 | Fri, 31 May 2024 15:23:12 GMT 3wo3Kfni6Kl3hO | SUCCEEDED | nf-core/proteinfold | reverent_linnaeus | user2 | Fri, 31 May 2024 15:22:38 GMT 4fIRrFgZV3eDb1 | FAILED | nextflow-io/hello | gigantic_lichterman | user1 | Mon, 29 Apr 2024 08:44:47 GMT cHEdKBXmdoQQM | FAILED | mathysgrapotte/stimulus | mighty_poitras | user3 | Mon, 29 Apr 2024 08:08:52 GMT ``` Use the optional `--filter` flag to filter the list of runs returned by one or more `keyword:value` entries: - `status` - `label` - `workflowId` - `runName` - `username` - `projectName` - `after` - `before` - `sessionId` - `is:starred` If no `keyword` is defined, the filtering is applied to the `runName`, `projectName` (the pipeline name), and `username`. :::note The `after` and `before` flags require an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp with UTC timezone (`YYYY-MM-DDThh:mm:ss.sssZ`). ::: #### Filtering examples Command: ```bash tw runs list --filter hello_slurm_20240530 ``` Example output: ```bash Pipeline runs at [seqeralabs / showcase] workspace: ID | Status | Project Name | Run Name | Username | Submit Date ---------------+-----------+-------------------+--------------------------------------+------------+------------------------------- pZeJBOLtIvP7R | SUCCEEDED | nextflow-io/hello | hello_slurm_20240530_e75584566f774e7 | user1 | Thu, 30 May 2024 09:12:51 GMT ``` Multiple filter criteria can be defined: Command: ```bash tw runs list --filter="after:2024-05-29T00:00:00.000Z before:2024-05-30T00:00:00.000Z username:user1" ``` Example output: ```bash Pipeline runs at [seqeralabs / testing] workspace: ID | Status | Project Name | Run Name | Username | Submit Date ----------------+-----------+-----------------------+--------------------+-------------+------------------------------- xJvK95W6YUmEz | SUCCEEDED | nextflow-io/rnaseq-nf | ondemand2 | user1 | Wed, 29 May 2024 20:35:28 GMT 1c1ckn9a3j0xF0 | SUCCEEDED | nextflow-io/rnaseq-nf | fargate | user1 | Wed, 29 May 2024 20:28:02 GMT 3sYX1acJ01T7rL | SUCCEEDED | nextflow-io/rnaseq-nf | min1vpcu-spot | user1 | Wed, 29 May 2024 20:27:47 GMT 4ZYJGWJCttXqXq | SUCCEEDED | nextflow-io/rnaseq-nf | min1cpu-ondemand | user1 | Wed, 29 May 2024 20:25:21 GMT 4LCxsffTqf3ysT | SUCCEEDED | nextflow-io/rnaseq-nf | lonely_northcutt | user1 | Wed, 29 May 2024 20:09:51 GMT 4Y8EcyopNiYBlJ | SUCCEEDED | nextflow-io/rnaseq-nf | fargate | user1 | Wed, 29 May 2024 18:53:47 GMT dyKevNwxK50XX | SUCCEEDED | mark814/nr-test | cheeky_cuvier | user1 | Wed, 29 May 2024 12:21:10 GMT eS6sVB5A387aR | SUCCEEDED | mark814/nr-test | evil_murdock | user1 | Wed, 29 May 2024 12:11:08 GMT ``` A leading and trailing `*` wildcard character is supported: Command: ```bash tw runs list --filter="*man/rnaseq-*" ``` Example output: ```bash Pipeline runs at [seqeralabs / testing] workspace: ID | Status | Project Name | Run Name | Username | Submit Date ----------------+-----------+---------------------+---------------------+----------------+------------------------------- 5z4AMshti4g0GK | SUCCEEDED | robnewman/rnaseq-nf | admiring_darwin | user1 | Tue, 16 Jan 2024 19:56:29 GMT 62LqiS4O4FatSy | SUCCEEDED | robnewman/rnaseq-nf | cheeky_yonath | user1 | Wed, 3 Jan 2024 12:36:09 GMT 3k2nu8ZmcBFSGv | SUCCEEDED | robnewman/rnaseq-nf | compassionate_jones | user3 | Tue, 2 Jan 2024 16:22:26 GMT 3zG2ggf5JsniNW | SUCCEEDED | robnewman/rnaseq-nf | fervent_payne | user1 | Wed, 20 Dec 2023 23:55:17 GMT 1SNIcSXRuJMSNZ | SUCCEEDED | robnewman/rnaseq-nf | curious_babbage | user3 | Thu, 28 Sep 2023 17:48:04 GMT 5lI2fZUZfiokBI | SUCCEEDED | robnewman/rnaseq-nf | boring_heisenberg | user2 | Thu, 28 Sep 2023 12:29:27 GMT 5I4lsRXIHVEjNB | SUCCEEDED | robnewman/rnaseq-nf | ecstatic_ptolemy | user2 | Wed, 27 Sep 2023 22:06:19 GMT ``` ## tw runs relaunch Relaunch a pipeline run. ```bash tw runs relaunch [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline run identifier to relaunch | Yes | `null` | | `--pipeline` | Override the pipeline to launch. Allows relaunching with a different pipeline repository URL while keeping other launch configuration settings. | No | `null` | | `--no-resume` | Start workflow execution from scratch instead of resuming from the last successful process. Use this to rerun the entire workflow without using cached results. | No | `null` | | `-n`, `--name` | Custom workflow run name. Overrides the automatically generated run name with a user-defined identifier. | No | `null` | | `--launch-container` | Container image for the Nextflow head job. Overrides the default launcher container. (BETA) | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | | `-c`, `--compute-env` | Compute environment identifier where the pipeline will run. Defaults to workspace primary compute environment if omitted. Provide the name or identifier. | No | `null` | | `--work-dir` | Work directory path where workflow intermediate files are stored. Defaults to compute environment work directory if omitted. | No | `null` | | `-p`, `--profile` | Array of Nextflow configuration profile names to apply. | No | `null` | | `--params-file` | Pipeline parameters in JSON or YAML format. Provide the path to a file containing the content. | No | `null` | | `--revision` | Git revision, branch, or tag to use. | No | `null` | | `--config` | Nextflow configuration as text (overrides config files). Provide the path to a file containing the content. | No | `null` | | `--pre-run` | Add a script that executes in the nf-launch script prior to invoking Nextflow processes. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--post-run` | Add a script that executes after all Nextflow processes have completed. See: https://docs.seqera.io/platform-cloud/launch/advanced#pre-and-post-run-scripts. Provide the path to a file containing the content. | No | `null` | | `--pull-latest` | Pull the latest version of the pipeline from the repository. | No | `null` | | `--stub-run` | Execute a stub run for testing (processes return dummy results). | No | `null` | | `--main-script` | Alternative main script filename. Default: `main.nf`. | No | `null` | | `--entry-name` | Workflow entry point name when using Nextflow DSL2. | No | `null` | | `--schema-name` | Name of the pipeline schema to use. | No | `null` | | `--user-secrets` | Array of user secrets to make available to the pipeline. | No | `null` | | `--workspace-secrets` | Array of workspace secrets to make available to the pipeline. | No | `null` | Run `tw runs relaunch -h` to view all the required and optional fields for relaunching a run in a workspace. #### Example Command: ```bash tw runs relaunch -i 6p7q8r9s0t1u2 ``` Example output: ```bash Workflow 8r9s0t1u2v3w4 submitted at [my-organization-updated / my-workspace] workspace. https://cloud.seqera.io/orgs/my-organization-updated/workspaces/my-workspace/watch/8r9s0t1u2v3w4/watch/8r9s0t1u2v3w4 ``` ## tw runs cancel Cancel a pipeline run. ```bash tw runs cancel [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Pipeline run identifier. The unique workflow ID to cancel. Running tasks will be terminated. | Yes | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | Run `tw runs cancel -h` to view all the required and optional fields for canceling a run in a workspace. #### Example Command: ```bash tw runs cancel -i 6p7q8r9s0t1u2 -w 123456789012345 ``` Example output: ```bash Pipeline run '6p7q8r9s0t1u2' canceled at [my-organization-updated / my-workspace] workspace ``` ## tw runs labels Manage pipeline run labels. ```bash tw runs labels [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `-id` | Pipeline run identifier. The unique workflow ID to manage labels for. Labels help organize and filter pipeline runs. | Yes | `null` | | `--no-create` | Assign labels without creating the ones which were not found. | No | `null` | | `--operations`, `-o` | Type of operation (set, append, delete) [default: set]. | No | `set` | #### Example Command: ```bash tw runs labels -i 6p7q8r9s0t1u2 newlabel ``` Example output: ```bash 'set' labels on 'run' with id '6p7q8r9s0t1u2' at 123456789012345 workspace ``` ## tw runs delete Delete a pipeline run. ```bash tw runs delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `-id` | Pipeline run identifier. The unique workflow ID to delete. Deletes the run record and associated metadata from Seqera Platform. | Yes | `null` | | `--force` | Force deletion of active workflows. By default, only completed workflows can be deleted. Use this flag to delete running or pending workflows. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | Run `tw runs delete -h` to view all the required and optional fields for deleting a run in a workspace. #### Example Command: ```bash tw runs delete -i 7q8r9s0t1u2v3 -w 123456789012345 ``` Example output: ```bash Pipeline run '7q8r9s0t1u2v3' deleted at [my-organization-updated / my-workspace] workspace ``` ## tw runs dump Dump all logs and details of a run into a compressed tarball file for troubleshooting. ```bash tw runs dump [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `-id` | Pipeline run identifier | Yes | `null` | | `-o`, `--output` | Output file path for the compressed archive. Supported formats: .tar.xz (smaller, slower) and .tar.gz (faster, larger). | Yes | `null` | | `--add-task-logs` | Include individual task log files (stdout, stderr, .command.log) in the archive. Useful for detailed task-level troubleshooting. | No | `null` | | `--add-fusion-logs` | Include Fusion file system logs for tasks. Only applicable when workflow uses Fusion for cloud storage access. | No | `null` | | `--only-failed` | Include only failed tasks in the dump. Reduces archive size by excluding successful task logs. | No | `null` | | `--silent` | Suppress download progress indicators. Useful for scripting or logging to files. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` | Run `tw runs dump -h` to view all the required and optional fields for dumping all logs and details of a run in a workspace. The supported formats are `.tar.xz` and `.tar.gz`. In the example below, we dump all the logs and details for the run with ID `5z4AMshti4g0GK` to the output file `file.tar.gz`. #### Example Command: ```bash tw runs dump -i 5z4AMshti4g0GK -o file.tar.gz - Tower info - Workflow details - Task details ``` Example output: ```bash Pipeline run '5z4AMshti4g0GK' at [seqeralabs / testing] workspace details dump at 'file.tar.gz' ``` --- ## tw secrets Run `tw secrets -h` to view supported workspace secret operations. [Secrets](https://docs.seqera.io/platform-cloud/secrets/overview) are used to store the keys and tokens used by workflow tasks to interact with external systems, such as a password to connect to an external database or an API token. ## tw secrets list List secrets. ```bash tw secrets list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw secrets list -w 123456789012345 ``` Example output: ```bash Secrets at [my-organization-updated / my-workspace] workspace: ID | Name | Last updated -----------------+----------------------+------------------------------- 333444555666777 | secret2 | Thu, 15 Jan 2026 13:33:55 GMT ``` ## tw secrets add Add a secret. ```bash tw secrets add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Secret name. Must be unique per workspace. Names consist of alphanumeric, hyphen, and underscore characters. | Yes | `null` | | `-v`, `--value` | Secret value, to be stored securely. The secret is made available to pipeline executions at runtime. | No | `null` | | `--overwrite` | Overwrite the secret if it already exists | No | `false` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | Run `tw secrets add -h` to view the required and optional fields for adding a secret. #### Example Command: ```bash tw secrets add -n secret2 -v secret-value -w 123456789012345 ``` Example output: ```bash New secret 'secret2' (333444555666777) added at [my-organization-updated / my-workspace] workspace ``` ## tw secrets view View secret details. ```bash tw secrets view [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Secret identifier | No | `null` | | `-n`, `--name` | Secret name | No | `null` | #### Example Command: ```bash tw secrets view -n secret2 -w 123456789012345 ``` Example output: ```bash Secret at [my-organization-updated / my-workspace] workspace: ---------+------------------------------- ID | 333444555666777 Name | secret2 Created | Thu, 15 Jan 2026 13:33:55 GMT Updated | Thu, 15 Jan 2026 13:33:55 GMT Used | ``` ## tw secrets update Update a secret. ```bash tw secrets update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-v`, `--value` | New secret value, to be stored securely. The secret is made available to pipeline executions at runtime. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Secret identifier | No | `null` | | `-n`, `--name` | Secret name | No | `null` | #### Example Command: ```bash tw secrets update -n secret2 -v new-value -w 123456789012345 ``` Example output: ```bash Secret 'secret2' updated at [my-organization-updated / my-workspace] workspace ``` ## tw secrets delete Delete a secret. ```bash tw secrets delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Secret identifier | No | `null` | | `-n`, `--name` | Secret name | No | `null` | #### Example Command: ```bash tw secrets delete -n secret2 -w 123456789012345 ``` Example output: ```bash Secret 'secret2' deleted at [my-organization-updated / my-workspace] workspace ``` --- ## tw studios Run `tw studios -h` to view the list of supported operations. Manage [Studio sessions](https://docs.seqera.io/platform-cloud/studios/overview) hosted in Seqera Platform. Studio sessions allow interactive analysis using Jupyter, RStudio, VS Code, and Xpra. Additional custom analysis environments can be defined as needed. :::note Most Studio operations require workspace `MAINTAIN` permissions. ::: ## tw studios view View studio details. ```bash tw studios view [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable). Studios are not available in personal workspaces. | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Studio session identifier | No | `null` | | `-n`, `--name` | Studio name | No | `null` | Run `tw studios view -h` to view the required and optional fields for viewing session details. #### Example Command: ```bash tw studios view -i 23ce7967 -w community/showcase ``` Example output: ```bash Studio at workspace '[community / showcase]' ---------------------+------------------------------------------------------------ SessionID | 23ce7967 Name | experiment-analysis-session Status | STARTING Status Last Update | Fri, 31 Jan 2025 19:35:07 GMT Studio URL | https://a23ce7967.connect.cloud.seqera.io Description | Created on | Fri, 31 Jan 2025 18:12:27 GMT Created by | rob-newman | rob.newman@seqera.io Template | public.cr.seqera.io/platform/data-studio-jupyter:4.1.5-0.7 Mounted Data | Compute environment | aws-datastudios-sandbox-ireland-16cpus Region | eu-west-1 GPU allocated | 0 CPU allocated | 2 Memory allocated | 8192 Build reports | NA ``` ## tw studios list List studios. ```bash tw studios list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-f`, `--filter` | Optional filter criteria, allowing free text search on name and templateUrl and keywords: `userName`, `computeEnvName` and `status`. Example keyword usage: -f status:RUNNING. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable). Studios are not available in personal workspaces. | No | `TOWER_WORKSPACE_ID` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display (default: ) | No | `null` | Run `tw studios list -h` to view the required and optional fields for listing studios. List all studios in a workspace. #### Example Command: ```bash tw studios list -w 123456789012345 ``` Example output: ```bash Checkpoints at Studio 9s0t1u2v at [organization2 / organization6] workspace: ID | Name | Author | Date Created | Date Saved ------+----------------------+------------+-------------------------------+------------------------------- 7889 | snakemake_1768412934 | user3-name | Wed, 14 Jan 2026 17:48:54 GMT | Thu, 15 Jan 2026 14:28:01 GMT 7838 | snakemake_1768226043 | user3-name | Mon, 12 Jan 2026 13:54:03 GMT | Mon, 12 Jan 2026 14:22:31 GMT ``` ## tw studios templates List available Studio templates. ```bash tw studios templates [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `--max` | Maximum number of templates to return. | No | `20` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable). Studios are not available in personal workspaces. | No | `TOWER_WORKSPACE_ID` | #### Example Command: ```bash tw studios templates -w 123456789012345 ``` Example output: ```bash Available templates for Studios: Templates -------------------------------------------------------------- public.cr.seqera.io/platform/data-studio-jupyter:4.2.5-0.8 public.cr.seqera.io/platform/data-studio-jupyter:4.2.5-0.9 public.cr.seqera.io/platform/data-studio-ride:2025.04.1-0.8 public.cr.seqera.io/platform/data-studio-ride:2025.04.1-0.9 ``` ## tw studios start Start a studio. ```bash tw studios start [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `--wait` | Wait until given status or fail. Valid options: STARTING, RUNNING, STOPPED, STOPPING. | No | `null` | | `--labels` | Comma-separated list of labels | No | `null` | | `--description` | Optional configuration override for 'description'. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable). Studios are not available in personal workspaces. | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Studio session identifier | No | `null` | | `-n`, `--name` | Studio name | No | `null` | | `--gpu` | Optional configuration override for 'gpu' setting (integer representing number of cores). | No | `null` | | `--cpu` | Optional configuration override for 'cpu' setting (integer representing number of cores). | No | `null` | | `--memory` | Optional configuration override for 'memory' setting (integer representing memory in MBs). | No | `null` | | `--lifespan` | Optional configuration override for 'lifespan' setting (integer representing hours). Defaults to workspace lifespan setting. | No | `null` | ## tw studios add Add a studio. ```bash tw studios add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Studio name. | Yes | `null` | | `-d`, `--description` | Studio description | No | `null` | | `--conda-env-yml`, `--conda-env-yaml` | Path to a YAML env file with Conda packages to be installed in the studio environment | No | `null` | | `-c`, `--compute-env` | Compute environment name | Yes | `null` | | `-a`, `--auto-start` | Create studio and start it immediately (default: false) | No | `false` | | `--private` | Create a private studio that only you can access or manage (default: false) | No | `false` | | `--labels` | Comma-separated list of labels | No | `null` | | `--wait` | Wait until Studio is in RUNNING status. Valid options: STARTING, RUNNING, STOPPED, STOPPING. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable). Studios are not available in personal workspaces. | No | `TOWER_WORKSPACE_ID` | | `-t`, `--template` | Container image template to be used for Studio. Available templates can be listed with 'studios templates' command. | No | `null` | | `-ct`, `--custom-template` | Custom container image template to be used for Studio. | No | `null` | | `--gpu` | Optional configuration override for 'gpu' setting (integer representing number of cores). | No | `null` | | `--cpu` | Optional configuration override for 'cpu' setting (integer representing number of cores). | No | `null` | | `--memory` | Optional configuration override for 'memory' setting (integer representing memory in MBs). | No | `null` | | `--lifespan` | Optional configuration override for 'lifespan' setting (integer representing hours). Defaults to workspace lifespan setting. | No | `null` | Run `tw studios add -h` to view the required and optional fields for adding sessions. Add a new Studio session in a workspace. #### Example Command: ```bash tw studios add -n new-analysis -w community/showcase \ --description="New Python analysis for RNA experiment ABC" \ --template="public.cr.seqera.io/platform/data-studio-jupyter:4.1.5-0.7" \ --compute-env=48bB2PDk83AxskE40lealy \ --cpu=2 \ --memory=8192 ``` Example output: ```bash Studio 2aa60bb7 CREATED at [community / showcase] workspace. ``` ## tw studios checkpoints List studio checkpoints. ```bash tw studios checkpoints [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-f`, `--filter` | Optional filter criteria, allowing free text search on name and keywords: `after: YYYY-MM-DD`, `before: YYYY-MM-DD` and `author`. Example keyword usage: -f author:my-name. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable). Studios are not available in personal workspaces. | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Studio session identifier | No | `null` | | `-n`, `--name` | Studio name | No | `null` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display (default: ) | No | `null` | Run `tw studios checkpoints -h` to view the required and optional fields for viewing checkpoints for a session. List all checkpoints for an existing Studio session in a workspace. See [Session checkpoints](https://docs.seqera.io/platform-cloud/studios/managing#studio-session-checkpoints) for more information. #### Example Command: ```bash tw studios checkpoints -i 9s0t1u2v -w 123456789012345 ``` Example output: ```bash Checkpoints for studio '9s0t1u2v' at [my-organization / my-workspace] workspace: ID | Name | Created ---------------+---------------------+------------------------------- 1a2b3c4d5e | checkpoint-001 | Mon, 15 Jan 2024 10:30:00 GMT 2b3c4d5e6f | checkpoint-002 | Mon, 15 Jan 2024 14:45:00 GMT ``` ## tw studios add-as-new Add a new Studio session from an existing parent session and checkpoint. Useful for experimentation without impacting the parent session state. ```bash tw studios add-as-new [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `--parent-checkpoint-id` | Parent Studio checkpoint id, to be used as the starting point for the new Studio session. If not provided, it defaults to the most recent existing checkpoint of the parent Studio session. | No | `null` | | `-n`, `--name` | Studio name. | Yes | `null` | | `-d`, `--description` | Studio description | No | `null` | | `-a`, `--auto-start` | Create studio and start it immediately (default: false) | No | `false` | | `--private` | Create a private studio that only you can access or manage (default: false) | No | `false` | | `--labels` | Comma-separated list of labels | No | `null` | | `--wait` | Wait until Studio is in RUNNING status. Valid options: STARTING, RUNNING, STOPPED, STOPPING. | No | `null` | | `-pid`, `--parent-id` | Parent studio session identifier | No | `null` | | `-pn`, `--parent-name` | Parent studio name | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable). Studios are not available in personal workspaces. | No | `TOWER_WORKSPACE_ID` | | `--gpu` | Optional configuration override for 'gpu' setting (integer representing number of cores). | No | `null` | | `--cpu` | Optional configuration override for 'cpu' setting (integer representing number of cores). | No | `null` | | `--memory` | Optional configuration override for 'memory' setting (integer representing memory in MBs). | No | `null` | | `--lifespan` | Optional configuration override for 'lifespan' setting (integer representing hours). Defaults to workspace lifespan setting. | No | `null` | Run `tw studios add-as-new -h` to view the required and optional fields for adding a new studio session from an existing one. #### Example Command: ```bash tw studios add-as-new -pid 0t1u2v3w -n cloned-studio-example -w 123456789012345 ``` Example output: ```bash Studio 1u2v3w4x CREATED at [my-organization / my-workspace] workspace. ``` ## tw studios stop Stop a studio. ```bash tw studios stop [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `--wait` | Wait until given status or fail. Valid options: STARTING, RUNNING, STOPPED, STOPPING. | No | `null` | | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable). Studios are not available in personal workspaces. | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Studio session identifier | No | `null` | | `-n`, `--name` | Studio name | No | `null` | Run `tw studios stop -h` to view the required and optional fields for adding sessions. Stop an existing Studio session in a workspace. #### Example Command: ```bash tw studios stop -i 13083356 -w community/showcase ``` Example output: ```bash Studio 13083356 STOP successfully submitted at [community / showcase] workspace. ``` ## tw studios delete Delete an existing Studio session from a workspace. ```bash tw studios delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable). Studios are not available in personal workspaces. | No | `TOWER_WORKSPACE_ID` | | `-i`, `--id` | Studio session identifier | No | `null` | | `-n`, `--name` | Studio name | No | `null` | Run `tw studios delete -h` to view the required and optional fields for listing sessions. #### Example Command: ```bash tw studios delete -i 2aa60bb7 ``` Example output: ```bash Studio 2aa60bb7 deleted at [community / showcase] workspace. ``` --- ## tw teams Run `tw teams -h` to view supported team operations. Manage [organization teams](https://docs.seqera.io/platform-cloud/orgs-and-teams/organizations#teams). :::note Team management operations require organization `OWNER` permissions. ::: ## tw teams list List organization teams. ```bash tw teams list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-o`, `--organization` | Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'. | Yes | `null` | | `--page` | Page number for paginated results (default: 1) | No | `null` | | `--offset` | Row offset for paginated results (default: 0) | No | `null` | | `--max` | Maximum number of records to display (default: ) | No | `null` | Run `tw teams list -h` to view the required and optional fields for listing teams. #### Example Command: ```bash tw teams list -o TestOrg2 ``` Example output: ```bash Teams for TestOrg2 organization: Team ID | Team Name | Members Count Name ----------------+-----------+-------------------- 84866234211969 | Testing | 1 ``` ## tw teams add Add a team. ```bash tw teams add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-n`, `--name` | Team name. The unique identifier for the team within the organization. Used to reference the team in commands and workspace permissions. | Yes | `null` | | `-o`, `--organization` | Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'. | Yes | `null` | | `-d`, `--description` | Team description. Free-text description providing context about the team's purpose, members, or project scope. | No | `null` | | `--overwrite` | Overwrite existing team. If a team with this name already exists in the organization, delete it first before creating the new one. Use with caution as this removes all team members and permissions. | No | `false` | Run `tw teams add -h` to view the required and optional fields for creating a team. #### Example Command: ```bash tw teams add -n team1 -o TestOrg2 -d testing ``` Example output: ```bash A 'team1' team added for 'TestOrg2' organization ``` ## tw teams delete Delete a team. ```bash tw teams delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Team numeric identifier. The unique ID assigned when the team was created. Find team IDs using 'tw teams list'. | Yes | `null` | | `-o`, `--organization` | Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'. | Yes | `null` | #### Example Command: ```bash tw teams delete -i 169283393825479 -o TestOrg2 ``` Example output: ```bash Team '169283393825479' deleted for TestOrg2 organization ``` ## tw teams members List team members. ```bash tw teams members [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-t`, `--team` | Team name. The unique team identifier within the organization. Lists all members who belong to this team. | Yes | `null` | | `-o`, `--organization` | Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'. | Yes | `null` | #### Example Command: ```bash tw teams members -t Team1 -o my-organization-updated ``` Example output: ```bash Members for team 'Team1': Member ID | Username | Email | Role -----------------+-------------------+-----------------------------+-------- 987654321098765 | user1-name | user1@example.com | member 987654321098766 | user2-name | user2@example.com | member ``` ### tw teams members add Add a team member. ```bash tw teams members add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-m`, `--member` | Member username or email address. The user must already be a member of the organization before being added to the team. Use either their platform username or email address. | Yes | `null` | | `-t`, `--team` | Team name or identifier to add the member to. | Yes | `null` | | `-o`, `--organization` | Organization name or identifier where the team exists. | Yes | `null` | #### Example Command: ```bash tw teams members add -m user1@example.com -t my-team -o my-organization ``` Example output: ```bash Member 'user1@example.com' added to team 'my-team' in organization 'my-organization' ``` ### tw teams members delete Remove a team member. ```bash tw teams members delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-m`, `--member` | Member username to remove from team. Removes the user from this team but does not remove them from the organization. They will lose access to workspaces shared with this team. | Yes | `null` | | `-t`, `--team` | Team name or identifier to remove the member from. | Yes | `null` | | `-o`, `--organization` | Organization name or identifier where the team exists. | Yes | `null` | #### Example Command: ```bash tw teams members delete -m user1@example.com -t my-team -o my-organization ``` Example output: ```bash Member 'user1@example.com' removed from team 'my-team' in organization 'my-organization' ``` --- ## tw workspaces Run `tw workspaces -h` to view supported workspace operations. [Workspaces](https://docs.seqera.io/platform-cloud/orgs-and-teams/workspace-management) provide the context in which a user launches workflow executions, defines the available resources, and manages who can access those resources. Workspaces contain pipelines, runs, actions, datasets, compute environments, credentials, and secrets. Access permissions are controlled with participants, collaborators, and teams. ## tw workspaces list List workspaces. ```bash tw workspaces list [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-o`, `--org`, `--organization` | Workspace organization name | No | `null` | List all the workspaces in which you are a participant. #### Example Command: ```bash tw workspaces list ``` Example output: ```bash Workspaces for default user: Workspace ID | Workspace Name | Organization Name | Organization ID -----------------+------------------+-------------------+----------------- 26002603030407 | shared-workspace | my-tower-org | 04303000612070 ``` ## tw workspaces add Add a workspace. ```bash tw workspaces add [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-o`, `--org`, `--organization` | Workspace organization name | Yes | `null` | | `-n`, `--name` | Unique workspace name within the organization. Must be 2-40 characters, start and end with alphanumeric characters, and can contain hyphens or underscores between characters. | Yes | `null` | | `-f`, `--full-name` | Full display name for the workspace. Maximum 100 characters. | Yes | `null` | | `-d`, `--description` | Optional description of the workspace. Maximum 1000 characters. | No | `null` | | `-v`, `--visibility` | Workspace visibility setting. Accepts `PRIVATE` (only participants can access) or `SHARED` (all organization members can view). | No | `null` | | `--overwrite` | Overwrite the workspace if it already exists | No | `false` | :::note Workspace management operations require organization `OWNER` permissions. ::: Run `tw workspaces add -h` to view the required and optional fields for adding your workspace. In the example below, we create a shared workspace to be used for sharing pipelines with other private workspaces. See [Shared workspaces](https://docs.seqera.io/platform-cloud/orgs-and-teams/workspace-management) for more information. #### Example Command: ```bash tw workspaces add --name=shared-workspace --full-name=shared-workspace-for-all --org=my-tower-org --visibility=SHARED ``` Example output: ```bash A 'SHARED' workspace 'shared-workspace' added for 'my-tower-org' organization ``` :::note By default, a workspace is set to private when created. ::: ## tw workspaces view View workspace details. ```bash tw workspaces view [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Workspace identifier | No | `null` | | `-n`, `--name` | Workspace namespace in OrganizationName/WorkspaceName format | No | `null` | #### Example Command: ```bash tw workspaces view -i 123456789012345 ``` Example output: ```bash Details for workspace 'Workspace one' --------------+------------------------------------------------ ID | 123456789012345 Name | my-workspace Full Name | Workspace one Description | Workspace created with seqerakit CLI scripting Visibility | SHARED ``` ## tw workspaces update Update a workspace. ```bash tw workspaces update [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-i`, `--id` | Workspace identifier | Yes | `null` | | `--new-name` | Updated workspace name. Must be unique per workspace. Names consist of alphanumeric, hyphen, and underscore characters. Must be 2-40 characters. | No | `null` | | `-f`, `--fullName` | Updated full display name for the workspace. Maximum 100 characters. | No | `null` | | `-d`, `--description` | Updated workspace description. Maximum 1000 characters. | No | `null` | #### Example Command: ```bash tw workspaces update -i 123456789012345 --new-name my-workspace-updated ``` Example output: ```bash A 'SHARED' workspace 'my-workspace' updated for 'my-organization-updated' organization ``` ## tw workspaces delete Delete a workspace. ```bash tw workspaces delete [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-i`, `--id` | Workspace identifier | No | `null` | | `-n`, `--name` | Workspace namespace in OrganizationName/WorkspaceName format | No | `null` | #### Example Command: ```bash tw workspaces delete -i 222333444555667 ``` Example output: ```bash Workspace 'test-workspace' deleted for organization5 organization ``` ## tw workspaces leave Leave a workspace. ```bash tw workspaces leave [OPTIONS] ``` #### Options | Option | Description | Required | Default | |--------|-------------|----------|----------| | `-i`, `--id` | Workspace identifier | No | `null` | | `-n`, `--name` | Workspace namespace in OrganizationName/WorkspaceName format | No | `null` | #### Example Command: ```bash tw workspaces leave -i 222333444555668 ``` Example output: ```bash You have been removed as a participant from 'new-workspace' workspace ``` # MultiQC > Documentation for MultiQC This file contains all documentation content in a single document following the llmstxt.org standard. ## AI summaries MultiQC v1.27 and newer can generate AI-powered summaries of your reports. These can be created at two points: - When creating the report, baked into the report HTML. - Dynamically in the browser, while viewing an existing HTML report. The AI summaries are generated using LLMs (large-language models) AI, with the following supported providers: - [Seqera Co-Scientist](https://ai.seqera.io/) - [OpenAI](https://openai.com/) - [Anthropic](https://www.anthropic.com/) - [AWS Bedrock](https://aws.amazon.com/bedrock/) - MultiQC reports also have an option to copy a prompt to your clipboard, to paste into any provider you have access to :::warning Never rely on AI-generated summaries. Whilst these summaries can be useful to get you started quickly with a report, they may give inaccurate analysis and miss important details. ::: AI summaries work by sending report data to an LLM provider of your choice, via an API over the internet. Be aware of what data you are sending, and to who. For more information, see [Seqera AI: Your privacy matters](https://seqera.io/ai-trust/). ## Choosing a provider To use native summary generation, MultiQC needs to communicate with an LLM provider's API. All three supported services require an API key to work. Remember: Treat your API keys like passwords and do not share them. - [Seqera Co-Scientist](https://ai.seqera.io/) - Register for free at [seqera.io](https://seqera.io/) - Create a new key on the **Access tokens** page: [https://cloud.seqera.io/tokens](https://cloud.seqera.io/tokens) - [OpenAI](https://openai.com/) - Register at [platform.openai.com](https://platform.openai.com/signup) (NB: different to ChatGPT) - Add a payment method to your account to enable API usage beyond any trial credits - Create a new secret key on the _API Keys_ section [under your profile](https://platform.openai.com/api-keys) - [Anthropic](https://www.anthropic.com/) - Sign up at [https://console.anthropic.com](https://console.anthropic.com) - Add a payment method to enable API access - Create a new key on on the _API Keys_ section in your [account settings](https://console.anthropic.com/settings/keys) - [AWS Bedrock](https://aws.amazon.com/bedrock/) - Bedrock supports a plethora of models across many providers - Sign up, access credentials and payment are handled via an AWS account - Other providers, via custom endpoint - Works for providers supporting OpenAI-compatible API, specify a custom endpoint URL. See [Using custom OpenAI-compatible endpoints](#using-custom-openai-compatible-endpoints) for details - Other providers, via your clipboard - You can use buttons in MultiQC reports to copy a prompt to your clipboard, in order to manually summarise report data. See [Copying prompts](#copying-prompts) for instructions. Seqera Co-Scientist is free to use.[^seqera-ai-usage-limits] Use of other third-party APIs are billed by their respective providers based on consumption. Seqera Co-Scientist uses the latest AI provider models under the hood. ### Choosing a model If you're using OpenAI, Anthropic or AWS Bedrock you can choose the exact model used for report summaries. This is done by setting `ai_model` in the MultiQC config. - Anthropic model names must begin with `claude` - Default: `claude-sonnet-4-5`. - See the [Anthropic docs](https://docs.anthropic.com/en/docs/intro-to-claude#model-options). - OpenAI model names must being with `gpt` - Default: `gpt-4o`. - See the [OpenAI docs](https://platform.openai.com/docs/models). - Bedrock model names must be valid inputs to the `modelId` parameter of the `InvokeModel` API ([docs](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html#API_runtime_InvokeModel_RequestSyntax)). This model is used during report generation and also set as the default toolbox panel setting for browser report summaries. ## Reasoning Models MultiQC supports reasoning models from multiple providers which provide enhanced reasoning capabilities for complex bioinformatics analysis interpretation. These models "think" before responding, using internal reasoning to provide more accurate and thorough analysis. ### Supported Reasoning Models - OpenAI: `o1`, `o3`, `o3-mini`, `o4-mini` - Anthropic Claude 4 series: `claude-sonnet-4-5` ### Configuration Simply set your AI model to a reasoning model: ```yaml # multiqc_config.yaml ai_summary: true ai_provider: openai # or Anthropic for Claude 4 ai_model: o3-mini # or claude-sonnet-4-5, o4-mini, etc. ``` Reasoning models support additional configuration parameters: **OpenAI reasoning models:** ```yaml # multiqc_config.yaml ai_summary: true ai_provider: openai ai_model: o3-mini ai_reasoning_effort: high # low, medium, or high ai_max_completion_tokens: 8000 # adjust based on needs ``` **Anthropic Claude 4 extended thinking:** ```yaml # multiqc_config.yaml ai_summary: true ai_provider: anthropic ai_model: claude-sonnet-4-5 ai_extended_thinking: true # enable extended thinking ai_thinking_budget_tokens: 15000 # budget for extended thinking ``` ### Configuration Options **OpenAI reasoning models:** - **`ai_reasoning_effort`**: Controls how much time the model spends reasoning - `low`: Faster responses, less thorough reasoning - `medium`: Balanced speed and reasoning depth (default) - `high`: Slower but most thorough reasoning - **`ai_max_completion_tokens`**: Maximum tokens for model output (default: 4000) - Higher values allow longer, more detailed summaries **Anthropic extended thinking:** - **`ai_extended_thinking`**: Enable extended thinking for Claude 4 models (default: false) - Must be set to `true` to enable extended thinking capabilities - When disabled, Claude 4 models run as regular models without extended thinking - **`ai_thinking_budget_tokens`**: Maximum tokens for internal reasoning process (default: 10000) - Only applies when `ai_extended_thinking` is enabled - Controls how much "thinking" the model can do before responding - Higher budgets enable more thorough analysis for complex problems - The model may not use the entire budget allocated ### Key Differences from Regular Models 1. **Internal Reasoning**: Reasoning models "think" before responding, using hidden reasoning tokens 2. **Enhanced Accuracy**: Better performance on complex analytical tasks 3. **Different Parameters**: Use `max_completion_tokens` and `reasoning_effort` 4. **Developer Messages**: Use developer messages instead of system messages for better performance ### Usage Examples **Basic Configuration for o1-mini:** ```yaml ai_summary: true ai_provider: openai ai_model: o1-mini ``` **High-Quality Analysis with o3:** ```yaml ai_summary: true ai_summary_full: true ai_provider: openai ai_model: o3 ai_reasoning_effort: high ai_max_completion_tokens: 6000 ``` **Cost-Optimized Setup with o4-mini:** ```yaml ai_summary: true ai_provider: openai ai_model: o4-mini ai_reasoning_effort: low ai_max_completion_tokens: 3000 ``` **Anthropic Claude 4 Extended Thinking:** ```yaml ai_summary: true ai_provider: anthropic ai_model: claude-sonnet-4-5 ai_extended_thinking: true # enable extended thinking ai_thinking_budget_tokens: 12000 # budget for thinking process ``` ### Model Recommendations - **`o4-mini`**: Most cost-effective, good for routine analysis - **`o3-mini`**: Balanced performance and cost - **`o3`**: Best reasoning capabilities for complex reports - **`o1-mini`**: Good for coding-heavy bioinformatics analysis ### Notes - **Performance**: Both OpenAI reasoning models and Anthropic extended thinking may take longer to respond due to internal reasoning - **Billing**: Reasoning/thinking tokens are charged but internal reasoning is not visible in the output - **Context windows**: o1 series (128k), o3/o4 series (200k), Claude 4 series (200k+) - **OpenAI reasoning models**: Don't support parameters like `temperature`, use `reasoning_effort` and `max_completion_tokens` - **Anthropic extended thinking**: Uses standard Anthropic API with `thinking.budget_tokens` parameter, supports regular parameters like `temperature` - **Different approaches**: OpenAI uses specialized reasoning models, while Anthropic adds extended thinking capabilities to their regular models ## Summaries during report generation MultiQC can generate AI summaries at run time, when generating reports. Summary text is included within the report HTML as static text and will be visible to anyone viewing the report, even when shared. ### MultiQC configuration AI summaries are disabled by default when running MultiQC. To generate them, you must enable them either on the command line or via a MultiQC config file. - Command line flags: - `--ai` / `--ai-summary`: Generate a short report summary and put it on top of the report (fast) - `--ai-summary-full`: Generate a detailed version of the summary with analysis and recommendations (slower) - `--ai-provider `: Choose AI provider. One of `seqera`, `openai`, `anthropic` or `aws_bedrock`. Default `seqera` - `--no-ai`: Disable AI toolbox and buttons in the report - Alternatively, MultiQC configuration file: ```yaml ai_summary: false # Set to true for short summaries ai_summary_full: false # Set to true for long summaries ai_provider: "seqera" # 'seqera', 'openai', 'anthropic' or 'aws_bedrock'. Default: 'seqera' no_ai: false # Set to true to disable AI toolbox and buttons in the report ``` ### Environment variables You must also set your provider's API key in an environment variable in order to access its service _(see [Choosing a provider](#choosing-a-provider) for how to get an API key)_. API keys are supplied by setting the following environment variables in your shell: ```bash export SEQERA_ACCESS_TOKEN="..." # or TOWER_ACCESS_TOKEN export OPENAI_API_KEY="..." export ANTHROPIC_API_KEY="..." ``` It's possible to save these in an `.env` file instead of exporting to your shell's environment. This `.env` file can either be in the current working directory or the MultiQC source code directory. MultiQC uses the [python-dotenv](https://saurabh-kumar.com/python-dotenv/) package. For AWS Bedrock, the client uses the [default `boto3` credential chain](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html). If you run MultiQC without the appropriate key you will get a warning printed to the console, but report generation will otherwise proceed without the summary. MultiQC will not return an error exit code. :::tip MultiQC configuration options can also be set using environment variables (see [Config with environment variables](../getting_started/config.md#config-with-environment-variables)), so you can set up everything, including the command line flags / config this way: ```bash export MULTIQC_AI_SUMMARY=1 export SEQERA_ACCESS_TOKEN="..." ``` ::: Environment variables will only be used for `--ai-summary`/`--ai-summary-full` generation. They are not saved by MultiQC and cannot be used for in-browser summary generation, within reports. ## In-browser AI summaries In addition to summaries during report generation, MultiQC can also create summaries dynamically in reports. This can be useful as the person viewing a report is often different than the person who generated it. Summaries can be generated on demand when needed. The AI toolbox and **Summarize** buttons are shown by default in all reports. To prevent this, run MultiQC with the `--no-ai` flag. This can also be done on a per-user basis by selecting **Remove AI buttons** in the **AI Provider** dropdown in the AI toolbox. Summaries generated in reports are _ephemeral_ and are not saved in the HTML. If you generate a summary and share the report then others will not see it. MultiQC tries to save the summary response within your browser's [local storage](https://www.w3schools.com/html/html5_webstorage.asp) so that it shows the next time you open the same report, but this process is imperfect and might not always work. ### Configuring the AI provider ![Configure AI providers within a MultiQC report](../../../docs/images/ai_toolbox_icon.png) When you first try to generate a summary in the browser, you must supply the LLM provider's API key. Open the AI settings by clicking the icon in the toolbox: Then, choose an AI provider and enter the relevant API key _(see [Choosing a provider](#choosing-a-provider) for how to get an API key)_. :::info[Important] API keys are stored _only_ in your browser's [local storage](https://www.w3schools.com/html/html5_webstorage.asp) and are not shared if you send the HTML report to someone else. They are used to send report data directly to your AI provider of choice. ::: ![Enter a provider API key in the report toolbox](../../../docs/images/ai_toolbox_keys.png) ### Summarising the report Once your provider API key is configured, click **Summarize report** to generate an overview summary of the entire report. ![Button to summarize a MultiQC report](../../../docs/images/ai_summarize_button.png) The summary text is interactive: click an underlined sample name to highlight that sample throughout the report: ![Click underlined sample names in the summary to highlight them in the report](../../../docs/images/ai_highlight_samples.gif) ### Section-level summaries Besides a global report-level AI summary, you can generate a summary for each plot or table separately using buttons next to each section: ![Summarize with AI buttons in a report](../../../docs/images/ai_summarize_buttons.png) ### Copying prompts If you have access to an LLM that is not directly supported by MultiQC, you can copy the exact prompt that MultiQC uses to your clipboard. This can be pasted into whatever LLM that you have access to. To do this, select **Copy prompts** as the LLM provider in the report toolbox AI tab. The **Summarize** buttons will then change to **Copy prompt** buttons and instead of injecting summaries into the report HTML, will copy the LLM prompt to your clipboard. ### Remove AI buttons If you're suffering from AI-overload and don't want to see the AI summary features in your reports, you can disable them by selecting **Remove AI buttons** in the toolbox as an AI provider. This will remove all **Summarize** buttons from the report. This is done at user level and will be stored in the browser's local storage and applied to all MultiQC reports that you open. You can also use `--no-ai` when generating reports, which removes this functionality from the HTML for all users. ## Using `llms-full.txt` MultiQC always saves the full prompt and response to `multiqc_data/llms-full.txt` file, regardless of whether the summary was generated during report generation or in the browser. This file can be used to debug or further analyse the AI summary generation process. It can be used to directly copy the prompt into your clipboard and use it with external services, e.g. ones with a larger context window. ## Continue chat If using Seqera AI as a provider, you can click the **Chat with Seqera AI** button to open the Seqera AI chat interface in a new tab in order to ask further questions. This button is shown alongside the report-level summary after it's generated. ![Chat with Seqera AI button location](../../../docs/images/ai_chat_with_seqera_ai_button.png) If you are logged in to [seqera.io](https://seqera.io) with the same user that generated the report summary, the chat history with the report prompt and AI summary response will be loaded allowing you to continue straight on with more in-depth questions. ![Seqera AI with MultiQC report history](../../../docs/images/ai_continue_chat.png) ## Context window A context window refers to the amount of text (in tokens) that an AI model can consider at once when processing input and generating responses, encompassing both the input prompt and the output. At the time of writing, modern LLMs typically have a context window size in 128-200k tokens, which translates to about 100-160k characters of report data. That means that very large reports, of thousands of samples, might not fit in the available LLM context window. MultiQC uses the following logic, moving on to the next step if the prompt is still too large: 1. Attempt to include all report data in the prompt. 2. Include just the general statistics table. 3. Include the general statistics table, without hidden-by-default columns. 4. Abort AI summary. If you're unable to generate an AI summary, you can try the following: - Hide additional columns in the general statistics table (see [Hiding Columns](../reports/customisation.md#hiding-columns)). - Hide General statistics data in the browser, and request the AI summary dynamically: - Hide columns with the **Configure columns** button - Filter shown samples dynamically with the toolbox - Copy the prompt from `multiqc_data/llms-full.txt` into clipboard with the **Copy prompt** button in the toolbox, and use it with external services with a larger context window. ## Using custom OpenAI-compatible endpoints In addition to the built-in providers, MultiQC supports using custom OpenAI-compatible endpoints. This allows you to use self-hosted models or alternative providers that implement the OpenAI API specification. To use a custom endpoint: 1. Select "Custom" as the AI provider in the toolbox 2. Enter the endpoint URL (e.g., `http://localhost:8000/v1/chat/completions`) 3. Specify the model name to use with this endpoint 4. Provide an API key (if required by the endpoint) 5. Optionally specify a custom context window size if different from the default 128k tokens You can configure this in the MultiQC config: ```yaml ai_provider: custom ai_model: your-model-name ai_custom_endpoint: http://localhost:8000/v1/chat/completions ai_custom_context_window: 32000 # Optional ``` Make sure to set the `OPENAI_API_KEY` environment variable to use with the custom endpoint: ```bash export OPENAI_API_KEY=your-api-key ``` You can also customize the query payload sent to the endpoint by setting `ai_extra_query_options` in your config: ```yaml ai_extra_query_options: temperature: 0.7 top_p: 0.9 # Any other parameters supported by your endpoint ``` In browser, you can also select "Custom" provider from the toolbox, and enter the endpoint URL, model name, API key, and optional extra query options manually. ## Configuring within Nextflow If you're running MultiQC within a Nextflow pipeline, you probably don't want to edit the workflow code to configure AI summaries. Most nf-core pipelines with MultiQC have a `--multiqc_config` option to provide an additional YAML config for MultiQC. However, because API keys must be passed using environment variables, the recommended method is to use environment vars for everything. Using this approach means that no pipeline code needs adjustment, only a small addition to the Nextflow config. For example, to use with OpenAI you would set the following in your Nextflow config: ```groovy env { MULTIQC_AI_SUMMARY_FULL = 1 // Enable long summaries during report generation MULTIQC_AI_PROVIDER = "openai" // Select OpenAI as provider } process.withName: MULTIQC { secret = [ 'OPEN_API_KEY' ] // Access key for OpenAI } ``` In this example, [Nextflow Secrets](https://nextflow.io/docs/latest/secrets.html) are used to securely manage your API keys outside of your config file. To add this Nextflow secret you would run the following command in the terminal: ```bash $ nextflow secrets set OPENAI_API_KEY "xxxx" ``` Note that secrets can behave differently across different compute environment types. See the [Nextflow docs](https://www.nextflow.io/docs/latest/secrets.html#process-directive) for details. :::tip Save this Nextflow config to `~/.nextflow/config` and it [will be applied](https://nextflow.io/docs/edge/config.html#configuration-file) to every Nextflow pipeline you launch. ::: ## Security considerations MultiQC AI summaries are used at your own risk. Treat results with appropriate mistrust and consider what data you are sending to external services. - API keys set in environment variables are not saved in report outputs - API keys put in the toolbox are stored only in your browser's local storage - No report data or keys are sent to any servers except the chosen AI provider Seqera AI does not use inputs for subsequent fine-tuning or direct model improvement. You can find our more information about Seqera's pledge for privacy at [https://seqera.io/ai-trust/](https://seqera.io/ai-trust/) ### Sample anonymization MultiQC provides an option to anonymize sample names when generating AI summaries, both during report generation and in the browser. This helps protect sensitive information when sharing summaries with AI providers. To enable sample anonymization: - For in-browser summaries: Toggle "Anonymize samples" in the AI toolbox section - For report generation: Set `anonymize_samples: true` in your MultiQC config When enabled, sample names are replaced with generic pseudonyms (e.g., "SAMPLE_1", "SAMPLE_2") before being sent to the AI provider. The anonymization is applied consistently across the entire report - each sample name gets the same pseudonym wherever it appears. When the AI response references samples, the pseudonyms are automatically converted back to the original sample names before displaying. MultiQC replaces sample names that appear as typical keys in plots and tables, specifically: - First column of a table table (e.g. the General statistics table) - Labels of bars in bar plots - Line names in line plots - Data point labels in scatter plots - Heatmap axis labels - Violin plot data point names But note that if a module creates some custom plot configuration where sample names are used elsewhere, anonymization would not be guaranteed. :::info Note that with the "Continue chat" button you would see the anonymized samples, which makes it less useful. ::: [^seqera-ai-usage-limits]: Seqera Cloud Basic is free for small teams. It includes access to Seqera Co-Scientist, with a usage cap of 100 messages per calendar month. Researchers at qualifying academic institutions can apply for free access to Seqera Cloud Pro. See [Seqera Pricing](https://seqera.io/pricing/) for more details --- ## MultiQC Configuration Reference This document describes all configuration options available in MultiQC. ## Introduction MultiQC configuration can be set in several ways: 1. **Command line parameters** - Command line flags are available for many options (run `multiqc --help` to see all available options) 2. **Configuration files** - MultiQC looks for configuration files in the following locations (in order of precedence): - `/multiqc_config.yaml` - `~/.multiqc_config.yaml` - `/multiqc/utils/config_defaults.yaml` 3. **Environment variables** - MultiQC checks for environment variables that match configuration options prefixed with `MULTIQC_`, for example: `MULTIQC_TITLE="My Report"` Configuration values are loaded in the following order of precedence (highest to lowest): 1. Command line parameters 2. Current working directory config file 3. User home directory config file 4. Environment variables 5. Default configuration values The options below can be specified in your YAML configuration files. For boolean options, use `true` or `false` (all lowercase) in your YAML files. :::tip If you'd rather build your config visually, the [Config Wizard](https://seqera.io/multiqc_config_wizard) renders every option below as a form field with the same descriptions and defaults, and validates as you type. ::: ## Report Meta ### Header text #### `title` **Type**: str Title shown at the top of the report and used in the page title. #### `subtitle` **Type**: str Subtitle shown under the report title. Plain text only. #### `intro_text` **Type**: str Paragraph shown under the title. Useful for adding context about the analysis. #### `report_comment` **Type**: str Free-text comment shown at the top of the report. HTML is allowed. **Example**: ```yaml report_comment: This report was generated from the RNA-seq pipeline on 2024-08-21. ``` #### `report_header_info` **Type**: List[Dict[str, str]] Extra key/value pairs shown in the report header, eg. contact name, run ID, pipeline version. Each list item is a single-key dictionary. **Example**: ```yaml report_header_info: - Contact E-mail: phil.ewels@seqera.io - Application Type: RNA-seq - Project Type: Application - Sequencing Platform: HiSeq 2500 High Output V4 ``` ### Report generation info #### `show_analysis_paths` **Type**: bool (default: `true`) Show the absolute paths of analysed directories in the report header. #### `show_analysis_time` **Type**: bool (default: `true`) Show the date and time the report was generated in the header. ## Report Appearance ### Template #### `template` **Type**: str (default: `"default"`) Name of the report template. Built-in templates: default, original, simple, sections, gathered, geo, disco. Plugin packages can register additional templates via the `multiqc.templates.v1` entry point. **Example**: ```yaml template: default ``` #### `template_dark_mode` **Type**: bool (default: `true`) Enable the dark mode toggle in the report template. #### `simple_output` **Type**: bool (default: `false`) Render a minimal HTML report without the toolbox or interactive widgets. Useful for very large reports. ### Logo #### `custom_logo` **Type**: str Path to an image to show at the top of the report, replacing the MultiQC logo. **Examples**: ```yaml custom_logo: /path/to/logo.png ``` ```yaml custom_logo: ./assets/logo.svg ``` #### `custom_logo_dark` **Type**: str Path to an alternative logo for dark mode. Falls back to custom_logo if unset. **Example**: ```yaml custom_logo_dark: ./assets/logo_dark.svg ``` #### `custom_logo_url` **Type**: str URL the custom logo links to when clicked. **Example**: ```yaml custom_logo_url: https://www.scilifelab.se ``` #### `custom_logo_title` **Type**: str Tooltip text shown when hovering over the custom logo. **Example**: ```yaml custom_logo_title: Our institute name ``` #### `custom_logo_width` **Type**: int Logo width in pixels. Height scales proportionally. **Example**: ```yaml custom_logo_width: 200 ``` ### Branding #### `custom_favicon` **Type**: str Path to a custom favicon image to show in the browser tab. **Examples**: ```yaml custom_favicon: /path/to/favicon.ico ``` ```yaml custom_favicon: ./assets/favicon.png ``` #### `custom_css_files` **Type**: List[str] Paths to additional CSS files to inline into the report. Useful for branding overrides. **Example**: ```yaml custom_css_files: - ./assets/custom.css - /path/to/branding.css ``` ## Report Contents ### Custom content #### `custom_content` **Type**: Dict[str, Any] Embed arbitrary plots, tables or text in the report. See the [Custom Content docs](https://docs.seqera.io/multiqc/custom_content) for the full structure. **Example**: ```yaml custom_content: data: my-section-id: data: sample1: col1: 100 sample2: col1: 200 id: my-section-id plot_type: table section_name: My Custom Section order: - my-section-id - my-other-section-id ``` #### `custom_content_modules` **Type**: List[str] Extra module IDs whose output should be parsed as custom content. #### `custom_data` **Type**: Dict[str, Any] Inline custom content data keyed by section ID. Companion to custom_content for users who prefer splitting the metadata and the data across two top-level keys. ### Module ordering #### `top_modules` **Type**: List[Union[str, Dict[str, ModuleOverride]]] Module IDs to render before module_order. Useful for pinning a module to the top regardless of where it appears in module_order. Same shape as module_order entries. **Example**: ```yaml top_modules: - fastqc - cutadapt ``` #### `module_order` **Type**: List[Union[str, Dict[str, ModuleOverride]]] Order in which modules appear in the report. Each entry is either a module ID, or a single-key dict mapping the ID to per-run overrides (eg. name, anchor, info, path_filters, path_filters_exclude, generalstats, custom_config).
Default value ```yaml - custom_content - ccs - ngsderive - purple - conpair - isoseq - lima - peddy - percolator - haplocheck - somalier - methylqa - mosdepth - phantompeakqualtools - qualimap - bamdst - preseq - hifiasm - quast - qorts - rna_seqc - rockhopper - rsem - rseqc - busco - checkm - bustools - goleft_indexcov - gffcompare - disambiguate - supernova - deeptools - sargasso - verifybamid - mirtrace - happy - mirtop - glimpse - gopeaks - homer - hops - macs2 - theta2 - snpeff - gatk - htseq - bcftools - featurecounts - fgbio - dragen - dragen_fastqc - dedup - pbmarkdup - damageprofiler - mapdamage - biobambam2 - jcvi - mtnucratio - picard - vep - bakta - prokka - checkm2 - qc3C - nanoq - nanostat - samblaster - samtools - bamtools - sambamba - ngsbits - pairtools - sexdeterrmine - seqera_cli - eigenstratdatabasetools - jellyfish - vcftools - longranger - stacks - varscan2 - snippy - umicollapse - umitools - truvari - megahit - sincei - ganon - gtdbtk - bbmap - bismark - biscuit - diamond - hicexplorer - hicup - hicpro - salmon - kallisto - slamdunk - star - hisat2 - tophat - bowtie2 - bowtie1 - hostile - cellranger - checkatlas - snpsplit - odgi - vg - pangolin - nextclade - freyja - humid - kat - leehom - librarian - nonpareil - adapterremoval - bbduk - clipandmerge - cutadapt - trim_galore - flexbar - sourmash - kaiju - kraken - malt - motus - trimmomatic - sickle - skewer - sortmerna - ribodetector - biobloomtools - seqfu - fastq_screen - fastqe - afterqc - fastp - fastqc - sequali - filtlong - prinseqplusplus - pychopper - porechop - pycoqc - minionqc - anglerfish - multivcfanalyzer - clusterflow - checkqc - bcl2fastq - bclconvert - interop - ivar - flash - seqyclean - optitype - whatshap - spaceranger - xenome - xengsort - metaphlan - sylphtax - seqwho - telseq - ataqv - mgikit - mosaicatcher ```
**Example**: ```yaml module_order: - fastqc - fastqc: name: FastQC (trimmed) path_filters: - "*_trimmed*" - fastqc: generalstats: false name: FastQC (raw) - cutadapt ``` #### `run_modules` **Type**: List[str] Module IDs to run. If set, only listed modules are processed (mirror of the --module CLI flag). **Example**: ```yaml run_modules: - fastqc - cutadapt - samtools ``` #### `exclude_modules` **Type**: List[str] Module IDs to skip (mirror of the --exclude CLI flag). **Example**: ```yaml exclude_modules: - fastqc ``` #### `remove_sections` **Type**: List[str] Module sections to hide. Use the section anchor as it appears in the URL. **Example**: ```yaml remove_sections: - fastqc_overrepresented_sequences - gatk-compare-overlap ``` #### `report_section_order` **Type**: Dict[str, Union[Literal["remove"], SectionOrderOverride]] Reorder, group or hide report sections by ID. Values are either the literal string 'remove' (drops the section) or a dict with any combination of `order` (int), `before` (str) and `after` (str). See the [customisation docs](https://docs.seqera.io/multiqc/reports/customisation#order-of-module-and-module-subsection-output) for the full grammar. **Example**: ```yaml report_section_order: custom_content-my-section: before: fastqc fastqc: order: -10 ``` ### Section comments + indicators #### `section_comments` **Type**: Dict[str, str] Markdown text shown under specific module sections. Keys are section anchors. **Example**: ```yaml section_comments: fastqc_overrepresented_sequences: "**This is** an important note about the overrepresented\ \ sequences." samtools: Reviewed by *Phil* on 2024-08-21. ``` #### `section_status_checks` **Type**: Dict[str, Union[bool, Dict[str, bool]]] Enable or disable the green/yellow/red status indicators on report sections. Top-level keys are module IDs, values are either a bool or a dict mapping section ID to bool. **Example**: ```yaml section_status_checks: fastqc: true samtools: alignment_stats: false ``` ## Output Options ### Report file #### `force` **Type**: bool (default: `false`) Overwrite existing output files without prompting. #### `output_fn_name` **Type**: str (default: `"multiqc_report.html"`) Filename for the generated HTML report. Defaults to multiqc_report.html. #### `make_report` **Type**: bool (default: `true`) Generate the HTML report. Set to false to only produce data files. ### Data files #### `make_data_dir` **Type**: bool (default: `true`) Write parsed data as files alongside the report. #### `zip_data_dir` **Type**: bool (default: `false`) Compress the data directory into a single .zip file. #### `data_dir_name` **Type**: str (default: `"multiqc_data"`) Name of the directory written alongside the report holding parsed data. Defaults to multiqc_data. #### `data_format` **Type**: Literal["tsv", "csv", "json", "yaml"] (default: `"tsv"`) Format used when writing parsed data files. #### `data_format_extensions` **Type**: Dict[str, str] (default: `{"tsv":"txt","csv":"csv","json":"json","yaml":"yaml"}`) Override the file extension used when writing each data format, eg. {tsv: txt} to write TSV as .txt. **Example**: ```yaml data_format_extensions: json: json tsv: txt yaml: yml ``` #### `parquet_format` **Type**: Literal["long", "wide"] (default: `"long"`) Parquet table layout. 'long' has rows of (sample_name, metric_name, val_raw, val_raw_type, val_str), easy to filter by metric. 'wide' uses one column per metric (prefixed with table name and namespace), easier for analytics but can hit column limits or mixed-type issues. ### Data dump #### `data_dump_file` **Type**: bool (default: `true`) Write a single JSON file containing all parsed data, for re-running MultiQC later. #### `data_dump_file_write_raw` **Type**: bool (default: `true`) Include raw values (before any normalisation or filtering) in the dumped JSON. ### Plot export #### `export_plots` **Type**: bool (default: `false`) Save each plot as a static image (formats set by export_plot_formats). #### `export_plot_formats` **Type**: List[Literal["png", "svg", "pdf"]] (default: `["png","svg","pdf"]`) Image formats to export when export_plots is on. #### `export_plots_timeout` **Type**: int (default: `60`) Timeout for exporting each plot, in seconds. #### `plots_dir_name` **Type**: str (default: `"multiqc_plots"`) Directory for exported plot images when export_plots is on. Defaults to multiqc_plots. ### PDF #### `make_pdf` **Type**: bool (default: `false`) Also generate a PDF version of the report. Requires Pandoc to be installed. #### `pandoc_template` **Type**: str Path to a Pandoc template used when exporting the report as PDF. ## Sample Names ### Prepend directory #### `prepend_dirs` **Type**: bool (default: `false`) Prefix sample names with their parent directory. Useful when the same sample name occurs in multiple directories. #### `prepend_dirs_depth` **Type**: int (default: `0`) How many parent directories to include. 0 means all the way to the root. #### `prepend_dirs_sep` **Type**: str (default: `" | "`) String inserted between directory names and the sample name. Defaults to '|'. **Examples**: ```yaml prepend_dirs_sep: _ ``` ```yaml prepend_dirs_sep: " - " ``` ### Name cleaning #### `fn_clean_sample_names` **Type**: bool (default: `true`) Apply the cleaning rules in fn_clean_exts and fn_clean_trim to sample names. #### `extra_fn_clean_exts` **Type**: List[Union[str, CleanPattern]] Extensions appended to the built-in list. Use to add custom suffixes without overriding defaults. **Example**: ```yaml extra_fn_clean_exts: - .mySuffix - module: - samtools pattern: _tmp type: remove ``` #### `extra_fn_clean_trim` **Type**: List[str] Strings appended to the built-in trim list, without overriding defaults. **Example**: ```yaml extra_fn_clean_trim: - sample_ - _processed ``` #### `fn_clean_exts` **Type**: List[Union[str, CleanPattern]] Extensions stripped from sample names, eg. .gz, .fastq. Replaces the built-in list.
Default value ```yaml - .gz - .fastq - .fq - .bam - .cram - .sam - .sra - .vcf - .dat - _tophat - .pbmarkdup.log - .log - .stderr - .out - .spp - .fa - .fasta - .png - .jpg - .jpeg - .html - Log.final - ReadsPerGene - .flagstat - _star_aligned - _fastqc - .hicup - .counts - _counts - .txt - .tsv - .csv - .aligned - Aligned - .merge - .deduplicated - .dedup - .clean - .sorted - .report - "| stdin" - .geneBodyCoverage - .inner_distance_freq - .junctionSaturation_plot.r - .pos.DupRate.xls - .GC.xls - _slamdunk - _bismark - .conpair - .concordance - .contamination - .BEST.results - _peaks.xls - .relatedness - .cnt - .aqhist - .bhist - .bincov - .bqhist - .covhist - .covstats - .ehist - .gchist - .idhist - .ihist - .indelhist - .lhist - .mhist - .qahist - .qchist - .qhist - .rpkm - .selfSM - .extendedFrags - _SummaryStatistics - .purple.purity - .purple.qc - .trim - .bowtie2 - .mkD - .highfreq - .lowfreq - .consensus - .snpEff - .snpeff - .scaffolds - .contigs - .kraken2 - .ccurve - .hisat2 - _duprate - .markdup - .read_distribution - .junction_annotation - .infer_experiment - .biotype - .ivar - .mpileup - .primer_trim - .mapped - .vep - _vep - ccs - _NanoStats - .cutadapt - .qcML - .mosdepth - _gopeaks - .readCounts - .wgs_contig_mean_cov - _overall_mean_cov - _coverage_metrics - .wgs_fine_hist - .wgs_coverage_metrics - .wgs_hist - .vc_metrics - .gvcf_metrics - .ploidy_estimation_metrics - _overall_mean_cov - .fragment_length_hist - .mapping_metrics - .gc_metrics - .trimmer_metrics - .time_metrics - .quant_metrics - .quant.metrics - .quant.transcript_coverage - .scRNA_metrics - .scRNA.metrics - .scATAC_metrics - .scATAC.metrics - .fastqc_metrics - .labels - .bammetrics.metrics - .filter_summary - .cluster_report - .error.spl - .error.grp - .vgstats - _mapq_table - _strand_table - _isize_table - _dup_report - _cv_table - _covdist_all - _covdist_q40 - _CpGRetention - _CpHRetentionByReadPos - _totalBaseConversionRate - _totalReadConversionRate - .sylphmpa - _qual - _hifi_trimmer - .hifi_trimmer - _trimmer ```
**Example**: ```yaml fn_clean_exts: - .gz - .fastq - .bam - pattern: _S\d+_L\d+ type: regex ``` #### `fn_clean_trim` **Type**: List[str] Strings trimmed from the start or end of sample names. Replaces the built-in list.
Default value ```yaml - . - ":" - _ - "-" - .r - _val - .idxstats - _trimmed - .trimmed - .csv - .yaml - .yml - .json - _mqc - short_summary_ - _summary - .summary - .align - .h5 - _matrix - .stats - .hist - .phased - .tar - runs_ - .qc ```
**Example**: ```yaml fn_clean_trim: - _R1 - _R2 - _001 ``` #### `use_filename_as_sample_name` **Type**: Union[bool, List[str]] (default: `false`) Use the source filename as the sample name instead of any name parsed from the log. Set to true for all modules, or to a list of module IDs / patterns to apply selectively. ### Ignore samples #### `sample_names_ignore` **Type**: List[str] Glob patterns. Matching samples are dropped from the report. **Example**: ```yaml sample_names_ignore: - "*_temp" - control_* ``` #### `sample_names_ignore_re` **Type**: List[str] Regex patterns. Matching samples are dropped from the report. **Example**: ```yaml sample_names_ignore_re: - ^test_.* - .*_neg_ctrl$ ``` #### `sample_names_only_include` **Type**: List[str] Glob patterns. If set, only matching samples are kept. **Example**: ```yaml sample_names_only_include: - RNA_* - Sample_?? ``` #### `sample_names_only_include_re` **Type**: List[str] Regex patterns. If set, only matching samples are kept. **Example**: ```yaml sample_names_only_include_re: - ^WGS_[0-9]+$ ``` ### Rename and replace #### `sample_names_rename` **Type**: List[List[str]] Toolbox rename rows. Each entry is a list where the first element is the source sample name and each subsequent element is the rename for the corresponding button in `sample_names_rename_buttons` (so inner lists should have `1 + len(sample_names_rename_buttons)` elements). **Example**: ```yaml sample_names_rename: - - SMP001 - Patient_A - - SMP002 - Patient_B - - SMP003 - Patient_C ``` #### `sample_names_rename_buttons` **Type**: List[str] Names of the toolbox buttons that switch between the rename groups defined in sample_names_rename. **Example**: ```yaml sample_names_rename_buttons: - Sample ID - Patient ID - Lane ``` #### `sample_names_replace` **Type**: Dict[str, str] Substring replacements applied to every sample name. Keys are matched, values are replacements. **Example**: ```yaml sample_names_replace: Sample_: S _001: "" ``` #### `sample_names_replace_complete` **Type**: bool (default: `false`) Replace the entire sample name when the key matches anywhere in it. #### `sample_names_replace_exact` **Type**: bool (default: `false`) Only replace when the key matches the sample name exactly, not as a substring. #### `sample_names_replace_regex` **Type**: bool (default: `false`) Treat keys in sample_names_replace as regex patterns. ## File Discovery ### Input source #### `file_list` **Type**: bool (default: `false`) Treat the input path as a file containing a list of paths to scan, one per line. #### `require_logs` **Type**: bool (default: `false`) Fail with an error if any module explicitly requested with `--module` has no log files found. Off by default, so missing inputs are skipped silently. ### Size limits #### `log_filesize_limit` **Type**: int (default: `50000000`) Skip log files larger than this many bytes. #### `filesearch_lines_limit` **Type**: int (default: `1000`) Stop reading a log file after this many lines. ### Skip patterns #### `ignore_symlinks` **Type**: bool (default: `false`) Skip symlinked files and directories during the file search. #### `ignore_images` **Type**: bool (default: `true`) Skip image files (PNG/JPEG/etc.) to avoid wasting time opening them. #### `fn_ignore_dirs` **Type**: List[str] (default: `["multiqc_data",".git","icarus_viewers","runs_per_reference","not_aligned","contigs_reports"]`) Glob patterns for directory names to skip entirely during the file search. **Example**: ```yaml fn_ignore_dirs: - work - .nextflow - "*_logs" ``` #### `fn_ignore_paths` **Type**: List[str] (default: `["*/work/??/??????????????????????????????","*/.snakemake","*/.singularity","*/__pycache__","*/site-packages/multiqc"]`) Glob patterns for paths to skip during the file search. **Example**: ```yaml fn_ignore_paths: - "*/test_data/*" - "*/.snakemake/*" ``` #### `fn_ignore_files` **Type**: List[str] Glob patterns for file names to skip during the file search.
Default value ```yaml - .DS_Store - .py[cod] - "*.bam" - "*.bai" - "*.sam" - "*.fq.gz" - "*.fastq.gz" - "*.fq" - "*.fastq" - "*.fa" - "*.gtf" - "*.bed" - "*.vcf" - "*.tbi" - "*.txt.gz" - "*.pdf" - "*.md5" - "*.parquet" - "*[!s][!u][!m][!_\\.m][!mva][!qer][!cpy].html" - multiqc_data.json - "*.gam" - "*.gamp" - "*.jar" ```
**Example**: ```yaml fn_ignore_files: - "*.bai" - "*.bak" - "*.tmp" ``` #### `filesearch_file_shared` **Type**: List[str] Module IDs whose log files may be matched by multiple modules during the search. ### Search patterns #### `sp` **Type**: Dict[str, Union[SearchPattern, List[SearchPattern]]] Override or add to the built-in module search patterns. Top-level keys are module IDs (eg. `fastqc`); values are a single `SearchPattern` dict or a list of them. See the [SearchPattern](#searchpattern) definition below for the accepted fields.
Default value ```yaml multiqc_data: fn: "*multiqc.parquet" adapterremoval: fn: "*.settings" contents: AdapterRemoval num_lines: 1 xenium/metrics: fn: metrics_summary.csv contents: num_cells_detected num_lines: 5 xenium/experiment: fn: experiment.xenium num_lines: 50 afterqc: fn: "*.json" contents: allow_mismatch_in_poly num_lines: 10000 anglerfish: fn: "*.json" contents: anglerfish_version bakta: fn: "*.txt" contents: "Bakta:" bamdst/coverage: contents: "## The file was created by bamdst" num_lines: 5 bamtools/stats: contents: "Stats for BAM file(s):" num_lines: 10 bases2fastq/run: fn: RunStats.json contents: SampleStats num_lines: 100 bases2fastq/project: fn: "*_RunStats.json" contents: SampleStats num_lines: 100 bases2fastq/manifest: fn: RunManifest.json contents: Settings num_lines: 100 bbduk: contents: Executing jgi.BBDuk num_lines: 2 bbmap/stats: contents: - "#File" - "#Total" - "#Matched" - "#Name\tReads\tReadsPct" num_lines: 10 bbmap/bbsplit: contents: "#name\t%unambiguousReads\tunambiguousMB\t%ambiguousReads" num_lines: 5 bbmap/aqhist: contents: "#Quality\tcount1\tfraction1\tcount2\tfraction2" num_lines: 10 bbmap/bhist: contents: "#Pos\tA\tC\tG\tT\tN" num_lines: 10 bbmap/bincov: contents: "#RefName\tCov\tPos\tRunningPos" num_lines: 10 bbmap/bqhist: contents: "#BaseNum\tcount_1\tmin_1\tmax_1\tmean_1\tQ1_1\tmed_1\tQ3_1\tLW_1\tRW_1\t\ count_2\tmin_2\tmax_2\tmean_2\tQ1_2\tmed_2\tQ3_2\tLW_2\tRW_2" num_lines: 10 bbmap/covhist: contents: "#Coverage\tnumBases" num_lines: 10 bbmap/covstats: contents: "#ID\tAvg_fold" num_lines: 10 bbmap/ehist: contents: "#Errors\tCount" num_lines: 10 bbmap/gchist: contents: - "#Mean\t" - "#GC\tCount" num_lines: 10 bbmap/idhist: contents: - "#Mean_reads" - "#Identity\tReads\tBases" num_lines: 10 bbmap/ihist: contents: - "#Mean\t" - "#InsertSize\tCount" num_lines: 10 bbmap/indelhist: contents: "#Length\tDeletions\tInsertions" num_lines: 10 bbmap/lhist: contents: "#Length\tCount" num_lines: 10 bbmap/mhist: contents: "#BaseNum\tMatch1\tSub1\tDel1\tIns1\tN1\tOther1\tMatch2\tSub2\tDel2\t\ Ins2\tN2\tOther2" num_lines: 10 bbmap/qahist: contents: "#Quality\tMatch\tSub\tIns\tDel" num_lines: 10 bbmap/qchist: contents_re: "#Quality\tcount1\tfraction1$" num_lines: 10 bbmap/qhist: contents: "#BaseNum\tRead1_linear\tRead1_log\tRead1_measured" num_lines: 10 bbmap/rpkm: contents: - "#File\t" - "#Reads\t" - "#Mapped\t" - "#RefSequences\t" - "#Name Length" num_lines: 10 bbmap/statsfile_machine: contents: Reads Used= num_lines: 10 bbmap/statsfile: contents: - "Reads Used:" - "Mapping:" - "Reads/sec:" - "kBases/sec:" num_lines: 10 bcftools/stats: contents: This file was produced by bcftools stats bcl2fastq: fn: Stats.json contents: DemuxResults num_lines: 300 bclconvert/runinfo: fn: RunInfo.xml bclconvert/demux: fn: Demultiplex_Stats.csv bclconvert/quality_metrics: fn: Quality_Metrics.csv bclconvert/adaptermetrics: fn: Adapter_Metrics.csv bclconvert/unknown_barcodes: fn: Top_Unknown_Barcodes.csv biobambam2/bamsormadup: contents: "# bamsormadup" num_lines: 2 biobloomtools: contents: "filter_id\thits\tmisses\tshared\trate_hit\trate_miss\trate_shared" num_lines: 2 biscuit/align_mapq: fn: "*_mapq_table.txt" contents: BISCUITqc Mapping Quality Table num_lines: 3 biscuit/align_strand: fn: "*_strand_table.txt" contents: BISCUITqc Strand Table num_lines: 3 biscuit/align_isize: fn: "*_isize_table.txt" contents: BISCUITqc Insert Size Table num_lines: 3 biscuit/dup_report: fn: "*_dup_report.txt" contents: BISCUITqc Read Duplication Table num_lines: 3 biscuit/qc_cv: fn: "*_cv_table.txt" contents: BISCUITqc Uniformity Table num_lines: 3 biscuit/covdist_all_base_botgc: fn: "*_covdist_all_base_botgc_table.txt" biscuit/covdist_all_base: fn: "*_covdist_all_base_table.txt" biscuit/covdist_all_base_topgc: fn: "*_covdist_all_base_topgc_table.txt" biscuit/covdist_q40_base_botgc: fn: "*_covdist_q40_base_botgc_table.txt" biscuit/covdist_q40_base: fn: "*_covdist_q40_base_table.txt" biscuit/covdist_q40_base_topgc: fn: "*_covdist_q40_base_topgc_table.txt" biscuit/covdist_all_cpg_botgc: fn: "*_covdist_all_cpg_botgc_table.txt" biscuit/covdist_all_cpg: fn: "*_covdist_all_cpg_table.txt" biscuit/covdist_all_cpg_topgc: fn: "*_covdist_all_cpg_topgc_table.txt" biscuit/covdist_q40_cpg_botgc: fn: "*_covdist_q40_cpg_botgc_table.txt" biscuit/covdist_q40_cpg: fn: "*_covdist_q40_cpg_table.txt" biscuit/covdist_q40_cpg_topgc: fn: "*_covdist_q40_cpg_topgc_table.txt" biscuit/cpg_retention_readpos: fn: "*_CpGRetentionByReadPos.txt" biscuit/cph_retention_readpos: fn: "*_CpHRetentionByReadPos.txt" biscuit/base_avg_retention_rate: fn: "*_totalBaseConversionRate.txt" biscuit/read_avg_retention_rate: fn: "*_totalReadConversionRate.txt" bismark/align: fn: "*_[SP]E_report.txt" bismark/dedup: fn: "*.deduplication_report.txt" bismark/meth_extract: fn: "*_splitting_report.txt" bismark/m_bias: fn: "*M-bias.txt" bismark/bam2nuc: fn: "*.nucleotide_stats.txt" bowtie1: contents: "# reads processed:" exclude_fn: - bowtie.left_kept_reads.log - bowtie.left_kept_reads.m2g_um.log - bowtie.left_kept_reads.m2g_um_seg1.log - bowtie.left_kept_reads.m2g_um_seg2.log - bowtie.right_kept_reads.log - bowtie.right_kept_reads.m2g_um.log - bowtie.right_kept_reads.m2g_um_seg1.log - bowtie.right_kept_reads.m2g_um_seg2.log shared: true bowtie2: contents: "reads; of these:" exclude_contents: - bisulfite - HiC-Pro shared: true busco: fn: short_summary* contents: "BUSCO version is:" num_lines: 1 bustools: fn: "*inspect.json" ccs/v4: contents: ZMWs generating CCS num_lines: 2 max_filesize: 1024 ccs/v5: contents: '"id": "ccs_processing"' fn: "*.json" checkatlas/summary: fn: "*.tsv" contents_re: ^AtlasFileType\tNbCells\tNbGenes num_lines: 1 checkatlas/adata: fn: "*.tsv" contents_re: ^atlas_obs\tobsm\tvar\tvarm\tuns num_lines: 1 checkatlas/qc: fn: "*.tsv" contents_re: cellrank_(total_counts|n_genes_by_counts|pct_counts_mt) num_lines: 1 checkatlas/cluster: fn: "*.tsv" contents_re: ^Clust_Sample\tobs num_lines: 1 checkatlas/annotation: fn: "*.tsv" contents_re: ^Annot_Sample\tReference\tobs num_lines: 1 checkatlas/dimred: fn: "*.tsv" contents_re: ^Dimred_Sample\tobsm num_lines: 1 cellranger/count_html: - fn: "*.html" contents: '"command":"Cell Ranger","subcommand":"count"' num_lines: 20 - fn: "*.html" contents: '"command": "Cell Ranger", "subcommand": "count"' num_lines: 20 cellranger/vdj_html: - fn: "*.html" contents: '"command":"Cell Ranger","subcommand":"vdj"' num_lines: 20 - fn: "*.html" contents: '"command": "Cell Ranger", "subcommand": "vdj"' num_lines: 20 cellranger_arc: - fn: "*.html" contents: Cell Ranger ARC num_lines: 250 cells2stats/run: fn: RunStats.json contents: '"AnalysisID": "c2s.' num_lines: 100 checkm: - contents_re: ".*Bin Id(?:\t| {3,})Marker lineage(?:\t| {3,})# genomes(?:\t| {3,})#\ \ markers(?:\t| {3,})# marker sets.*" num_lines: 10 checkm2: contents: "Name\tCompleteness\tContamination\tCompleteness_Model_Used\tTranslation_Table_Used" num_lines: 10 checkqc: contents: instrument_and_reagent_type fn: "*.json" custom_content: fn_re: .+_mqc\.(yaml|yml|json|txt|csv|tsv|log|out|png|jpg|jpeg|gif|webp|tiff|html|md) clipandmerge: contents: ClipAndMerge ( num_lines: 5 clusterflow/logs: fn: "*_clusterFlow.txt" shared: true clusterflow/runfiles: fn: "*.run" contents: Cluster Flow Run File num_lines: 2 conpair/concordance: contents: markers (coverage per marker threshold num_lines: 3 conpair/contamination: contents: "Tumor sample contamination level: " num_lines: 3 cutadapt: - contents: This is cutadapt exclude_contents_re: "Trim Galore version: (?:[2-9]|\\d{2,})\\." num_lines: 100 - fn: "*.json" contents: Cutadapt report damageprofiler: fn: "*dmgprof.json" deacon: fn: "*.json" contents: '"version": "deacon' num_lines: 30 dedup: fn: "*.json" contents: '"tool_name": "DeDup"' num_lines: 20 deeptools/bamPEFragmentSizeTable: contents: "\tFrag. Sampled\tFrag. Len. Min.\tFrag. Len. 1st. Qu.\tFrag. Len. Mean\t\ Frag. Len. Median\tFrag. Len. 3rd Qu." num_lines: 1 deeptools/bamPEFragmentSizeDistribution: contents: "#bamPEFragmentSize" num_lines: 1 deeptools/estimateReadFiltering: contents: "Sample\tTotal Reads\tMapped Reads\tAlignments in blacklisted regions\t\ Estimated mapped reads" num_lines: 1 deeptools/plotCorrelationData: contents: "#plotCorrelation --outFileCorMatrix" num_lines: 1 deeptools/plotCoverageStdout: contents: "sample\tmean\tstd\tmin\t25%\t50%\t75%\tmax" num_lines: 1 deeptools/plotCoverageOutRawCounts: contents: "#plotCoverage --outRawCounts" num_lines: 1 deeptools/plotEnrichment: contents: "file\tfeatureType\tpercent\tfeatureReadCount\ttotalReadCount" num_lines: 1 deeptools/plotFingerprintOutRawCounts: contents: "#plotFingerprint --outRawCounts" num_lines: 1 deeptools/plotFingerprintOutQualityMetrics: contents: "Sample\tAUC\tSynthetic AUC\tX-intercept\tSynthetic X-intercept\tElbow\ \ Point\tSynthetic Elbow Point" num_lines: 1 deeptools/plotPCAData: contents: "#plotPCA --outFileNameData" num_lines: 1 deeptools/plotProfile: contents: bin labels num_lines: 1 diamond: fn: diamond.log disambiguate: contents: unique species A pairs num_lines: 2 dragen/vc_metrics: fn: "*.vc_metrics.csv" dragen/gvcf_metrics: fn: "*.gvcf_metrics.csv" dragen/ploidy_estimation_metrics: fn: "*.ploidy_estimation_metrics.csv" dragen/wgs_contig_mean_cov: fn_re: .*\.wgs_contig_mean_cov_?(tumor|normal)?\.csv dragen/overall_mean_cov_metrics: fn_re: .*_overall_mean_cov.*\.csv dragen/coverage_metrics: fn_re: .*_coverage_metrics.*\.csv dragen/wgs_fine_hist: fn_re: .*\.wgs_fine_hist_?(tumor|normal)?\.csv dragen/fragment_length_hist: fn: "*.fragment_length_hist.csv" dragen/mapping_metrics: fn: "*.mapping_metrics.csv" contents: Number of unique reads (excl. duplicate marked reads) num_lines: 50 dragen/gc_metrics: fn: "*.gc_metrics.csv" dragen/trimmer_metrics: fn: "*.trimmer_metrics.csv" dragen/time_metrics: fn: "*.time_metrics.csv" dragen/rna_quant_metrics: fn: "*.quant[._]metrics.csv" dragen/rna_transcript_cov: fn: "*.quant.transcript_coverage.txt" dragen/sc_rna_metrics: fn: "*.scRNA[._]metrics.csv" dragen/sc_atac_metrics: fn: "*.scATAC[._]metrics.csv" dragen_fastqc: fn: "*.fastqc_metrics.csv" eigenstratdatabasetools: fn: "*_eigenstrat_coverage.json" fastp: fn: "*.json" contents: '"before_filtering": {' num_lines: 50 fastq_screen: fn: "*_screen.txt" fastqe: fn: "*fastqe*" contents: "Filename\tStatistic\tQualities" num_lines: 1 fastqc/data: fn: "*fastqc_data.txt" fastqc/zip: fn: "*_fastqc.zip" fastqc/theoretical_gc: fn: "*fastqc_theoretical_gc*" featurecounts: fn: "*.summary" shared: true fgbio/groupreadsbyumi: contents: fraction_gt_or_eq_family_size num_lines: 3 fgbio/errorratebyreadposition: contents: "read_number\tposition\tbases_total\terrors\terror_rate\ta_to_c_error_rate\t\ a_to_g_error_rate\ta_to_t_error_rate\tc_to_a_error_rate\tc_to_g_error_rate\tc_to_t_error_rate" num_lines: 3 filtlong: contents: Scoring long reads contents_re: .*Filtering long reads.* num_lines: 5 flash/log: contents: "[FLASH]" flash/hist: fn: "*flash*.hist" flexbar: contents: Flexbar - flexible barcode and adapter removal freyja: fn: "*.tsv" contents: "summarized\t[" num_lines: 6 ganon: contents: - ganon-classify processed num_lines: 100 gatk/varianteval: contents: "#:GATKTable:TiTvVariantEvaluator" gatk/base_recalibrator: - contents: "#:GATKTable:Arguments:Recalibration" num_lines: 3 - contents: "#:SENTIEON_QCAL_TABLE:Arguments:Recalibration" num_lines: 3 gatk/analyze_saturation_mutagenesis: fn: "*.readCounts" contents: ">>Reads in disjoint pairs evaluated separately:" num_lines: 10 gffcompare: fn: "*.stats" contents: "# gffcompare" num_lines: 2 glimpse/err_spl: fn: "*.error.spl.txt.gz" num_lines: 1 glimpse/err_grp: fn: "*.error.grp.txt.gz" num_lines: 1 goleft_indexcov/roc: fn: "*-indexcov.roc" goleft_indexcov/ped: fn: "*-indexcov.ped" gopeaks: fn: "*_gopeaks.json" gtdbtk: contents: "user_genome\tclassification\tclosest_genome_reference\tclosest_genome_reference_radius\t\ closest_genome_taxonomy\tclosest_genome_ani" num_lines: 10 haplocheck: contents: "\"Sample\"\t\"Contamination Status\"\t\"Contamination Level\"\t\"Distance\"\ \t\"Sample Coverage\"" num_lines: 10 happy: fn: "*.summary.csv" contents: Type,Filter,TRUTH htseq: - contents_re: ^feature\tcount$ num_lines: 1 shared: true - contents_re: ^\w+.*\t\d+$ num_lines: 1 shared: true hicexplorer: contents: Min rest. site distance max_filesize: 4096 num_lines: 26 hicup: fn: HiCUP_summary_report* hicup/html: fn: "*HiCUP_summary_report*.html" hicpro/mmapstat: fn: "*mapstat" contents: total_R num_lines: 10 hicpro/mpairstat: fn: "*pairstat" contents: Total_pairs_processed num_lines: 10 hicpro/mergestat: fn: "*.mergestat" contents: valid_interaction num_lines: 10 hicpro/mRSstat: fn: "*RSstat" contents: Valid_interaction_pairs hicpro/assplit: fn: "*assplit.stat" hicstuff/pipeline_stats: - fn: "*.txt" contents: "## hicstuff:" num_lines: 100 - fn: "*.log" contents: "## hicstuff:" num_lines: 10 hicstuff/distancelaw: contents: "## distance_law" num_lines: 5 hifiasm: contents: "[M::ha_analyze_count]" num_lines: 1 hifi_trimmer: fn: "*.json" contents: '"total_reads_trimmed"' num_lines: 10 hisat2: contents: "HISAT2 summary stats:" homer/findpeaks: contents: "# HOMER Peaks" num_lines: 3 homer/GCcontent: fn: tagGCcontent.txt homer/genomeGCcontent: fn: genomeGCcontent.txt homer/RestrictionDistribution: fn: petagRestrictionDistribution.*.txt homer/LengthDistribution: fn: tagLengthDistribution.txt homer/tagInfo: fn: tagInfo.txt homer/FreqDistribution: fn: petag.FreqDistribution_1000.txt hops: fn: heatmap_overview_Wevid.json hostile: fn: "*.json" contents: '"reads_removed_proportion"' num_lines: 100 humid/stats: fn: stats.dat contents: "total: " num_lines: 1 humid/neighbours: fn: neigh.dat contents_re: "[0-9]+ [0-9]+" num_lines: 1 humid/counts: fn: counts.dat contents_re: "[0-9]+ [0-9]+" num_lines: 1 humid/clusters: fn: clusters.dat contents_re: "[0-9]+ [0-9]+" num_lines: 1 interop/summary: contents: Level,Yield,Projected Yield,Aligned,Error Rate,Intensity C1,%>=Q30 interop/index-summary: contents: Total Reads,PF Reads,% Read Identified (PF),CV,Min,Max isoseq/refine-json: contents: '"num_reads_fl"' fn: "*.json" isoseq/refine-csv: contents: id,strand,fivelen,threelen,polyAlen,insertlen,primer fn: "*.csv" isoseq/cluster-csv: contents: cluster_id fn: "*cluster_report.csv" num_lines: 1 ivar/trim: contents: Number of references num_lines: 8 jcvi: contents: " o % GC % of genome Average size (bp) Median size (bp)\ \ Number Total length (Mb)" jellyfish: fn: "*_jf.hist" kaiju: contents_re: file\tpercent\treads\ttaxon_id\ttaxon_name num_lines: 1 kallisto: contents: "[quant] finding pseudoalignments for the reads" kat: fn: "*.dist_analysis.json" kraken: contents_re: ^\s{0,2}(\d{1,3}\.\d{1,2})\t(\d+)\t(\d+)\t((\d+)\t(\d+)\t)?([URDKPCOFGS-]\d{0,2})\t(\d+)(\s+)[root|unclassified] num_lines: 2 librarian: fn: librarian_heatmap.txt leehom: contents: Adapter dimers/chimeras num_lines: 100 lima/summary: contents: ZMWs above all thresholds num_lines: 2 max_filesize: 1024 lima/counts: contents: "IdxFirst\tIdxCombined\tIdxFirstNamed\tIdxCombinedNamed\tCounts\tMeanScore" num_lines: 1 longranger/summary: fn: "*summary.csv" contents: longranger_version,instrument_ids,gems_detected,mean_dna_per_gem,bc_on_whitelist,bc_mean_qscore,n50_linked_reads_per_molecule num_lines: 2 longranger/invocation: fn: _invocation contents: call PHASER_SVCALLER_CS( max_filesize: 2048 macs2: fn: "*_peaks.xls" malt: contents: MaltRun - Aligns sequences using MALT (MEGAN alignment tool) num_lines: 2 mapdamage: - fn: 3p*_freq.txt - fn: 5p*_freq.txt - fn: lgdistribution.txt megahit: contents: " - MEGAHIT v" num_lines: 5 metaphlan: fn: "*.txt" contents: "#clade_name\tNCBI_tax_id\trelative_abundance\t" methurator: fn: "*methurator_summary.yml" methylqa: fn: "*.report" shared: true mgikit/mgi_ambiguous_barcode: fn: "*.mgikit.ambiguous_barcode" mgikit/mgi_sample_stats: fn: "*.mgikit.sample_stats" mgikit/mgi_general_info: fn: "*.mgikit.general" mgikit/mgi_sample_reads: fn: "*.mgikit.info" mgikit/mgi_undetermined_barcode: fn: "*.mgikit.undetermined_barcode" minionqc: fn: summary.yaml contents: total.gigabases mirtop: fn: "*_mirtop_stats.log" mirtrace/summary: fn: mirtrace-results.json mirtrace/length: fn: mirtrace-stats-length.tsv mirtrace/contaminationbasic: fn: mirtrace-stats-contamination_basic.tsv mirtrace/mirnacomplexity: fn: mirtrace-stats-mirna-complexity.tsv mtnucratio: fn: "*mtnuc.json" mosdepth/summary: fn: "*.mosdepth.summary.txt" mosdepth/global_dist: fn: "*.mosdepth.global.dist.txt" mosdepth/region_dist: fn: "*.mosdepth.region.dist.txt" motus: contents: Reads are aligned (by BWA) to marker gene sequences in the reference database num_lines: 2 multivcfanalyzer: fn: MultiVCFAnalyzer.json nanostat: max_filesize: 4096 contents_re: Metrics\s+dataset\s* num_lines: 1 nanostat/legacy: max_filesize: 4096 contents_re: General summary:\s* num_lines: 1 nanoq: contents: Nanoq Read Summary num_lines: 3 nextclade: contents: seqName;clade; num_lines: 1 ngsbits/readqc: - fn: "*.qcML" contents: ReadQC num_lines: 20 - fn: "*.qcML" contents: SeqPurge num_lines: 20 ngsbits/mappingqc: - fn: "*.qcML" contents: MappingQC num_lines: 20 ngsbits/samplegender: - fn: "*_ngsbits_sex.tsv" ngsderive/strandedness: contents: "File\tTotalReads\tForwardPct\tReversePct\tPredicted" num_lines: 1 ngsderive/instrument: contents: "File\tInstrument\tConfidence\tBasis" num_lines: 1 ngsderive/readlen: contents: "File\tEvidence\tMajorityPctDetected\tConsensusReadLength" num_lines: 1 ngsderive/encoding: contents: "File\tEvidence\tProbableEncoding" num_lines: 1 ngsderive/junction_annotation: contents: "File\ttotal_junctions\ttotal_splice_events\tknown_junctions\tpartial_novel_junctions\t\ complete_novel_junctions\tknown_spliced_reads\tpartial_novel_spliced_reads\tcomplete_novel_spliced_reads" num_lines: 1 nonpareil: - fn: "*.json" contents: LRstar num_lines: 50 max_filesize: 1048576 optitype: contents: "\tA1\tA2\tB1\tB2\tC1\tC2\tReads\tObjective" num_lines: 1 pangolin: contents: pangolin_version num_lines: 1 odgi: - fn: "*.og.stats.yaml" - fn: "*.og.stats.yml" - fn: "*.odgi.stats.yaml" - fn: "*.odgi.stats.yml" pairtools: contents: - "total_single_sided_mapped\t" - "cis\t" - "trans\t" - pair_types/ num_lines: 20 peddy/summary_table: fn: "*.peddy.ped" peddy/het_check: fn: "*.het_check.csv" peddy/ped_check: fn: "*.ped_check.csv" peddy/sex_check: fn: "*.sex_check.csv" peddy/background_pca: fn: "*.background_pca.json" percolator: fn: "*percolator_feature_weights.tsv" seqera_cli/run_dump: fn: runs_*.tar.gz seqera_cli/json: fn: workflow.json sequali: fn: "*.json" contents: '"sequali_version"' num_lines: 10 somalier/somalier-ancestry: fn: "*.somalier-ancestry.tsv" somalier/samples: fn: "*.samples.tsv" contents: "#family_id" num_lines: 5 somalier/pairs: fn: "*.pairs.tsv" contents: hom_concordance num_lines: 5 sourmash/compare: fn: "*.labels.txt" sourmash/gather: contents: intersect_bp,f_orig_query,f_match,f_unique_to_query,f_unique_weighted, num_lines: 1 pbmarkdup: contents_re: LIBRARY +READS +UNIQUE MOLECULES +DUPLICATE READS num_lines: 5 phantompeakqualtools/out: fn: "*.spp.out" picard/alignment_metrics: - contents: picard.analysis.AlignmentSummaryMetrics - contents: --algo AlignmentStat picard/basedistributionbycycle: contents: BaseDistributionByCycleMetrics picard/crosscheckfingerprints: contents: CrosscheckFingerprints picard/gcbias: - contents: GcBiasDetailMetrics - contents: GcBiasSummaryMetrics - contents: --algo GCBias picard/hsmetrics: - contents: HsMetrics - contents: --algo HsMetricAlgo picard/insertsize: - contents: picard.analysis.InsertSizeMetrics - contents: --algo InsertSizeMetricAlgo picard/markdups: - contents: picard.sam.MarkDuplicates - contents: picard.sam.DuplicationMetrics - contents: picard.sam.markduplicates.MarkDuplicates - contents: markduplicates.DuplicationMetrics - contents: MarkDuplicatesSpark - contents: markduplicates.GATKDuplicationMetrics - contents: --algo Dedup picard/oxogmetrics: - contents: "# picard.analysis.CollectOxoGMetrics" - contents: "# CollectOxoGMetrics" - contents_re: "# CollectMultipleMetrics .*OxoGMetrics" shared: true picard/pcr_metrics: - contents: "# picard.analysis.directed.CollectTargetedPcrMetrics" - contents_re: "# CollectMultipleMetrics .*TargetedPcrMetrics" shared: true picard/quality_by_cycle: - contents: "# MeanQualityByCycle" - contents: --algo MeanQualityByCycle - contents_re: .*CollectMultipleMetrics.*MeanQualityByCycle shared: true picard/quality_score_distribution: - contents: "# QualityScoreDistribution" - contents: --algo QualDistribution - contents_re: .*CollectMultipleMetrics.*QualityScoreDistribution shared: true picard/quality_yield_metrics: - contents: "# CollectQualityYieldMetrics" - contents_re: .*CollectMultipleMetrics.*QualityYieldMetrics shared: true picard/rnaseqmetrics: - contents: "# picard.analysis.Collectrnaseqmetrics" - contents: "# picard.analysis.CollectRnaSeqMetrics" - contents: "# CollectRnaSeqMetrics" - contents_re: "# CollectMultipleMetrics .*RnaSeqMetrics" shared: true picard/rrbs_metrics: - contents: "# picard.analysis.CollectRrbsMetrics" - contents_re: "# CollectMultipleMetrics .*RrbsMetrics" shared: true picard/sam_file_validation: fn: "*[Vv]alidate[Ss]am[Ff]ile*" picard/variant_calling_metrics: contents_re: "## METRICS CLASS.*VariantCallingDetailMetrics" picard/wgs_metrics: - contents: --algo WgsMetricsAlgo - contents_re: "## METRICS CLASS.*WgsMetrics" shared: true picard/collectilluminabasecallingmetrics: contents: CollectIlluminaBasecallingMetrics picard/collectilluminalanemetrics: contents: CollectIlluminaLaneMetrics picard/extractilluminabarcodes: contents: ExtractIlluminaBarcodes picard/markilluminaadapters: contents: MarkIlluminaAdapters porechop: contents: Looking for known adapter sets num_lines: 10 preseq: - contents: EXPECTED_DISTINCT num_lines: 2 - contents: distinct_reads num_lines: 2 preseq/real_counts: fn: "*preseq_real_counts*" prinseqplusplus: - contents: reads removed by - num_lines: 2 prokka: contents: "contigs:" num_lines: 2 purple/qc: fn: "*.purple.qc" purple/purity: fn: "*.purple.purity.tsv" pycoqc: contents: '"pycoqc":' num_lines: 2 pychopper: contents: "Classification\tRescue" num_lines: 6 qc3C: fn: "*.qc3C.json" qorts: contents: BENCHMARK_MinutesOnSamIteration num_lines: 100 qorts/log: fn: QC.*.log contents: Starting QoRTs num_lines: 2 qualimap/bamqc/genome_results: fn: genome_results.txt qualimap/bamqc/coverage: fn: coverage_histogram.txt qualimap/bamqc/insert_size: fn: insert_size_histogram.txt qualimap/bamqc/genome_fraction: fn: genome_fraction_coverage.txt qualimap/bamqc/gc_dist: fn: mapped_reads_gc-content_distribution.txt qualimap/bamqc/html: fn: qualimapReport.html contents: "Qualimap report: BAM QC" num_lines: 10 qualimap/rnaseq/rnaseq_results: fn: rnaseq_qc_results.txt qualimap/rnaseq/coverage: fn: coverage_profile_along_genes_(total).txt qualimap/rnaseq/html: fn: qualimapReport.html contents: "Qualimap report: RNA Seq QC" num_lines: 10 quast: fn: report.tsv contents: "Assembly\t" num_lines: 2 rna_seqc/metrics_v1: fn: "*metrics.tsv" contents: "Sample\tNote\t" rna_seqc/metrics_v2: fn: "*metrics.tsv" contents: High Quality Ambiguous Alignment Rate rna_seqc/coverage: fn_re: meanCoverageNorm_(high|medium|low)\.txt rna_seqc/correlation: fn_re: corrMatrix(Pearson|Spearman)\.txt rna_seqc/html: fn: index.html contents: RNA-SeQC v num_lines: 200 ribotish/qual: fn: "*_qual.txt" num_lines: 10 ribowaltz/psite_region: fn: "*ribowaltz*psite_region.tsv" contents_re: "sample[,\t]region[,\t]count[,\t]scaled_count" num_lines: 1 ribowaltz/frames: fn: "*ribowaltz*frames.tsv" contents_re: "sample[,\t]region[,\t]frame[,\t]count[,\t]scaled_count" num_lines: 1 ribowaltz/metaprofile: fn: "*ribowaltz*metaprofile_psite.tsv" contents_re: "sample[,\t]region[,\t]x[,\t]y" num_lines: 1 riker/alignment: fn: "*.alignment-metrics.txt" contents_re: ^sample\b.*\bcategory\b num_lines: 1 riker/basic_base_dist: fn: "*.base-distribution-by-cycle.txt" contents_re: ^sample\b.*\bfrac_a\b num_lines: 1 riker/basic_mean_quality: fn: "*.mean-quality-by-cycle.txt" contents_re: ^sample\b.*\bmean_quality\b num_lines: 1 riker/basic_quality_dist: fn: "*.quality-score-distribution.txt" contents_re: ^sample\b.*\bfrac_bases\b num_lines: 1 riker/gcbias_detail: fn: "*.gcbias-detail.txt" contents_re: ^sample\b.*\bnormalized_coverage\b num_lines: 1 riker/gcbias_summary: fn: "*.gcbias-summary.txt" contents_re: ^sample\b.*\bgc_0_19_normcov\b num_lines: 1 riker/hybcap_metrics: fn: "*.hybcap-metrics.txt" contents_re: ^sample\b.*\bbait_territory\b num_lines: 1 riker/isize_metrics: fn: "*.isize-metrics.txt" contents_re: ^sample\b.*\bpair_orientation\b num_lines: 1 riker/isize_histogram: fn: "*.isize-histogram.txt" contents_re: ^sample\b.*\bfr_count\b num_lines: 1 riker/wgs_metrics: fn: "*.wgs-metrics.txt" contents_re: ^sample\b.*\bgenome_territory\b num_lines: 1 riker/wgs_coverage: fn: "*.wgs-coverage.txt" contents_re: ^sample\b.*\bbases_at_or_above\b num_lines: 1 rockhopper: fn: summary.txt contents: Number of gene-pairs predicted to be part of the same operon max_filesize: 500000 ribodetector: contents: Writing output non-rRNA sequences into file num_lines: 20 rsem: fn: "*.cnt" rseqc/bam_stat: contents: "Proper-paired reads map to different chrom:" max_filesize: 500000 rseqc/gene_body_coverage: fn: "*.geneBodyCoverage.txt" rseqc/inner_distance: fn: "*.inner_distance_freq.txt" rseqc/junction_annotation: contents: "Partial Novel Splicing Junctions:" max_filesize: 500000 rseqc/junction_saturation: fn: "*.junctionSaturation_plot.r" rseqc/read_gc: fn: "*.GC.xls" rseqc/read_distribution: contents: Group Total_bases Tag_count Tags/Kb max_filesize: 500000 rseqc/read_duplication_pos: fn: "*.pos.DupRate.xls" rseqc/infer_experiment: - fn: "*infer_experiment.txt" - contents: Fraction of reads explained by max_filesize: 500000 rseqc/tin: fn: "*.summary.txt" contents: TIN(median) num_lines: 1 salmon/meta: fn: meta_info.json contents: salmon_version num_lines: 10 max_filesize: 50000 salmon/lfc: fn: lib_format_counts.json salmon/fld: fn: flenDist.txt sambamba/markdup: contents: finding positions of the duplicate reads in the file num_lines: 50 samblaster: contents: "samblaster: Version" samtools/stats: contents: This file was produced by samtools stats samtools/flagstat: contents: in total (QC-passed reads + QC-failed reads) samtools/idxstats: fn: "*idxstat*" samtools/rmdup: contents: "[bam_rmdup" samtools/ampliconclip: contents: - "COMMAND:" - samtools ampliconclip num_lines: 11 samtools/coverage: contents: "#rname\tstartpos\tendpos\tnumreads\tcovbases\tcoverage\tmeandepth\tmeanbaseq\t\ meanmapq" num_lines: 10 samtools/markdup_txt: contents: - "^COMMAND:" - samtools markdup num_lines: 2 samtools/markdup_json: contents: - '"COMMAND":' - samtools markdup num_lines: 10 sargasso: fn: overall_filtering_summary.txt seqfu/stats: contents: "File\t#Seq\tTotal bp\tAvg\tN50\tN75\tN90\tauN\tMin\tMax" num_lines: 1 seqkit/stats: contents_re: ^file\s+format\s+type\s+num_seqs\s+sum_len num_lines: 1 seqwho: contents: ' "Per Base Seq": [' num_lines: 10 seqyclean: fn: "*_SummaryStatistics.tsv" sexdeterrmine: fn: sexdeterrmine.json sickle: contents_re: "FastQ \\w*\\s?records kept: .*" num_lines: 2 sincei/scFilterStats: contents: "Cell_ID\tTotal_sampled\tFiltered\tBlacklisted\tLow_MAPQ\tMissing_Flags\t\ Excluded_Flags" num_lines: 1 sincei/scCountQC: fn: "*.cells.tsv" contents: "Cell_ID\tbarcodes\tsample\tn_genes_by_counts\tlog1p_n_genes_by_counts\t\ total_counts" skewer: contents: "maximum error ratio allowed (-r):" slamdunk/summary: contents: "# slamdunk summary" num_lines: 1 slamdunk/PCA: contents: "# slamdunk PCA" num_lines: 1 slamdunk/rates: contents: "# slamdunk rates" num_lines: 1 slamdunk/utrrates: contents: "# slamdunk utrrates" num_lines: 1 slamdunk/tcperreadpos: contents: "# slamdunk tcperreadpos" num_lines: 1 slamdunk/tcperutrpos: contents: "# slamdunk tcperutr" num_lines: 1 snippy/snippy: contents: snippy num_lines: 20 snippy/snippy-core: contents_re: ID\tLENGTH\tALIGNED\tUNALIGNED\tVARIANT\tHET\tMASKED\tLOWCOV num_lines: 1 snpeff: contents: SnpEff_version max_filesize: 5000000 snpsplit/old: contents: "Writing allele-flagged output file to:" num_lines: 2 snpsplit/new: fn: "*SNPsplit_report.yaml" software_versions: fn_re: .+_mqc_versions\.(yaml|yml) sompy: fn: "*.stats.csv" contents: ",sompyversion,sompycmd" num_lines: 2 sortmerna: contents: Minimal SW score based on E-value spaceranger/count_html: - fn: "*.html" contents: '"command":"Space Ranger","subcommand":"count"' num_lines: 20 - fn: "*.html" contents: '"command": "Space Ranger", "subcommand": "count"' num_lines: 20 stacks/gstacks: fn: gstacks.log.distribs contents: BEGIN effective_coverages_per_sample stacks/populations: fn: populations.log.distribs contents: BEGIN missing_samples_per_loc_prefilters stacks/sumstats: fn: "*.sumstats_summary.tsv" contents: "# Pop ID\tPrivate\tNum_Indv\tVar\tStdErr\tP\tVar" max_filesize: 1000000 star: fn: "*Log.final.out" star/genecounts: fn: "*ReadsPerGene.out.tab" supernova/report: fn: "*report*.txt" num_lines: 100 contents: "- assembly checksum =" supernova/summary: fn: summary.json num_lines: 120 contents: '"lw_mean_mol_len":' supernova/molecules: fn: histogram_molecules.json num_lines: 10 contents: '"description": "molecules",' supernova/kmers: fn: histogram_kmer_count.json num_lines: 10 contents: '"description": "kmer_count",' sylphtax: fn: "*.sylphmpa" telseq: num_lines: 3 contents: "ReadGroup\tLibrary\tSample\tTotal\tMapped\tDuplicates\tLENGTH_ESTIMATE" theta2: fn: "*.BEST.results" tophat: fn: "*align_summary.txt" shared: true trim_galore: fn: "*_trimming_report.json" trimmomatic: contents_re: ^Trimmomatic truvari/bench: contents_re: .*truvari.* bench.* fn: log.txt num_lines: 10 umicollapse: num_lines: 100 contents: "UMI collapsing finished in " umitools/extract: contents: "# output generated by extract" num_lines: 100 umitools/dedup: contents: "# output generated by dedup" num_lines: 100 varscan2/mpileup2snp: contents: Only SNPs will be reported num_lines: 10 varscan2/mpileup2indel: contents: Only indels will be reported num_lines: 10 varscan2/mpileup2cns: contents: Only variants will be reported num_lines: 10 vcftools/relatedness2: fn: "*.relatedness2" vcftools/tstv_by_count: fn: "*.TsTv.count" vcftools/tstv_by_qual: fn: "*.TsTv.qual" vcftools/tstv_summary: fn: "*.TsTv.summary" vep/vep_html: fn: "*.html" contents: VEP summary num_lines: 10 max_filesize: 1000000 vep/vep_txt: contents: "[VEP run statistics]" num_lines: 1 max_filesize: 100000 verifybamid/selfsm: fn: "*.selfSM" vg/stats: contents: - "Total perfect:" - "Total gapless (softclips allowed):" - "Total time:" - "Speed:" num_lines: 30 whatshap/stats: contents: "#sample\tchromosome\tfile_name\tvariants\tphased\tunphased\tsingletons" num_lines: 1 xenome: contents: "B\tG\tH\tM\tcount\tpercent\tclass" num_lines: 2 xengsort: contents: "# Xengsort classify" num_lines: 2 ataqv: fn: "*.json" contents: ataqv_version num_lines: 10 mosaicatcher: fn: "*.mosaicatcher_info_raw.txt" ```
**Example**: ```yaml sp: fastqc/data: fn: fastqc_data.txt fastqc/zip: fn: "*_fastqc.zip" ``` ## Plot Settings ### Rendering mode #### `plots_force_flat` **Type**: bool (default: `false`) Render plots as static images instead of interactive Plotly. Useful for very large reports. #### `plots_force_interactive` **Type**: bool (default: `false`) Force interactive plots even when MultiQC would normally fall back to flat images. #### `plots_flat_numseries` **Type**: int (default: `2000`) If a plot has more than this many series, MultiQC switches it from interactive to flat image. #### `plots_defer_loading_numseries` **Type**: int (default: `100`) Plots with more than this many series start collapsed. The user clicks a button to render them. #### `num_datasets_plot_limit` **Type**: int (default: `100`) Deprecated. Use `plots_defer_loading_numseries` instead. ### Appearance #### `plots_export_font_scale` **Type**: float (default: `1.0`) Multiplier applied to font sizes in exported plot images. Bump up for publication-quality output. #### `plot_font_family` **Type**: str CSS font-family for plot text. Defaults to a system font stack. #### `custom_plot_config` **Type**: Dict[str, Any] Override plot config options per plot. Top-level keys are plot IDs, values are option dicts. **Example**: ```yaml custom_plot_config: fastqc_per_base_sequence_quality_plot: title: "FastQC: Mean Quality Scores (custom)" yaxis: title: Phred score ``` #### `lineplot_number_of_points_to_hide_markers` **Type**: int (default: `50`) Hide individual data point markers in line plots once the total point count across samples exceeds this. #### `barplot_legend_on_bottom` **Type**: bool (default: `false`) Place bar plot legends below the plot instead of to the side. Not recommended. ### Boxplot and violin #### `boxplot_boxpoints` **Type**: Literal["outliers", "suspectedoutliers", "all", False] (default: `"outliers"`) How boxplot data points are drawn. Use false to hide individual points. #### `box_min_threshold_outliers` **Type**: int (default: `100`) When a boxplot has more samples than this, only outlier points are drawn. #### `box_min_threshold_no_points` **Type**: int (default: `1000`) When a boxplot has more samples than this, no individual points are drawn. #### `violin_downsample_after` **Type**: int (default: `2000`) Start downsampling violin plot data once the sample count exceeds this. Keeps rendering snappy. #### `violin_min_threshold_outliers` **Type**: int (default: `100`) When a violin plot has more samples than this, only outlier points are drawn. #### `violin_min_threshold_no_points` **Type**: int (default: `1000`) When a violin plot has more samples than this, no individual points are drawn. ## Toolbox ### Highlighting #### `highlight_patterns` **Type**: List[str] Substring (or regex) patterns. Matching samples are highlighted in plots and tables. **Example**: ```yaml highlight_patterns: - control - treated ``` #### `highlight_colors` **Type**: List[str] CSS colour for each entry in highlight_patterns, in the same order. Accepts hex (`#377eb8`), named colours (`red`), or any CSS colour function (`rgb(...)`, `hsl(...)`). **Example**: ```yaml highlight_colors: - "#377eb8" - "#e41a1c" ``` #### `highlight_regex` **Type**: bool (default: `false`) Treat highlight_patterns as regex instead of plain substring. ### Show/hide buttons #### `show_hide_buttons` **Type**: List[str] Labels for the toolbox show/hide buttons. One per pattern set. **Example**: ```yaml show_hide_buttons: - Tumour samples - Normal samples ``` #### `show_hide_patterns` **Type**: List[Union[str, List[str]]] Patterns for each show/hide button. Each entry is a string or list of strings to match against sample names. **Example**: ```yaml show_hide_patterns: - - _T_ - _tumour_ - - _N_ - _normal_ ``` #### `show_hide_mode` **Type**: List[Literal["show", "hide", "show_re", "hide_re"]] Action for each show/hide button: 'show' (only show matches), 'hide' (hide matches), or their `_re` variants which signal regex patterns (set by the TSV loader). **Example**: ```yaml show_hide_mode: - show - show ``` #### `show_hide_regex` **Type**: List[Union[str, bool]] Whether each pattern set is treated as regex. List of bools aligned with show_hide_buttons. **Example**: ```yaml show_hide_regex: - false - false ``` ## Table Settings ### General #### `collapse_tables` **Type**: bool (default: `true`) Collapse module tables by default. Users click to expand. #### `max_table_rows` **Type**: int (default: `500`) Tables larger than this many rows are rendered as a violin plot instead. #### `max_configurable_table_columns` **Type**: int (default: `200`) Cap on the number of columns the user can toggle in the table-configure toolbox. #### `decimalPoint_format` **Type**: str (default: `"."`) Decimal-point character used in formatted numbers. Defaults to `.` **Example**: ```yaml decimalPoint_format: "," ``` #### `thousandsSep_format` **Type**: str (default: `" "`) Thousands separator used in formatted numbers. Defaults to a single space, which is rendered as a small non-breaking space. **Example**: ```yaml thousandsSep_format: "," ``` ### General Stats table #### `general_stats_columns` **Type**: Dict[str, GeneralStatsModuleConfig] Per-module overrides for General Stats columns. Top-level keys are module IDs. **Example**: ```yaml general_stats_columns: fastqc: columns: percent_duplicates: format: "{:,.1f}%" max: 100 min: 0 scale: RdYlGn-rev title: "% Dups" ``` #### `general_stats_helptext` **Type**: str Help text shown under the General Statistics heading at the top of the report. #### `skip_generalstats` **Type**: bool (default: `false`) Hide the General Statistics table at the top of the report. ### Column overrides #### `table_columns_name` **Type**: Dict[str, Union[str, Dict[str, str]]] Rename table columns. Top-level keys are module IDs, inner keys are column IDs, values are the new display name. **Example**: ```yaml table_columns_name: fastqc: percent_duplicates: "% Dups" percent_gc: "% GC" ``` #### `table_columns_placement` **Type**: Dict[str, Dict[str, float]] Reorder table columns. Top-level keys are module IDs, inner keys are column IDs, values are float sort weights (lower is further left). **Example**: ```yaml table_columns_placement: fastqc: percent_duplicates: 900 percent_gc: 800 total_sequences: 700 ``` #### `table_columns_visible` **Type**: Dict[str, Union[bool, Dict[str, bool]]] Hide or show specific columns. Top-level keys are module IDs, values are either a bool (apply to all columns) or a dict mapping column ID to bool. **Example**: ```yaml table_columns_visible: fastqc: false samtools: error_rate: false raw_total_sequences: true ``` #### `custom_table_header_config` **Type**: Dict[str, Any] Override table column config. Same shape as custom_plot_config but for table headers. **Example**: ```yaml custom_table_header_config: general_stats_table: "% Dups": format: "{:,.1f}%" max: 100 min: 0 ``` ### Conditional formatting #### `table_cond_formatting_rules` **Type**: Dict[str, Dict[str, List[CondFormattingRule]]] Conditional cell formatting. Nested dicts map table ID (or the literal 'all_columns') to colour ID to a list of rules. Each rule has exactly one operator: string operators (s_eq, s_ne, s_contains) compare case-insensitively; numeric operators (eq, ne, gt, lt, ge, le) cast both sides to float. See the customisation docs for the full grammar.
Default value ```yaml all_columns: pass: - s_eq: pass - s_eq: "true" - s_eq: "yes" - s_eq: ok warn: - s_eq: warn - s_eq: unknown fail: - s_eq: fail - s_eq: "false" - s_eq: "no" male: - s_eq: male - s_eq: M female: - s_eq: female - s_eq: F QCStatus: fail: - s_contains: fail ```
**Example**: ```yaml table_cond_formatting_rules: all_columns: fail: - s_eq: fail pass: - s_eq: pass - s_eq: ok warn: - s_eq: warn mqc-generalstats-percent_duplicates: fail: - gt: 50 warn: - gt: 20 ``` #### `table_cond_formatting_colours` **Type**: List[Dict[str, str]] Background colours referenced by table_cond_formatting_rules. List of single-key dicts mapping a colour ID to a hex code.
Default value ```yaml - blue: "#337ab7" - lbue: "#5bc0de" - pass: "#5cb85c" - warn: "#f0ad4e" - fail: "#d9534f" - male: "#5bc0de" - female: "#d9534f" ```
**Example**: ```yaml table_cond_formatting_colours: - pass: "#5cb85c" - warn: "#f0ad4e" - fail: "#d9534f" ``` ### Row merging #### `table_sample_merge` **Type**: Dict[str, Union[str, CleanPattern, List[Union[str, CleanPattern]]]] Group samples by merging rows of supporting modules' tables, by collapsing samples that match a pattern. Keys are the merged group name; values are a clean-pattern entry (a string suffix, or a {type, pattern} dict) or a list of such entries. **Examples**: ```yaml table_sample_merge: R1: _1 R2: _2 ``` ```yaml table_sample_merge: R1: - _R1 - pattern: "[_.-][rR]?1$" type: regex R2: - _R2 - pattern: "[_.-][rR]?2$" type: regex ``` ## Software Versions ### `software_versions` **Type**: Dict[str, Union[str, List[str], Dict[str, Union[str, List[str]]]]] Manually specify software versions for the Software Versions section. Top-level keys are group or software names. Values are a single version string, a list of version strings, or a dict mapping software name to a version string or list of version strings (when the group contains multiple tools). **Examples**: ```yaml software_versions: bwa: 0.7.17 fastqc: 0.12.1 samtools: "1.20" ``` ```yaml software_versions: quast: - 5.2.0 - 5.1.0 ``` ```yaml software_versions: samtools: htslib: "1.3" samtools: "1.11" ``` ### `versions_table_group_header` **Type**: str (default: `"Group"`) Column header for the grouping column in the Software Versions table. Defaults to 'Group'. ### `disable_version_detection` **Type**: bool (default: `false`) Skip parsing software versions from module log files. ### `skip_versions_section` **Type**: bool (default: `false`) Hide the Software Versions section. ## Read & Base Counts ### Short reads #### `read_count_multiplier` **Type**: float (default: `1e-06`) Multiplier applied to read counts before display. Default 0.000001 shows reads in millions. **Example**: ```yaml read_count_multiplier: 0.001 ``` #### `read_count_prefix` **Type**: str (default: `"M"`) Suffix shown after formatted read counts, eg. 'M' for millions. **Example**: ```yaml read_count_prefix: K ``` #### `read_count_desc` **Type**: str (default: `"millions"`) Word used in plot/axis labels for read counts, eg. 'millions'. **Examples**: ```yaml read_count_desc: thousands ``` ```yaml read_count_desc: raw reads ``` ### Long reads #### `long_read_count_multiplier` **Type**: float (default: `0.001`) Multiplier for long-read counts. Default 0.001 shows counts in thousands. **Example**: ```yaml long_read_count_multiplier: 1.0e-06 ``` #### `long_read_count_prefix` **Type**: str (default: `"K"`) Suffix shown after formatted long-read counts, eg. 'K' for thousands. **Example**: ```yaml long_read_count_prefix: M ``` #### `long_read_count_desc` **Type**: str (default: `"thousands"`) Word used in labels for long-read counts, eg. 'thousands'. **Example**: ```yaml long_read_count_desc: millions ``` ### Bases #### `base_count_multiplier` **Type**: float (default: `1e-06`) Multiplier for base counts. Default 0.000001 shows bases in megabases. **Example**: ```yaml base_count_multiplier: 0.001 ``` #### `base_count_prefix` **Type**: str (default: `"Mb"`) Suffix shown after formatted base counts, eg. 'Mb' for megabases. **Example**: ```yaml base_count_prefix: Kb ``` #### `base_count_desc` **Type**: str (default: `"millions"`) Word used in labels for base counts, eg. 'megabases'. **Example**: ```yaml base_count_desc: kilobases ``` ## AI Summary ### On/off #### `ai_summary` **Type**: bool (default: `false`) Generate a short AI-written summary at the top of the report. #### `ai_summary_full` **Type**: bool (default: `false`) Also generate a longer per-section AI summary. Requires ai_summary to be on. #### `no_ai` **Type**: bool (default: `false`) Disable AI summaries entirely. Overrides ai_summary and ai_summary_full. ### Prompts #### `ai_prompt_short` **Type**: str Custom prompt prepended to the short AI summary request. Use to steer tone, length, or focus. **Example**: ```yaml ai_prompt_short: Write the summary in one short paragraph aimed at a lab head, no jargon. ``` #### `ai_prompt_full` **Type**: str Custom prompt prepended to the full-section AI summary request. **Example**: ```yaml ai_prompt_full: Use bullet points and call out any sample that looks like an outlier. ``` ### Privacy #### `ai_anonymize_samples` **Type**: bool (default: `false`) Replace sample names with placeholders before sending data to the AI provider. ### Provider #### `ai_provider` **Type**: Literal["seqera", "openai", "anthropic", "aws_bedrock", "custom"] (default: `"seqera"`) AI provider used for summaries. One of seqera, openai, anthropic, aws_bedrock, custom. #### `ai_model` **Type**: str Model name. Provider-specific. **Examples**: ```yaml ai_model: gpt-4o ``` ```yaml ai_model: claude-sonnet-4-5. ``` #### `ai_custom_endpoint` **Type**: str Base URL for the 'custom' provider, eg. a self-hosted OpenAI-compatible API. **Examples**: ```yaml ai_custom_endpoint: http://localhost:11434/v1 ``` ```yaml ai_custom_endpoint: https://api.example.com/v1 ``` #### `ai_auth_type` **Type**: Literal["bearer", "api-key"] Authentication scheme used by the custom endpoint. 'bearer' sends an Authorization header, 'api-key' sends an api-key header. #### `seqera_website` **Type**: str (default: `"https://ai.seqera.io"`) Base URL used for Seqera Platform links in the report. #### `seqera_api_url` **Type**: str (default: `"https://ai.seqera.io/v1/web"`) Base URL for the Seqera Platform API. Defaults to the public instance. ### Tuning #### `ai_retries` **Type**: int (default: `3`) Number of times to retry an AI request on transient errors. #### `ai_extra_query_options` **Type**: Dict[str, Any] Extra request-body fields merged into the AI request payload (provider-specific). **Example**: ```yaml ai_extra_query_options: temperature: 0.3 top_p: 0.9 ``` #### `ai_custom_context_window` **Type**: int Override the model's context window in tokens. Set this if MultiQC's default for your model is wrong. #### `ai_max_completion_tokens` **Type**: int Maximum completion tokens for OpenAI reasoning models. #### `ai_reasoning_effort` **Type**: Literal["low", "medium", "high"] Reasoning effort for OpenAI reasoning models. #### `ai_extended_thinking` **Type**: bool (default: `false`) Enable extended thinking on Anthropic Claude models that support it. #### `ai_thinking_budget_tokens` **Type**: int Token budget for Anthropic extended thinking when enabled. ## MegaQC ### `megaqc_url` **Type**: str URL of a MegaQC instance to upload report data to after generation. ### `megaqc_access_token` **Type**: str Auth token for the MegaQC instance. ### `megaqc_timeout` **Type**: int (default: `30`) Upload timeout in seconds when posting to MegaQC. ### `megaqc_upload` **Type**: bool Upload report data to MegaQC after generation. Requires megaqc_url and megaqc_access_token. ## Performance & Debugging ### Profiling #### `profile_runtime` **Type**: bool (default: `false`) Time each module and include the breakdown in the report. #### `profile_memory` **Type**: bool (default: `false`) Track peak memory per module. Adds runtime overhead. ### Logging #### `verbose` **Type**: bool (default: `false`) Print extra debug log messages to the terminal. #### `no_ansi` **Type**: bool (default: `false`) Disable ANSI colour codes in terminal output. #### `quiet` **Type**: bool (default: `false`) Suppress non-essential log messages. ### Linting #### `strict` **Type**: bool (default: `false`) Treat module warnings as errors. Stricter than lint. #### `lint` **Type**: bool (default: `false`) Deprecated. Run module linting and fail the build on issues. Used in MultiQC's own tests, rarely useful otherwise. ### Developer #### `development` **Type**: bool (default: `false`) Enable developer-mode features such as live JS reloading. For internal use. #### `report_readerrors` **Type**: bool (default: `false`) Surface file read errors in the log instead of silently skipping them. #### `preserve_module_raw_data` **Type**: bool (default: `false`) Keep each module's raw parsed data in memory after report generation. Used by Python API consumers. ### Version check #### `no_version_check` **Type**: bool (default: `false`) Skip the network check for newer MultiQC versions on startup. #### `version_check_url` **Type**: str (default: `"https://api.multiqc.info/version"`) URL queried by MultiQC's own update check. Set to override the default endpoint. ## Special Types ### SearchPattern Configuration for file search patterns used to find tool outputs. The `SearchPattern` type is used in the `sp` configuration option to define patterns for finding and parsing tool output files. Example: ```yaml sp: fastqc: fn: "*_fastqc.zip" custom_tool: fn: "*.log" contents: "Started analysis" ``` Properties: - **contents** (Union[str, List[str]]): File contents to match - **contents_re** (Union[str, List[str]]): File contents regex pattern to match - **exclude_contents** (Union[str, List[str]]): Exclude files containing this content - **exclude_contents_re** (Union[str, List[str]]): Exclude files containing this regex content - **exclude_fn** (Union[str, List[str]]): Exclude files matching this pattern - **exclude_fn_re** (Union[str, List[str]]): Exclude files matching this regex pattern - **fn** (str): Filename pattern to match - **fn_re** (str): Filename regex pattern to match - **max_filesize** (int): Maximum file size to process - **num_lines** (int): Number of lines to search - **shared** (bool): Allow file to be processed by multiple search patterns - **skip** (bool): Skip this search pattern ### CleanPattern Pattern for cleaning sample names. The `CleanPattern` type is used in the `fn_clean_exts` and `extra_fn_clean_exts` configuration options to define patterns for cleaning sample names. Example: ```yaml fn_clean_exts: - type: truncate pattern: '_S\d+_L\d+' - type: regex pattern: '\d{4}-\d{2}-\d{2}' ``` Properties: - **module** (Union[str, List[str]]): Module(s) to apply this pattern to - **pattern** (str): Pattern to match - **type** (Literal["truncate", "remove", "regex", "regex_keep"]): Type of pattern matching to use ### GeneralStatsModuleConfig Per-module wrapper for General Stats column overrides. The `GeneralStatsModuleConfig` type is the value of each module entry in the `general_stats_columns` configuration option. It has a single `columns` key mapping column IDs to `GeneralStatsColumnConfig` settings. Example: ```yaml general_stats_columns: fastqc: columns: percent_duplicates: title: "% Dups" ``` Properties: - **columns** (Dict[str, GeneralStatsColumnConfig]): Columns to show in general stats table. Keys are column IDs. ### GeneralStatsColumnConfig Configuration for columns in the general statistics table. The `GeneralStatsColumnConfig` type is used in the `general_stats_columns` configuration option to customize the appearance and behavior of columns in the general statistics table. Example: ```yaml general_stats_columns: fastqc: columns: percent_duplicates: title: "% Dups" description: "Percentage of duplicate reads" scale: "RdYlGn-rev" max: 100 min: 0 ``` Properties: - **ceiling** (float): Ceiling value - **description** (str): Column description - **floor** (float): Floor value - **format** (str): Number format - **hidden** (bool): Whether column is hidden by default - **max** (float): Maximum value - **min** (float): Minimum value - **namespace** (str): Column namespace - **placement** (float): Column placement order - **scale** (str): Color scale - **shared_key** (str): Shared key name - **title** (str): Column title ### CondFormattingRule One conditional-formatting comparison for a table cell. Used in the `table_cond_formatting_rules` configuration option. Each rule is a dict with exactly one operator key paired with its comparison value. String operators (`s_eq`, `s_ne`, `s_contains`) compare case-insensitively; numeric operators (`eq`, `ne`, `gt`, `lt`, `ge`, `le`) cast both sides via `float()`. Example: ```yaml table_cond_formatting_rules: all_columns: pass: - s_eq: "pass" fail: - gt: 50 ``` Properties: - **eq** (Union[float, int]): Numeric equality - **ge** (Union[float, int]): Greater than or equal to - **gt** (Union[float, int]): Strictly greater than - **le** (Union[float, int]): Less than or equal to - **lt** (Union[float, int]): Strictly less than - **ne** (Union[float, int]): Numeric inequality - **s_contains** (str): Case-insensitive substring match - **s_eq** (str): Case-insensitive string equality - **s_ne** (str): Case-insensitive string inequality ### ModuleOverride Per-module override values for `top_modules` and `module_order` entries. Each entry in `top_modules` / `module_order` is either a module ID (string) or a single-key dict mapping the module ID to a `ModuleOverride` dict. Example: ```yaml module_order: - fastqc: name: "FastQC (trimmed)" anchor: "fastqc_trimmed" path_filters: - "*_trimmed*" ``` Properties: - **anchor** (str): HTML/section anchor for this module run - **comment** (str): Comment text rendered as markdown under the heading - **custom_config** (Dict[str, Any]): Module-specific config values merged into config. - **doi** (Union[str, List[str]]): DOI or list of DOIs - **extra** (str): Extra HTML appended after the intro - **generalstats** (bool): Set to false to suppress this module's general-stats columns - **href** (Union[str, List[str]]): Tool homepage URL, or list of URLs - **info** (str): Intro text rendered as markdown under the section heading - **name** (str): Display name for this module run - **path_filters** (Union[str, List[str]]): Glob patterns restricting which files this module run sees - **path_filters_exclude** (Union[str, List[str]]): Glob patterns excluding files from this module run ### SectionOrderOverride Override dict accepted as a `report_section_order` value. Each value in `report_section_order` is either the literal string `"remove"` (drops the section) or a `SectionOrderOverride` dict combining any of `order`, `before` and `after`. Example: ```yaml report_section_order: fastqc: order: -10 custom_content-my-section: before: fastqc mod_section_2: remove ``` Properties: - **after** (str): Section/module/anchor ID to position this entry after - **before** (str): Section/module/anchor ID to position this entry before - **order** (int): Explicit numeric order --- ## Custom content # Introduction Bioinformatics projects often include non-standardised analyses, with results from custom scripts or in-house packages. It can be frustrating to have a MultiQC report describing results from 90% of your pipeline but missing the final key plot. To help with this, MultiQC has a special _"custom content"_ module. Custom content parsing is a little more restricted than standard modules. Specifically: - Only one plot per section is possible - Plot customisation is more limited All plot types can be generated using custom content - see the [test files](https://github.com/MultiQC/test-data/tree/main/data/custom_content) for examples of how data should be structured. :::note Use the name `custom_content` to refer to this module within configuration settings that require a module name, such as [`module_order`](../reports/customisation.md#order-of-modules) or [`run_modules`](../reports/customisation.md#removing-modules-or-sections). ::: ## Data from a released tool If your data comes from a released bioinformatics tool, you shouldn't be using this feature of MultiQC! Sure, you can probably get it to work, but it's better if a fully-fledged core MultiQC module is written instead. That way, other users of MultiQC can also benefit from results parsing. Note that proper MultiQC modules are more robust and powerful than this custom-content feature. You can also [write modules](../development/modules.md) in [MultiQC plugins](../development/plugins.md) if they're not suitable for general release. ## Images It is possible to import custom images into your MultiQC reports. Simply add `_mqc` to the end of the filename for `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` or `.tiff` files, for example: `my_image_file_mqc.png` or `summmary_diagram.jpeg`. Images will be embedded within the HTML file, so will be self contained. Note that this means that it's very possible to make the HTML file very very large if abused! Images are base64 encoded in the HTML and the report will often be larger than the binary source images. The report section name and description will be automatically based on the filename. Note that if you are using `sp:` to take in images with a custom filename you need to also set `ignore_images: false` in your config. For example: ```yaml custom_data: my_custom_content_image: section_name: "My nice image" sp: my_custom_content_image: fn: "*.png" ignore_images: false ``` ## MultiQC-specific data file If you can choose exactly how your data output looks, then the easiest way to parse it is to use a MultiQC-specific format. If the filename ends in `*_mqc.(yaml|yml|json|txt|csv|tsv|log|out|png|jpg|jpeg|html)` then it will be found by any standard MultiQC installation with no additional customisation required. These files contain configuration information specifying how the data should be parsed, alongside the data. If you want to use YAML, this is an example of how it should look: ```yaml id: "my_pca_section" section_name: "PCA Analysis" description: "This plot shows the first two components from a principal component analysis." plot_type: "scatter" pconfig: id: "pca_scatter_plot" title: "PCA Plot" xlab: "PC1" ylab: "PC2" data: sample_1: { x: 12, y: 14 } sample_2: { x: 8, y: 6 } sample_3: { x: 5, y: 11 } sample_4: { x: 9, y: 12 } ``` :::note This example YAML file is data only, and is not to be confused with a config file (though the two look very similar). See the docs [Data as part of MultiQC config](#data-as-part-of-multiqc-config) for more on that. ::: The file format can also be JSON. Note however that JSON doesn't preserve the order of elements in dicts, thus the preferred way to specify the series data points is through a list of tuples. For example: ```json { "id": "custom_data_lineplot", "section_name": "Custom JSON File", "description": "This plot is a self-contained JSON file.", "plot_type": "linegraph", "pconfig": { "id": "custom_data_linegraph", "title": "Output from my JSON file", "ylab": "Number of things", "xDecimals": false }, "data": { "sample_1": [ [1, 12], [2, 14], [3, 10], [4, 7], [5, 16] ], "sample_2": [ [1, 9], [2, 11], [3, 15], [4, 18], [5, 21] ] } } ``` Note that if you're using `plot_type: html` then `data` just takes a string, with no sample keys. For maximum compatibility with other tools, you can also use comma-separated or tab-separated files. Include commented header lines with plot configuration in YAML format: ```bash # id: "Output from my script' # section_name: 'Custom data file' # description: 'This output is described in the file header. Any MultiQC installation will understand it without prior configuration.' # format: 'tsv' # plot_type: 'bargraph' # pconfig: # id: 'custom_bargraph_w_header' # ylab: 'Number of things' Category_1 374 Category_2 229 Category_3 39 Category_4 253 ``` You can easily inject custom HTML snippets by ending the filename with `_mqc.html` - again the embedded config works in a similar way, but with a HTML comment: ```html Some custom HTML content here. ``` If no configuration is given, MultiQC will do its best to guess how to visualise your data appropriately. To see examples of typical file structures which are understood, see the [test data](https://github.com/MultiQC/test-data/tree/main/data/custom_content/no_config) used to develop this code. Something will be probably be shown, but it may produce unexpected results. :::note Check [Tricky extras](#tricky-extras) for certain caveats about formatting headers for custom `tsv` or `csv` files, particularly for the first column. ::: ## Data as part of MultiQC config If you are already using a MultiQC config file to add data to your report (for example, [titles / introductory text](../getting_started/config.md)), you can give data within this file too. This can be in any MultiQC config file (for example, passed on the command line with `-c my_yaml_file.yaml` or in your launch directory as `multiqc_config.yml` - see [Configuration](../getting_started/config.md)). :::note This is not to be confused with the YAML data files described in the above section, [MultiQC-specific data file](#multiqc-specific-data-file). For example, MultiQC config files will _not_ be found with `_mqc.yml` file extensions. ::: This is useful as you can keep everything contained within a single file (including stuff unrelated to this specific _custom content_ feature of MultiQC). To be understood by MultiQC, the `custom_data` key must be found. This must contain a section with a unique id, specific to your new report section. Finally, the contents of this second dictionary will look the same as the above stand-alone `YAML` files. For example: ```yaml custom_data: my_data_type: id: "mqc_config_file_section" section_name: "My Custom Section" description: "This data comes from a single multiqc_config.yaml file" plot_type: "bargraph" pconfig: id: "barplot_config_only" title: "MultiQC Config Data Plot" ylab: "Number of things" data: sample_a: first_thing: 12 second_thing: 14 sample_b: first_thing: 8 second_thing: 6 sample_c: first_thing: 11 second_thing: 5 sample_d: first_thing: 12 second_thing: 9 ``` Or to add data to the General Statistics table: ```yaml custom_data: my_genstats: plot_type: "generalstats" headers: - col_1: max: 100 min: 0 scale: "RdYlGn" suffix: "%" - col_2: min: 0 data: sample_a: col_1: 14.32 col_2: 1.2 sample_b: col_1: 84.84 col_2: 1.9 ``` :::note Use a **list** of headers in `pconfig` (keys prepended with `-`) to specify the order of columns in the General Statistics table. ::: See the [general statistics docs](../development/modules.md#step-3---adding-to-the-general-statistics-table) for more information about configuring data for the General Statistics table. ## Separate configuration and data files It's not always possible or desirable to include MultiQC configuration within a data file. If this is the case, you can add to the MultiQC configuration to specify how input files should be parsed. As described in the [Data as part of MultiQC config](#data-as-part-of-multiqc-config) section, this configuration should be held within a section called `custom_data` with a section-specific id. The only difference is that no `data` subsection is given and a search pattern for the given id must be supplied. Search patterns are added [as with any other module](../getting_started/config.md#module-search-patterns). Ensure that the search pattern key is the same as your `custom_data` section ID. For example, a MultiQC config file could look as follows: ```yaml # Other MultiQC config stuff here custom_data: example_files: file_format: "tsv" section_name: "Coverage Decay" description: "This plot comes from files acommpanied by a multiqc_config.yaml file for configuration" plot_type: "linegraph" pconfig: id: "example_coverage_lineplot" title: "Coverage Decay" ylab: "X Coverage" ymax: 100 ymin: 0 sp: example_files: fn: "example_files_*" ``` And work with the following data file: `example_files_Sample_1.txt`: ```bash 0 98.22076066 1 97.96764159 2 97.78227175 3 97.61262195 # [...] ``` This kind of customisation should work with most Custom Content types. For example, using an image called `some_science_mqc.jpeg` gives us a report section `some_science`, which we can then add a nicer name and description to: ```yaml custom_data: some_science: section_name: "Some real science" description: "This description comes from multiqc_config.yaml and helps to annotate the Custom Content image." ``` If no configuration is given, MultiQC will do its best to guess how to visualise your data appropriately. To see examples of typical file structures which are understood, see the [test data](https://github.com/MultiQC/test-data/tree/main/data/custom_content/no_config) used to develop this code. # Configuration ## Grouping sections and subsections If you have multiple content types that you would like to group together with MultiQC sub-sections, you can do so using the following keys: ```yaml parent_id: custom_section parent_name: "Some grouped data" parent_description: "This parent section contains one or more sub-sections below it" ``` Any custom-content files that share the same `parent_id` will be grouped. Note that some things, such as `parent_name` are taken from the first file that MultiQC finds with this `parent_id`. So it's a good idea to specify this in every file. `parent_description` and `extra` is taken from the first file where it is set. :::warning `parent_id` only works within Custom Content. It is not currently possible to add custom content output into a report section from a core MultiQC module. ::: ## Order of sections If you have multiple different Custom Content sections, their order will be random and may vary between runs. To avoid this, you can specify an order in your MultiQC config as follows: ```yaml custom_content: order: - first_cc_section - second_cc_section ``` Each section name should be the ID assigned to that section. You can explicitly set this (see below), or the Custom Content module will automatically assign an ID. To find out what your custom content section ID is, generate a report and click the side navigation to your section. The browser URL should update and show something that looks like this: ``` multiqc_report.html#my_cc_section ``` The section ID is the part after the `#` (`my_cc_section` in the above section). Note that any Custom Content sections found that are _not_ specified in the config will be placed at the top of the report. ## Section configuration See below for how these config options can be specified (either within the data file or in a MultiQC config file). All of these configuration parameters are optional, and MultiQC will do its best to guess sensible defaults if they are not specified. All possible configuration keys and their default values are shown below: ```yaml id: null # Unique ID for report section. section_anchor: # Used in report section #soft-links section_name: # Nice name used for the report section header section_href: null # External URL for the data, to find more information description: null # Introductory text to be printed under the section header helptext: null # Help text to be shown in a collapsible box (toggled with a help button) section_extra: null # Custom HTML to add after the section description file_format: null # File format of the data (eg. csv / tsv) plot_type: null # The plot type to visualise the data with. # generalstats | table | bargraph | linegraph | boxplot | scatter | heatmap | violin pconfig: {} # Configuration for the plot. ``` :::info Data types `generalstats` and `violin` are _only_ possible by setting the above configuration keys (these can't be guessed by data format). ::: Note that any _custom content_ data found with the same section `id` will be merged into the same report section / plot. The other section configuration keys are merged for each file, with identical keys overwriting what was previously parsed. This approach means that it's possible to have a single file containing data for multiple samples, but it's also possible to have one file per sample and still have all of them summarised. :::note If you're using `plot_type: 'generalstats'` then a report section will not be created and most of the configuration keys above are ignored. ::: ## Plot configuration Configuration of specific plots follows the same syntax as used when writing modules. To find out more, please see the later docs. Specifically, the plot config docs for [bar graphs](../development/plots.md#bar-graphs), [line graphs](../development/plots.md#line-graphs), [box plots](../development/plots.md#box-plots), [scatter plots](../development/plots.md#scatter-plots), [tables](../development/plots.md#creating-a-table), [violin plots](../development/plots.md#violin-plots) and [heatmaps](../development/plots.md#heatmaps). Wherever you see `pconfig`, any key can be used within the above syntax. ## Tricky extras Because of the way this module works, there are a few specifics that can trip you up. Most of these should probably be fixed one day. Feel free to ask for help on the [community forum](https://community.seqera.io/c/multiqc/6), or submit a pull request! I'll try to keep a list here to help the wary... ### Differences between Tables and General Stats Although they're both tables, note that general stats configures columns with a list in the `pconfig` scope (see above example). Files that are just tables use `headers` instead. ### First columns in tables are special The first column in every table is reserved for the sample name. As such, it shouldn't contain data. All header configuration will be ignored for the first column. The only exception is name: this can be tweaked using the somewhat tricky `col1_header` field in the `pconfig` scope (see table docs). Alternatively, you can customise the column name by including a 'header row' in the first line of the `tsv` or `csv` itself specifying the column names, with the first column with the name of your choice, and subsequent columns including the key(s) defined in the header. ### Quoting strings If you happen to use sample names or other values that appear number-like, and want to prevent MultiQC from attempt to parse them, you can quote them. For example, in this TSV defining a table all values would have been interpreted as numbers if they were not wrapped in quotes `"`: ``` # plot_type: "table" Sample Name,Size,Representative Id "01",100,"1446399400_1_131" "02",120,"782510898_278_395" ``` ## Linting MultiQC has been developed to be as forgiving as possible and will handle lots of invalid or ignored configurations. This is useful for most users but can make life difficult when getting MultiQC to work with a new custom content format. To help with this, you can run MultiQC with the `--strict` flag, which will give explicit warnings about anything that is not optimally configured. For example: ```bash multiqc --strict test-data ``` You can alternatively enable the strict mode by setting the environment variable `MULTIQC_STRICT`, or by setting it into the [config](../getting_started/config.md): `strict: true`. # Examples Probably the best way to get to grips with Custom Content is to see some examples. The MultiQC automated testing runs with a [number of different files](https://github.com/MultiQC/test-data/tree/main/data/custom_content) which you can look through for inspiration. For example, to see a file which generates a table in a report by itself, you can have a look at `embedded_config/table_headers_txt_mqc.txt` ([link](https://github.com/MultiQC/test-data/blob/main/data/custom_content/embedded_config/table_headers_txt_mqc.txt)). --- ## Breaking changes # Updating after major changes When releasing new versions of MultiQC we aim to maintain compatibility so that your existing modules and plugins will keep working. However, in some cases we have to make changes that require code to be modified. This section describes any major breaking changes in MultiQC releases. ## GitHub Repo and Docker images moved On December 18th 2023, just after the v1.19 release of MultiQC, the GitHub repo and Docker images were moved. - GitHub source code: - Repo name `ewels/MultiQC` became `MultiQC/MultiQC` - Default branch `master` was renamed to `main` - Docker images renamed: - DockerHub: `ewels/multiqc` became `multiqc/multiqc` - GitHub Packages: `ghcr.io/ewels/multiqc` became `ghcr.io/multiqc/multiqc` ### GitHub repository name change The [`ewels/MultiQC` repository](https://github.com/ewels/MultiQC) was moved to [`MultiQC/MultiQC`](https://github.com/MultiQC/MultiQC). All issues, pull-requests and other GitHub metadata moved with it. In most cases, GitHub should automatically redirect to the new location and you should not notice any difference. However, if you have a local clone / fork of the repository it's still a good idea to update the remote name. Assuming that you have forked the repo and have a local clone, configured with a remote called `upstream` with which you pull in new changes (with `git pull upstream`), you can rename the remote with the following: ```bash git remote set-url upstream git@github.com:MultiQC/MultiQC.git ``` ### Default branch name changed At the same time as moving the repo, we also changed the default branch name from `master` to `main`. This is inline with changing industry standards. See [`github/renaming`](https://github.com/github/renaming/) and [this software freedom conservancy blog post](https://sfconservancy.org/news/2020/jun/23/gitbranchname/) for more details. If you maintain your own fork of MultiQC, it will be unaffected by this change. The branch name is only switched on the main MultiQC repository. All pull-requests have been automatically updated to point to the renamed branch. If you wish to change the default branch name on your fork, you can do (probably a good idea so as not to get confusing). First, rename the branch on GitHub.com (_Settings_ -> _Default branch_, see also the [GitHub docs](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch)) Once renamed on GitHub.com, you'll need to rename the branch in your local clone and point to the renamed remote branch: ```bash git branch -m master main git fetch origin git branch -u origin/main main git remote set-head origin -a ``` ### New Docker images To coincide with the GitHub repository renaming, the official Docker images have also been renamed. **The previous `ewels/multiqc` images have _not_ been removed**, so as not to hinder reproducibility. However, they will no longer be updated and get no new pushes to `:dev`, `:latest` or releases after `:v1.19`. New docker images have been created [at DockerHub (`multiqc/multiqc`)](https://hub.docker.com/r/multiqc/multiqc/) and at [GitHub Packages (`ghcr.io/multiqc/multiqc`)](https://github.com/MultiQC/MultiQC/pkgs/container/multiqc). These do not have old versions, but will be updated from now on with releases v1.20 and onwards. ## v1.0 Updates MultiQC v1.0 brings a few changes in the way that MultiQC modules and plugins are written. Most are backwards-compatible, but there are a couple that could break external plugins. #### Module imports New MultiQC module imports have been refactored to make them less inter-dependent and fragile. This has a bunch of advantages, notably allowing better, more modular, unit testing (and hopefully more reliable and maintainable code). All MultiQC modules and plugins will need to change some of their import statements. There are two things that you probably need to change in your plugin modules to make them work with the updated version of MultiQC, both to do with imports. Instead of this style of importing modules: ```python from multiqc import config, BaseMultiqcModule, plots ``` You now need this: ```python from multiqc import config from multiqc.plots import bargraph # Load specific plot types here from multiqc.modules.base_module import BaseMultiqcModule ``` Modules that directly reference `multiqc.BaseMultiqcModule` instead need to reference `multiqc.modules.base_module.BaseMultiqcModule`. Secondly, modules that use `import plots` now need to import the specific plots needed. You will also need to update any plotting functions, removing the `plot.` prefix. For example, change this: ```python return plots.bargraph.plot(data, keys, pconfig) ``` to this: ```python from plots import bargraph return bargraph.plot(data, keys, pconfig) ``` These changes have been made to simplify the module imports within MultiQC, allowing specific parts of the codebase to be imported into a Python script on their own. This enables small, atomic, clean unit testing. If you have any questions, please open an issue. > Many thanks to [@tbooth](https://github.com/tbooth) at [@EdinburghGenomics](https://github.com/EdinburghGenomics) for his patient work with this. #### Searching for files The core `find_log_files` function has been rewritten and now works a little differently. Instead of searching all analysis files each time it's called (by every module), all files are searched once at the start of the MultiQC execution. This makes MultiQC run much faster. To use the new syntax, add your search pattern to `config.sp` using the new `before_config` plugin hook: `setup.py`: ```python # [..] 'multiqc.hooks.v1': [ 'before_config = myplugin.mymodule:load_config' ] ``` `mymodule.py`: ```python from multiqc.utils import config def load_config(): my_search_patterns = { 'my_plugin/my_mod': {'fn': '*_somefile.txt'}, 'my_plugin/my_other_mod': {'fn': '*other_file.txt'}, } config.update_dict(config.sp, my_search_patterns) ``` This will add in your search patterns to the default MultiQC config, before user config files are loaded (allowing people to overwrite your defaults as with other modules). Now, you can find your files much as before, using the string specified above: ```python for f in self.find_log_files('my_plugin/my_mod'): # do something ``` The old syntax (supplying a `dict` instead of a string to the function without any previous config setup) will still work, but you will get a depreciation notice. This functionality may be removed in the future. #### Adding report sections Report sections can be added by the method called `self.add_section()`. For example: ```python self.add_section( name='My Section', anchor='my-html-id', description='Description of what this plot shows.', helptext='More extensive help text can about how to interpret this.', plot=linegraph.plot(data, pconfig), ) ``` Text passed as `description` and `helptext` is wrapped in `` tags, and additional raw content can be provided with a `content` or `content_before_plot` string if required. Use the `alerts` parameter for Bootstrap alert boxes instead of appending raw alert HTML to `description` or `content`. #### Updated number formatting A couple of minor updates to how numbers are handled in tables may affect your configs. Firstly, format strings looking like `{:.1f}` should now be `{:,.1f}` (note the extra comma). This enables customisable number formatting with separated thousand groups. For example, `{:,.2f}` will format `1234567.89` as `1,234,567.89`. For decimal numbers, use `{:,d}`. Secondly, any table columns reporting a read and base counts should use new config options to allow user-configurable multipliers. For example, instead of this: ```python headers['read_counts'] = { 'title': 'M Reads', 'description': 'Read counts (millions)', 'modify': lambda x: x / 1000000, 'format': '{:.,2f} M', 'shared_key': 'read_count' } ``` you should now use this: ```python headers['read_counts'] = { 'title': f'{config.read_count_prefix} Reads', 'description': f'Total raw sequences ({config.read_count_desc})', 'modify': lambda x: x * config.read_count_multiplier, 'format': '{:,.2f} ' + config.read_count_prefix, 'shared_key': 'read_count' } ``` Not as pretty, but allows users to view low depth coverage. Similarly, for base counts: ```python headers['base_counts'] = { 'title': f'{config.base_count_prefix} Bases', 'description': f'Total raw bases ({config.base_count_desc})', 'modify': lambda x: x * config.base_count_multiplier, 'format': '{:,.2f} ' + config.base_count_prefix, 'shared_key': 'base_count' } ``` --- ## Contributing ## Changelog `CHANGELOG.md` file is populated semi-automatically. To generate an initial state, we use a script: ```sh python scripts/print_changelog.py ``` It automatically generates the changelog from the merged pull-requests assigned to a milestone (e.g. `v1.26`), using titles as changelog entries, and tags (labels) to categorize entries in sections (e.g. `New modules`, `Module fixes`, `Infrastructure`, etc.). We run that script before creating a release. For that reason, **your job is to ensure that your pull-request has a clean thoughtful title**. The title must summarize the changes, and be written in a good English without typos and errors, start with a capital letter, and have single spaces between words. Examples of good titles: - "Prepend plot IDs with `self.anchor` to assure custom anchor is applied" - "New module: Percolator (semi-supervised learning framework for peptide identification)" - "GATK BQSR: support Sentieon QualCal output" Add labels to the PR to automatically categorize them in the changelog: - `module: new` - "New modules" - `module: enhancement`, `module: change` - "Module updates" - `bug: module` - "Module fixes" - `bug: core` - "Fixes" - `core: back end`, `core: front end` - "Feature updates and improvements" - `core: infrastructure` - "Infrastructure and packaging" - `core: refactoring` - "Refactoring and typing" - `documentation` - "Chores" ## Docs - Admonitions Admonitions, sometimes known as call-outs, can be used to highlight relevant information in the docs so that it stands out of the main flow of text. ### Notes ```md :::note He had half a mind just to keep on `falling`. ::: ``` :::note He had half a mind just to keep on `falling`. ::: ### Info ```md :::info His face froze for a second or two and then began to do that terribly slow crashing `trick` that Arctic ice floes do so spectacularly in the spring. ::: ``` :::info His face froze for a second or two and then began to do that terribly slow crashing `trick` that Arctic ice floes do so spectacularly in the spring. ::: ### Tip ```md :::tip Her remark would have commanded greater attention had it been generally realized that human beings were only the third most intelligent life form present on the planet Earth. ::: ``` :::tip Her remark would have commanded greater attention had it been generally realized that human beings were only the third most intelligent life form present on the planet Earth. ::: ### Success ```md :::success “I’m afraid you cannot leave,' said Zarniwoop, 'you are entwined in the Improbability Field. You cannot escape.' ::: ``` :::success “I’m afraid you cannot leave,' said Zarniwoop, 'you are entwined in the Improbability Field. You cannot escape.' ::: ### Warnings ```md :::warning He smiled the smile that Zaphod had wanted to hit and this time `Zaphod` hit it. ::: ``` :::warning He smiled the smile that Zaphod had wanted to hit and this time `Zaphod` hit it. ::: ### Danger ```md :::danger One of the troublesome circumstances was the Plural nature of this Galactic Sector, where the possible `continually` interfered with the probable. ::: ``` :::danger One of the troublesome circumstances was the Plural nature of this Galactic Sector, where the possible `continually` interfered with the probable. ::: --- ## Development # Developing with MultiQC MultiQC was built to be customisable and extensible. This section of the docs leads you through how to work with MultiQC development: build new modules to support output from new tools, and even write custom report templates and plugins that can do just about anything! --- ## Writing new modules # Writing New Modules ## Introduction Writing a new module can at first seem a daunting task. However, MultiQC has been written _(and refactored)_ to provide a lot of functionality as common functions. Provided that you are familiar with writing Python and you have a read through the guide below, you should be on your way in no time! If you have any problems, feel free to contact the author - details here: [@ewels](https://github.com/ewels) ## Philosophical concepts These points are important and worth understanding early on. Get this stuff right, and your pull-request is much more likely to be merged quickly! ### Don't add everything MultiQC was designed to _summarise_ tool outputs. An end-user should be able to visually scan the report and spot any outlier samples, then go to the underlying tool to look at those samples in more detail. MultiQC is _not_ designed to replicate every single metric from a tool. Doing so makes the report difficult to read and digest quickly for many samples. Module additions that add huge quantities of metrics to reports will be asked to slim down. ### No images MultiQC doesn't know how many samples it will need to handle for a report, and as such every module should work with anything from 1-1000 samples. With images, you can't have more than a couple before the report is unusable. Worse, the file size will bloat the HTML file and it will crash the browser surprisingly fast. It's not accessible and the data cannot be exported into `multiqc_data` for downstream use. Plots should be _recreated_ within MultiQC by parsing the raw data and generating dynamic plots instead. I almost never merge modules that include images into reports. If you really need images in your report, you can do this either via Custom Content or an unofficial plugin module. Feel free to discuss on the community forum if you think that your case is an exception. There have been one or two in the past. ### One at a time Please try to keep contributions as atomic as possible. In other words, one module = one pull request. Don't be afraid to break things up into separate pull-requests coming from different branches. Just mention this in the PR comment so that it's clear which order they need to be merged in. ### Avoid optimising too much When you are writing a module that generates many similar plots, or table columns, or sections, it can be tempting to write nice efficient code that avoids duplicating these efforts. This is problematic for two reasons: - It's bespoke to that module, so more difficult to maintain and comprehend - Almost every table column, section and plot should have significant customisation. Descriptions, colour schemes, help text and more. Heavily optimised code will often need a lot of refactoring to pack this in. It's usually better to copy and paste a bit in these cases. The code is then easier to understand and easier to customise. ### Colour matters The emphasis for MultiQC reports is to allow people to quickly scan and spot outlier samples. The core of this is data visualisation. Especially when creating tables, make sure that you think about the [colour scheme](../development/plots.md#table-colour-scales) for every single column. - Ensure that adjacent columns do not share the same colour scheme - Makes long tables easier to follow - Allows fast recognition of columns for regular users - Think about what the colours suggest - For example, if a large value is a _bad_ thing (eg. percent duplication), use a strong red colour for large values - If values are centred around a point (eg. `0`), use a diverging colour scheme. Values close to the centre will have a weak colour and those at _both_ ends of the distribution will be strongly coloured. - This allows rapid understanding without a lot of thought This usually comes up for tables, but you can also think about it for bar plots. ## Core modules / plugins New modules can either be written as part of MultiQC or in a stand-alone plugin. If your module is for a publicly available tool, please add it to the main program and contribute your code back when complete via a pull request. If your module is for something _very_ niche, which no-one else can use, you can write it as part of a custom plugin. The process is almost identical, though it keeps the code bases separate. For more information about this, see the docs about _MultiQC Plugins_ below. ## Strict mode validation MultiQC has been developed to be as forgiving as possible and will handle lots of invalid or ignored code. Even if a module raised an unexpected exception, MultiQC will log that error, and continue running. This is useful most of the time, but can be difficult when writing new MultiQC modules (especially during pull-request reviews). To help with this, you can run MultiQC with the `--strict` flag. It will give explicit warnings about anything that is not optimally configured, and will also make MultiQC exit early if a module crashed. For example: ```bash multiqc --strict test-data ``` Note that the automated MultiQC continuous integration testing runs in this mode, so you will need to pass all lint tests for those checks to pass. This is required for any pull-requests. You can alternatively enable the strict mode using an environment variable: ```bash export MULTIQC_STRICT=true ``` Or set it in the [config](../getting_started/config.md): ```yaml # In multiqc_config.yaml strict: True ``` ## Static code analysis MultiQC uses type hints and static code analysis with [mypy](http://mypy-lang.org/) to prevent bugs. Mypy is run on the entire codebase using a GitHub Actions job, however, you can run it locally to check your changes before pushing them. In order to do that, install MultiQC in the dev mode, which will bring `mypy` along with additional pluginsL ```bash pip install -e .[dev] ``` Then run the following command to check your module: ```bash mypy multiqc/modules/your_module ``` Fix any problems that mypy finds before submitting your pull request. For a more convenient development experience, you can consider installing a mypy plugin for your editor. Both [VS Code](https://github.com/microsoft/vscode-mypy) and [PyCharm](https://plugins.jetbrains.com/plugin/11086-mypy) have plugins that can highlight type errors in your code as you write it. ## Code formatting MultiQC code base is also checked for consistency and formatting. Everyone has their own preferences when it comes to writing any code, both in the methods used but also with simple things like whitespace and whether to use `"` or `'`. When reviewing code contributions in pull-requests, these variations in coding style introduce an additional mental overhead. Inconsistent code style across the package also makes it harder for newcomers to get into the code. Code formatting / linting tools are able to assess files in many different languages and check that a set of "soft" formatting rules are adhered to, to enforce code consistency. Better still, many of these tools can automatically change the formatting so that developers can write code in whatever style they prefer and defer this task to automation. Much like source control, gloves in a lab, and wearing a seatbelt, code formatters and code linting is an annoying inconvenience at first for most people which in time becomes an indispensable tool in the maintenance of high quality software. MultiQC uses a range of tools to check the code base. The main two code formatters are: - [Ruff](https://docs.astral.sh/ruff/) - Python Code - [Prettier](https://prettier.io/) - Everything else (almost) The easiest way to work with these is to install editor plugins that run the tools every time you save a file. For example, [Visual Studio Code](https://code.visualstudio.com/) has [built-in support for Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) and plugins for [Prettier](https://github.com/prettier/prettier-vscode). ## Other style considerations 1. We use modern Python 3, thus: - Always use f-strings (e.g. `f"{var}"`) over the legacy `"{var}".format()` calls. - Use double quotes for strings. - Built-in `dict` preserve order, thus most of the time you don't need to use `OrderedDict`. - Avoid unnecessary `__future__` imports. 2. Unless a Python file is located in the root `scripts` directory, it must NOT have shebang lines like `#!/usr/bin/env python`. ### Prek MultiQC uses [prek](https://github.com/j178/prek) to test your code when you open a pull-request. Prek is a faster, Rust-based drop-in replacement for pre-commit. It's recommended that you install it yourself in your MultiQC clone directory: ```bash pip install prek # install the tool prek install # set up prek in the MultiQC repository ``` This will then automatically run all code checks on the files you have edited when you create a commit. Prek cancels the commit if anything fails - sometimes it will have fixed files for you, in which case just add them and try to commit again. Sometimes you will need to read the logs and fix the problem manually. Automated continuous integration tests will run using GitHub Actions to check that all files pass the above tests. If any files do not, that test will fail giving a red ❌ next to the pull request. :::tip Make sure that your configuration is working properly and that you're not changing loads of files that you haven't worked with. Pull-requests will not be merged with such changes. ::: These tools should be relatively easy to install and run, and have integration with the majority of code editors. Once set up, they can run on save, and you'll never need to think about them again. ## Initial setup ### MultiQC file structure The source code for MultiQC is separated into different folders. Most of the files you won't have to touch - the relevant files that you will need to edit or create follow the structure below: ``` ├── docs ├── multiqc │   ├── modules │   |   └── │   │      ├── __init__.py │   │      ├── .py │   │      └── tests │   │         ├── __init__.py │   │         └── test_.py │   └── search_patterns.yaml │   └── config_defaults.yaml └── pyproject.toml ``` These files are described in more detail below. ### Submodule MultiQC modules are Python submodules - as such, they need their own directory in `multiqc/` with an `__init__.py` file. The directory should share its name with the module. To follow common practice, the module code itself usually then goes in a separate python file (also with the same name, i.e. `multiqc/bismark/bismark.py`) which is then imported by the `__init__.py` file with: ```python from .mymodule import MultiqcModule __all__ = ["MultiqcModule"] ``` ### Entry points Once your submodule files are in place, you need to tell MultiQC that they are available as an analysis module. This is done within `pyproject.toml` using [entry points](https://setuptools.pypa.io/en/latest/userguide/entry_point.html). In `pyproject.toml` you will see some code that looks like this: ```toml [project.entry-points."multiqc.modules.v1"] mymodule = "multiqc.modules.mymodule:MultiqcModule" ``` Copy one of the existing module lines and change it to use your module name. The order is irrelevant, so stick to alphabetical if in doubt. Once this is done, you will need to update your installation of MultiQC: ```bash pip install -e . ``` ### MultiQC config So that MultiQC knows what order modules should be run in, you need to add your module to the core config file. In `multiqc/config_defaults.yaml` you should see a list variable called `module_order`. This contains the name of modules in order of precedence. Add your module here in an appropriate position. ### Tests Tests are written for [pytest](https://docs.pytest.org/), and placed in the `tests/` subdirectory within the module directory. MultiQC has a [blanket test](https://github.com/MultiQC/MultiQC/blob/main/tests/test_modules_run.py) that just checks that each module didn't crash when being run on the corresponding data in [test-data](https://github.com/MultiQC/test-data), and added _something_ into the report. However, users are encouraged to write more comprehensive tests that take the specific module logic into account. For some examples, consider checking: - the [samtools flagstat](https://github.com/MultiQC/MultiQC/blob/main/multiqc/modules/samtools/tests/test_flagstat.py) test that verifies some logic in the `flagstat` submodule of the `samtools` module; - the [picard tools](https://github.com/MultiQC/MultiQC/blob/main/multiqc/modules/picard/tests/test_picard.py) test that checks that every submodule for each Picard tool worked correctly. ### MultiqcModule Class If you've copied one of the other entry point statements, it will have ended in `:MultiqcModule` - this tells MultiQC to try to execute a class or function called `MultiqcModule`. To use the helper functions bundled with MultiQC, you should extend this class from `multiqc.modules.base_module.BaseMultiqcModule` in your module code file (i.e. `multiqc/modname/modname.py`). This will give you access to a number of functions on the `self` namespace. For example: ```python from multiqc.base_module import BaseMultiqcModule class MultiqcModule(BaseMultiqcModule): def __init__(self): super().__init__( name="My Module", anchor="mymodule", href="https://www.awesome_bioinfo.com/mymodule", info="Example analysis module used for writing documentation.", doi=["01.2345/journal/abc123", "01.2345/journal/abc124"], ) ``` The `__init__` variables are used to create the header, URL link, analysis module credits and description in the report. ### Markdown support in `info` The `info` parameter supports rich markdown formatting. For example: `````python super().__init__( name="My Advanced Module", anchor="myadvancedmodule", href="https://www.awesome_bioinfo.com/myadvancedmodule", info="This module performs **quality assessment** of sequencing data.\n\n" "Features:\n" "- Quality score distribution\n" "- Read length analysis\n" "- *Fast* processing\n\n" "See the [documentation](https://www.awesome_bioinfo.com/docs) for more details.", doi="01.2345/journal/abc123", ) The available arguments when initialising a module as follows: - `name` - Name of your module - `anchor` - A HTML-safe anchor that will be used after the `#` in the URL - `href` - Link(s) to the homepage for the tool - `info` - Very short description text about the tool. Supports markdown formatting when `autoformat=True` and `autoformat_type="markdown"` (default). Can include **bold** text, *italic* text, [links](https://example.com), lists, and other markdown features. - `doi` - One or more publication DOIs (can be a string or a list) - `comment` - Additional comment text for module. Usually user-supplied in a config. - `extra` - Optional additional description. Will appear in the documentation and in the report, but not on the list of modules on the website. - `target` - Name of the module in the description (default: `name`) - `autoformat` - (default: `True`) - `autoformat_type` - (default: `markdown`) :::tip **Backward Compatibility**: Existing modules with plain text `info` parameters will continue to work as before. The markdown processing only applies when `autoformat=True` (default) and `autoformat_type="markdown"` (default). ::: Ok, that should be it! The `__init__()` function will now be executed every time MultiQC runs. Try adding a `print("Hello World!")` statement and see if it appears in the MultiQC logs at the appropriate time... ### Documentation If there are any specific considerations for the users before running the module, add them into the module docstring, e.g.: ````py from multiqc.base_module import BaseMultiqcModule class MultiqcModule(BaseMultiqcModule): """ The tool provides multiple subcommands, and the MultiQC module currently only supports `command1`. The tool outputs useful information into stdout, and you need to capture it to a file for the module to recognize. To pipe stderr into a file, run the tool as follows: ``` mymod command1 2> sample1.log ``` Note the that the sample name is parsed from the filename by default, in this case, the reported name will be "sample1". #### Configuration By default, the tool uses the following thresholds to report something: 1, 2, 3. To override them, use the following config: ```yaml mymod: thresholds: - 1 - 2 - 3 ``` Version 1.1.0 of the tool is tested. """ def __init__(self): super().__init__( ... ) ... ````` The consideration can be: - The list of supported subcommands of a toolkit; - The list of supported use cases and sets of parameters; - Versions of the tools that are supported or tested; - Required outputs file naming and redirection; - The way the sample name is found in the logs, if not obvious; - Configuration parameters that the tool can read from the user config; - Any post-processing needed to be done by the user before running the module; - Performance considerations; - Conflicts with other MultiQC modules. ### Logging Last thing - MultiQC modules have a standardised way of producing output, so you shouldn't really use `print()` statements for your `Hello World` in your module code ;). Instead, use the `logger` module as follows: ```python log = logging.getLogger(__name__) log.info("Hello World!") ``` Log messages can come in a range of formats: - `log.debug` - These only show if MultiQC is run in `-v`/`--verbose` mode - `log.info` - For more important status updates - `log.warning` - Alert user about problems that don't halt execution - `log.error` and `log.critical` - Not often used, these are for show-stopping problems ### Pull-request tags Pull-request labels/tags are essential for auto-generation of the release changelog, so consider adding them to your PR. - When opening a pull-request for a new module, please add the `module: new` label. - If the pull-request only fixes an existing module, please add the `bug: module` label. - If it's an enhancement of an existing module, add the `module: enhancement` label. - If the PR fixes the core codebase, add the `bug: core`. - For other options, consider, like `core: frontend`, `core: refactoring`, `core: infrastructure` (e.g. CI workflows and tests), `documentation`. :::tip Please do not add anything to the `CHANGELOG.md` file! This is now handled by our friendly MultiQC bot 🤖 For more information about how it works, see the [contributing docs](../development/contributing.md#changelog). ::: ## Step 1 - Find log files The first thing that your module will need to do is to find analysis log files. You can do this by searching for a filename fragment, or a string within the file. It's possible to search for both (a match on either will return the file) and also to have multiple strings possible. First, add your default patterns to `multiqc/search_patterns.yaml` Each search has a yaml key, with one or more search criteria. The yaml key must begin with the name of your module. If you have multiple search patterns for a single module, follow the module name with a forward slash and then any string. For example, see the `fastqc` module search patterns: ```yaml fastqc/data: fn: "fastqc_data.txt" fastqc/zip: fn: "_fastqc.zip" ``` The following search criteria sub-keys can then be used: - `fn` - A glob filename pattern, used with the Python [`fnmatch`](https://docs.python.org/2/library/fnmatch.html) function - `fn_re` - A regex filename pattern - `contents` - A string to match within the file contents (checked line by line) - `contents_re` - A regex to match within the file contents (checked line by line) - NB: Regex must match entire line (add `.*` to start and end of pattern to avoid this) - `exclude_fn` - A glob filename pattern which will exclude a file if matched - `exclude_fn_re` - A regex filename pattern which will exclude a file if matched - `exclude_contents` - A string which will exclude the file if matched within the file contents (checked line by line) - `exclude_contents_re` - A regex which will exclude the file if matched within the file contents (checked line by line) - `num_lines` - The number of lines to search through for the `contents` string. Defaults to 1000 (configurable via `filesearch_lines_limit`). Set or a low number like 10 if it's e.g. a header of a TSV file. Do not set it to 1 (!!!) because there is a chance that other versions of this file can have extra-headers. - `shared` - By default, once a file has been assigned to a module it is not searched again. Specify `shared: true` when your file is likely to be shared between multiple tools, or has a too generic search pattern. - `max_filesize` - Files larger than the `log_filesize_limit` config key (default: 50MB) are skipped. If you know your files will be smaller than this and need to search by contents, you can specify this value (in bytes) to skip any files smaller than this limit. :::tip Please try to use `num_lines` and `max_filesize` where possible as they will speed up MultiQC execution time. ::: :::warning Please do not set `num_lines` to anything over 1000, as this will significantly slow down the file search for all users. If you do need to search more lines to detect a string, please combine it with a `fn` pattern to limit which files are loaded _(as done with AfterQC)_. ::: For example, two typical modules could specify search patterns as follows: ```yaml mymodule: fn: "_myprogram.txt" myother_module: contents: "This is myprogram v1.3" ``` You can also supply a list of different patterns for a single log file type if needed. If any of the patterns are matched, the file will be returned: ```yaml mymodule: - fn: "mylog.txt" - fn: "different_fn.out" ``` You can use _AND_ logic by specifying keys within a single list item. For example: ```yaml mymodule: fn: "mylog.txt" contents: "mystring" myother_module: - fn: "different_fn.out" contents: "This is myprogram v1.3" - fn: "another.txt" contents: ["What are these files anyway?", "End of program"] contents_re: '^Metric: \d+\.\d+' ``` For `mymodule`, a file must have the filename `mylog.txt` _and_ contain the string `mystring`. `myother_module` will match `different_fn.out` with the contents `This is myprogram v1.3`, _or_ `another.txt` containing ALL of the lines `What are these files anyway?`, `End of program"`, and `^Metric: \d+\.\d+`. You can match subsets of files by using `exclude_` keys as follows: ```yaml mymodule: fn: "*.myprog.txt" exclude_fn: "not_these_*" myother_module: fn: "mylog.txt" exclude_contents: - "trimmed" - "sorted" ``` Note that the `exclude_` patterns can have either a single value or a list of values. They are always considered using OR logic - any matches will reject the file. Remember that users can overwrite these defaults in their own config files. This is helpful as people have weird and wonderful processing pipelines with their own conventions. Once your strings are added, you can find files in your module with the base function `self.find_log_files()`, using the key you set in the YAML: ```python self.find_log_files("mymodule") ``` This function yields a dictionary with various information about each matching file. The `f` key contains the contents of the matching file: ```python # Find all files for mymod for f in self.find_log_files("mymodule"): print(f["f"]) # File contents print(f["s_name"]) # Sample name (from cleaned filename) print(f["fn"]) # Filename print(f["root"]) # Directory file was in ``` If `filehandles=True` is specified, the `f` key contains a file handle instead: ```python for f in self.find_log_files("mymodule", filehandles=True): # f['f'] is now a filehandle instead of contents for line in f["f"]: print(line) ``` This is good if the file is large, as Python doesn't read the entire file into memory in one go. ## Step 2 - Parse data from the input files What most MultiQC modules do once they have found matching analysis files is to pass the matched file contents to another function, responsible for parsing the data from the file. How this parsing is done will depend on the format of the log file and the type of data being read. See below for a basic example, based loosely on the preseq module: ```python from multiqc.base_module import BaseMultiqcModule from typing import Dict, Union class MultiqcModule(BaseMultiqcModule): def __init__(self): ... data_by_sample: Dict[str, Dict[str, Union[float, int]]] = dict() for f in self.find_log_files("mymod"): s_name = f["s_name"] if s_name in data_by_sample: log.debug(f"Duplicate sample name found! Overwriting: {s_name}") data_by_sample[s_name] = parse_file(f["f"]) def parse_file(f) -> Dict[str, Union[float, int]]: data = {} for line in f.splitlines(): s = line.strip().split() data[s[0]] = float(s[1]) return data ``` ### Filtering by parsed sample names MultiQC users can use the `--ignore-samples` flag to skip sample names that match specific patterns. As sample names are generated in a different way by every module, this filter has to be applied after log parsing. There is a core function to do this task - assuming that your data is in a dictionary with the first key as sample name, pass it through the `self.ignore_samples` function as follows: ```python data_by_sample = ... data_by_sample = self.ignore_samples(data_by_sample) ``` This will remove any dictionary keys where the sample name matches a user pattern. If your data structure is not in the `sample_name: data` format then you can check each sample name individually using the `self.is_ignore_sample()` function: ```python if self.is_ignore_sample(f["s_name"]): print("We will not use this sample!") ``` Note that this function should be used _after_ cleaning the sample name with `self.clean_s_name()`. ### No files found If your module cannot find any matching files, it needs to raise an exception of type `ModuleNoSamplesFound`. This tells the core MultiQC program that no modules were found. For example: ```python from multiqc.base_module import ModuleNoSamplesFound if len(data_by_sample) == 0: raise ModuleNoSamplesFound ``` Note that this has to be raised as early as possible, so that it halts the module progress. For example, if no logs are found then the module should not create any files or try to do any computation. ### Custom sample names Typically, sample names are taken from cleaned log filenames (the default `f['s_name']` value returned). However, if the underlying tool records the sample name in the logs somewhere, it's better to use that instead. Alternatively, it could also record the name of the input file somewhere (e.g. adapter cleaning tools typically save the input FASTQ file name in the log), in which case it's better to clean the sample name from the input file name. For that, you should use the `self.clean_s_name()` method, as this will prepend the directory name if requested on the command line: ```python for f in self.find_log_files("mymodule"): input_fname, data = parse_file(f) s_name = self.clean_s_name(input_fname, f) ... ``` This function has already been applied to the contents of `f['s_name']`, so it is only required when using something different for the sample identifier. :::tip `self.clean_s_name()` **must** be used on sample names parsed from the file contents. Without it, features such as prepending directories (`--dirs`) will not work. ::: The second argument should be the dictionary returned by the `self.find_log_files()` function. The root path is used for `--dirs` and the search pattern key is used for fine-grained configuration of the config option `use_filename_as_sample_name`. If you are using non-standard values for the logfile root, filename or search pattern key, these can be specified. The function def looks like this: ```python def clean_s_name(self, s_name, f, root=None): ``` A typical example is when the sample name is the log file directory. In this case, the root should be the dirname of that directory. This is non-standard, and would be specified as follows: ```python s_name = self.clean_s_name(f["root"], f, root=os.path.dirname(f["root"])) ``` ### Identical sample names If modules find samples with identical names, then the previous sample is overwritten. It's good to print a log statement when this happens, for debugging. However, most of the time it makes sense - programs often create log files _and_ print to `stdout` for example. ```python if f["s_name"] in data_by_sample: log.debug(f"Duplicate sample name found! Overwriting: {f['s_name']}") ``` ### Printing to the sources file Finally, once you've found your file we want to add this information to the `multiqc_sources.txt` file in the MultiQC report data directory. This lists every sample name and the file from which this data came from. This is especially useful if sample names are being overwritten as it lists the source used. This code is typically written immediately after the above warning. If you've used the `self.find_log_files` function, writing to the sources file is as simple as passing the log file variable to the `self.add_data_source` function: ```python for f in self.find_log_files("mymodule"): self.add_data_source(f) ``` If you have different files for different sections of the module, or are customising the sample name, you can tweak the fields. The default arguments are as shown: ```python self.add_data_source(f=None, s_name=None, source=None, module=None, section=None) ``` ### Saving version information Software version information may be present in the log files of some tools. The version number can be included in the report by passing it to the method `self.add_software_version`. Let's use this `samtools stats` log below as an example. ```bash # This file was produced by samtools stats (1.3+htslib-1.3) and can be plotted using plot-bamstats # This file contains statistics for all reads. # The command line was: stats /home/lp113/bcbio-nextgen/tests/test_automated_output/align/Test1/Test1.sorted.bam # CHK, Checksum [2]Read Names [3]Sequences [4]Qualities # CHK, CRC32 of reads which passed filtering followed by addition (32bit overflow) CHK 560674ab 1165a6ca 7b309ac6 # Summary Numbers. Use `grep ^SN | cut -f 2-` to extract this part. SN raw total sequences: 101 ... ``` The version number here (`1.3`) can be extracted using a regular expression (regex). We then pass this to the `self.add_software_version()` function. Note that we pass the sample name (`f["s_name"]` in this case) so that we don't add versions for samples that are later ignored. ```python for line in f.splitlines(): version = re.search(r"# This file was produced by samtools stats \(([\d\.]+)", line) if version is not None: self.add_software_version(version.group(1), sample=f["s_name"]) # ..rest of file parsing ``` The version number will now appear after the module header in the report as well as in the section _Software Versions_ in the end of the report. :::tip For tools that don't output software versions in their logs these can instead be provided in a separate YAML file. See [Customising Reports](../reports/customisation.md#listing-software-versions) for details. ::: In some cases, a log may include multiple version numbers for a single tool. In the example provided, the version of htslib is shown alongside the previously extracted samtools version. This information is valuable and should be incorporated into the report. To achieve this, we need to extract the new version string and provide it to the `self.add_software_version()` function. Include the relevant software name (in this case, `htslib`) as well. This will ensure that the htslib version is listed separately from the main module's software version. Example: ```python for line in f.splitlines(): version = re.search(r"# This file was produced by samtools stats \(([\d\.]+)", line) if version is not None: self.add_software_version(version.group(1), sample=f["s_name"]) htslib_version = re.search(r"\+htslib-([\d\.]+)", line) if htslib_version is not None: self.add_software_version(htslib_version.group(1), sample=f["s_name"], software_name="htslib") ... # rest of file parsing ``` Even if the logs does not contain any version information, you should still add a superfluous `self.add_software_version()` call to the module. This will help maintainers to check if new modules or submodules parse any version information that might exist. The call should also include a note that it is a dummy call. Example: ```python for f in self.find_log_files("mymodule/submodule"): sample = f["s_name"] data_by_sample[sample] = parse_file(f) # Superfluous function call to confirm that it is used in this module # Replace None with actual version if it is available self.add_software_version(None, sample) ``` ## Step 3 - Adding to the general statistics table Now that you have your parsed data, you can start inserting it into the MultiQC report. At the top of every report is the 'General Statistics' table. This contains metrics from all modules, allowing cross-module comparison. Do not add a lot of columns to the General Statistics table. There should be 1-2 columns visible-by-default columns per module, plus there can be a bunch of more hidden columns. There is a helper function to add your data to this table. It can take a lot of configuration options, but most have sensible defaults. At it's simplest, it works as follows: ```python data_by_sample: Dict[str, Dict[str, float]] = { "sample_1": { "first_col": 91.4, "second_col": 78.2, }, "sample_2": { "first_col": 138.3, "second_col": 66.3, }, } self.general_stats_addcols(data_by_sample) ``` To give more informative table headers and configure things like data scales and colour schemes, you can supply an extra dict: ```python from multiqc.plots.table_object import ColumnMeta headers = { "first_col": ColumnMeta( title="First", description="My First Column", scale="RdYlGn-rev", ), "second_col": ColumnMeta( title="Second", description="My Second Column", max=100, min=0, scale="Blues", suffix="%", ) } self.general_stats_addcols(data_by_sample, headers) ``` Here are all options for headers, with defaults: ```python headers["name"] = TableColumn( namespace="", # Module name. Auto-generated for core modules in General Statistics. title="[ dict key ]", # Short title, table column title description="[ dict key ]", # Longer description, goes in mouse hover text max=None, # Minimum value in range, for bar / colour coding min=None, # Maximum value in range, for bar / colour coding scale="GnBu", # Colour scale for colour coding. Set to False to disable. suffix=None, # Suffix for value (eg. '%') format="{:,.1f}", # Output format() string. Can also be a lambda function. shared_key=None, # See below for description modify=None, # Lambda function to modify values hidden=False, # Set to True to hide the column on page load placement=1000.0, # Alter the default ordering of columns in the table ) ``` - `namespace` - This prepends the column title in the mouse hover: _Namespace: Title_. - The 'Configure Columns' modal displays this under the 'Group' column. - It's automatically generated for core modules in the General Statistics table, though this can be overwritten (useful for example with custom-content). - `scale` - Colour scales are the names of ColorBrewer palettes. See below for available scales. - Add `-rev` to the name of a colour scale to reverse it - Set to `False` to disable colouring and background bars - `shared_key` - Any string can be specified here, if other columns are found that share the same key, a consistent colour scheme and data scale will be used in the table. Typically this is set to things like `read_count`, so that the read count in a sample can be seen varying across analysis modules. - `modify` - A python `lambda` function to change the data in some way when it is inserted into the table. - `format` - A format string or a python `lambda` function to format the data to display on screen. - `hidden` - Setting this to `True` will hide the column when the report loads. It can then be shown through the _Configure Columns_ modal in the report. This can be useful when data could be sometimes useful. For example, some modules show "percentage aligned" on page load but hide "number of reads aligned". - `placement` - If you feel that the results from your module should appear on the left side of the table set this value less than 1000. Or to move the column right, set it greater than 1000. This value can be any float. The typical use for the `modify` string is to divide large numbers such as read counts, to make them easier to interpret. If handling read counts, there are three config variables that should be used to allow users to change the multiplier for read counts: `read_count_multiplier`, `read_count_prefix` and `read_count_desc`. For example: ```python from multiqc.plots.table_object import TableConfig pconfig = TableConfig( title="Reads", description=f"Number of reads ({config.read_count_desc})", modify=lambda x: x * config.read_count_multiplier, suffix=f" {config.read_count_prefix}", ... ) ``` Similar config options apply for base pairs: `base_count_multiplier`, `base_count_prefix` and `base_count_desc`. And for the read count of long reads: `long_read_count_multiplier`, `long_read_count_prefix` and `long_read_count_desc`. Note that adding e.g. `"shared_key": "read_count"` will automatically add corresponding `description`, `modify`, and `suffix` into the column, so in most cases the following will be sufficient: ```python pconfig = TableConfig( title="Reads", shared_key="read_count", ... ) ... pconfig2 = TableConfig( title="Base pairs", shared_key="base_count", ... ) ``` A third parameter can be passed to this function, `namespace`. This is usually not needed - MultiQC automatically takes the name of the module that is calling the function and uses this. However, sometimes it can be useful to overwrite this. ### Table colour scales Colour scales are taken from [ColorBrewer2](http://colorbrewer2.org/). Colour scales can be reversed by adding the suffix `-rev` to the name. For example, `RdYlGn-rev`. The following scales are available: ![color brewer](../../../docs/images/cbrewer_scales.png) For categorical metrics that can take a value from a predefined set, use one of the categorical color scales: Set2, Accent, Set1, Set3, Dark2, Paired, Pastel2, Pastel1. For numerical metrics, consider one the "sequential" color scales from the table above. ### Grouping samples If you have a set of samples that should be grouped together in the report using the [sample grouping configuration option](../reports/customisation.md#sample-grouping), you can include the `group_samples_config` parameter to the `self.general_stats_addcols` function. For example, FastQC uses the following configuration: ```python self.general_stats_addcols( ..., group_samples_config=SampleGroupingConfig( cols_to_sum=[ColumnKey("total_sequences")], cols_to_weighted_average=[ (ColumnKey("percent_gc"), ColumnKey("total_sequences")), (ColumnKey("avg_sequence_length"), ColumnKey("total_sequences")), (ColumnKey("percent_duplicates"), ColumnKey("total_sequences")), (ColumnKey("median_sequence_length"), ColumnKey("total_sequences")), ], extra_functions=[_summarize_statues], ) ) ``` In this configuration, you can specify how to merge data for each column: - `cols_to_sum` - add up values for each sample in the group. - `cols_to_average` - take an average of all samples. - `cols_to_weighted_average` - take a weighed average, specifying the weight column in the the second tuple parameter. - `extra_functions` - list of functions to call to add extra data to the merged row - `explicit_groups` - opt-in dict of `{group_display_name: [sample_names]}` that lets a module supply its own ground-truth groups instead of relying on the user-supplied `table_sample_merge` name patterns. #### Extra functions The `extra_functions` flag can be used when you need custom logic beyond summing or averaging numeric values. For example, FastQC uses it to recalculate the `percent_fails` value: ```python def _summarize_statues( merged_row: InputRow, group_s_names: List[Tuple[Optional[str], SampleName, SampleName]] ): # Add count of fail statuses _num_statuses = 0 _num_fails = 0 for _, _, original_sn in group_s_names: for st in self.fastqc_data[original_sn]["statuses"].values(): _num_statuses += 1 if st == "fail": _num_fails += 1 if _num_statuses > 0: merged_row.data[ColumnKey("percent_fails")] = (float(_num_fails) / float(_num_statuses)) * 100.0 ``` #### Explicit groups Use this when the tool output already tells you which samples are related. For example a tool whose log carries a stable pair / replicate identifier. When set, this short-circuits the name-pattern matcher: each `[sample_names]` list is collapsed into one group with the given display name. ```python # Build the groups from tool metadata during parse. explicit_groups: Dict[str, List[str]] = {} for s_name, data in data_by_sample.items(): group_id = data["sample_id"] # This will depend on your data structure explicit_groups.setdefault(group_id, []).append(s_name) self.general_stats_addcols( data_by_sample, headers, group_samples_config = SampleGroupingConfig( explicit_groups = explicit_groups, cols_to_sum = [ColumnKey("some_count_column")], cols_to_weighted_average = [ (ColumnKey("some_percent"), ColumnKey("some_count_column")) ], ), ) ``` Entries with a single member are ignored by the framework - they fall through and render as a normal ungrouped row with their original sample name. Modules that use this should expose a config flag so users can opt out and see per-sample rows. Auto-grouping is independent of `table_sample_merge`: if the user has _also_ configured name patterns, you can layer them on top of your auto-groups before passing: run each auto-group's display name through `self.groups_for_sample(...)` and bucket by the result. ## Step 4 - Writing data to a file In addition to printing data to the General Stats, MultiQC modules typically also write to text-files to allow people to easily use the data in downstream applications. This also gives the opportunity to output additional data that may not be appropriate for the General Statistics table. Again, there is a base class function to help you with this - just supply it with a dictionary and a filename: ```python data_by_sample = { "sample_1": { "first_col": 91.4, "second_col": "78.2%", }, "sample_2": { "first_col": 138.3, "second_col": "66.3%", }, } self.write_data_file(data_by_sample, "multiqc_mymodule") ``` Make sure to call `self.write_data_file` in the end of the module, because it may modify `data_by_sample` to be JSON-serializable. If your output has a lot of columns, you can supply the additional argument `sort_cols = True` to have the columns alphabetically sorted. This function will also pay attention to the default / command line supplied data format and behave accordingly. So the written file could be a tab-separated file (default), `JSON` or `YAML`. Note that any keys with more than 2 levels of nesting will be ignored when being written to tab-separated files. ## Step 5 - Create report sections Great! It's time to start creating sections of the report with more information. To do this, use the `self.add_section()` helper function. This supports the following arguments: - `name`: Name of the section, used for the title - `anchor`: The URL anchor - must be unique, used when clicking the name in the side-nav - `description`: A very short descriptive text to go above the plot (markdown). - `comment`: A comment to add under the description. Big and blue text, mostly for users to customise the report (markdown). - `helptext`: Longer help text explaining what users should look for (markdown). - `plot`: Results from one of the MultiQC plotting functions - `content`: Any custom HTML - `autoformat`: Default `True`. Automatically format the `description`, `comment` and `helptext` strings. - `autoformat_type`: Default `markdown`. Autoformat text type. Currently only `markdown` supported. - `statuses`: Optional dictionary with keys `"pass"`, `"warn"`, and `"fail"`, each containing lists of sample names. When provided, adds an interactive status progress bar to the section header showing pass/warn/fail counts. - `alerts`: Optional alert box, or list of alert boxes, shown below the description. Alert messages support markdown, Bootstrap alert levels, and optional affected sample lists. ### Section status bars If your tool generates pass/warn/fail metrics for different QC checks, you can add interactive status bars to section headers using the `statuses` parameter in `add_section()`. The status bars will automatically: - Show sample lists on hover (after 0.5s delay) - Pin the popover on click - Provide "Highlight" and "Filter" buttons for integration with the MultiQC toolbox - Display colored progress bars showing the proportion of samples in each status category For example: ```python # Collect sample names by status for this section status_data = { "pass": ["sample1", "sample2", "sample3"], "warn": ["sample4"], "fail": ["sample5"] } # Add section with status bar self.add_section( name="Quality Check", anchor="quality_check", description="Results from quality control analysis", plot=my_plot, statuses=status_data ) ``` #### Status bar user configuration Users can control status bar visibility globally or per-module using the `section_status_checks` config: ```yaml section_status_checks: fastqc: false # Disable all FastQC status bars mymodule: section1: false # Disable specific section status bar ``` By default, all status bars are enabled. Configuration can be set at the module level (boolean) or per-section level (nested dictionary). ### Section alerts Use the `alerts` parameter when a section needs to call out an important note, especially if samples were hidden from a plot or table. This keeps warnings separate from the section description and lets MultiQC render the Bootstrap alert markup consistently. Each alert can be a plain markdown string, a dictionary, a `SectionAlert`, or a list of these. Dictionary and `SectionAlert` values support: - `message`: Alert text, formatted as markdown by default - `level`: Bootstrap alert style, default `"info"`; must be one of `"primary"`, `"secondary"`, `"success"`, `"danger"`, `"warning"`, `"info"`, `"light"`, or `"dark"` - `affected_samples`: Optional list of sample names, rendered in an expandable list Alerts with an empty `message` are ignored. After `add_section()` runs, the `SectionAlert.message` value stored on the section is the rendered HTML string, matching how section descriptions are stored. For example: ```python from multiqc.types import SectionAlert self.add_section( name="Adapter Content", anchor="adapter_content", description="Adapter content per cycle.", plot=adapter_plot, alerts=SectionAlert( message="**3 samples** with negligible adapter content hidden from this plot.", level="warning", affected_samples=["sample1", "sample2", "sample3"], ), ) ``` Sections with alerts still render even when there is no plot or custom content. Use `alerts` instead of appending raw `` HTML to `description` or `content`. ![section alerts](../../../docs/images/section_alerts.png) For example: ```python from multiqc.plots import linegraph, bargraph from multiqc.plots.linegraph import LinePlotConfig from multiqc.plots.bargraph import BarPlotConfig self.add_section( name="Second Module Section", anchor="mymodule-second", plot=linegraph.plot(data_by_sample2, pconfig=LinePlotConfig( id="mymodule-second", title="My Module: Duplication Rate" )), ) self.add_section( name="First Module Section", anchor="mymodule-first", description="My amazing module output, from the first section", helptext=""" If you're not sure _how_ to interpret the data, we can help! Most modules use multi-line strings for these text blocks, with triple quotation marks. * Markdown * Lists * Are * `Great` """, plot = bargraph.plot(data_by_sample, pconfig=BarPlotConfig( id="mymodule-first", title="My Module: Read Counts" )) ) self.add_section( content="Some custom HTML." ) ``` If a module has more than one section, these will automatically be labelled and linked in the left sidebar navigation (unless `name` is not specified). ## Step 6 - Plot some data Ok, you have some data, now the fun bit - visualising it! Each of the plot types is described in the _Plotting Functions_ section of the docs. ## Appendices ### User configuration Instead of hard-coding the defaults, it's a great idea to allow users to configure the behaviour of MultiQC module code. It's pretty easy to use the built-in MultiQC configuration settings to do this, so that users can set up their config as described in the [Configuration docs](../getting_started/config.md). To do this, just assume that your configuration variables are available in the MultiQC `config` module and have sensible defaults. For example: ```python from multiqc import config mymod_config = getattr(config, 'mymod', {}) my_custom_config_var = mymod_config.get('my_custom_config_var', 5) ``` You now have a variable `my_custom_config_var` with a default value of 5, but that can be configured by a user as follows: ```yaml mymod: my_custom_config_var: 200 ``` Please be sure to use a unique top-level config name to avoid clashes - prefixing with your module name is a good idea as in the example above. Keep all module config options under the same top-level name for clarity. Finally, don't forget to document the usage of your module-specific configuration in the `MultiqcModule` class docstring, so that people know how to use it. ### Profiling Performance It's important that MultiQC runs quickly and efficiently, especially on big projects with large numbers of samples. The recommended method to check this is by using `cProfile` to profile the code execution. To do this, first find out where your copy of MultiQC is located: ```sh $ which multiqc /Users/you/anaconda/envs/myenv/bin/multiqc ``` Then run MultiQC with this path and the `cProfile` module as follows (the flags at the end can be any regular MultiQC flags): ```bash python -m cProfile -o multiqc_profile.prof /Users/you/anaconda/envs/myenv/bin/multiqc -f . ``` You can create a `.bashrc` alias to make this easier to run: ```bash alias profile_multiqc='python -m cProfile -o multiqc_profile.prof /Users/you/anaconda/envs/myenv/bin/multiqc ' profile_multiqc -f . ``` MultiQC should run as normal, but produce the additional binary file `multiqc_profile.prof`. This can then be visualised with software such as [SnakeViz](https://jiffyclub.github.io/snakeviz/). To install SnakeViz and visualise the results, do the following: ```bash pip install snakeviz snakeviz multiqc_profile.prof ``` A web page should open where you can explore the execution times of different nested functions. It's a good idea to run MultiQC with a comparable number of results from other tools (eg. FastQC) to have a reference to compare against for how long the code should take to run. ### Adding Custom CSS / Javascript If you would like module-specific CSS and / or JavaScript added to the template, just add to the `self.css` and `self.js` dictionaries that come with the `BaseMultiqcModule` class. The key should be the filename that you want your file to have in the generated report folder _(this is ignored in the default template, which includes the content file directly in the HTML)_. The dictionary value should be the path to the desired file. For example, see how it's done in the FastQC module: ```python self.css = { "assets/css/multiqc_fastqc.css": os.path.join(os.path.dirname(__file__), "assets", "css", "multiqc_fastqc.css") } self.js = { "assets/js/multiqc_fastqc.js": os.path.join(os.path.dirname(__file__), "assets", "js", "multiqc_fastqc.js") } ``` ## Addendum - example module Below is an example of a good-quality module written for a made-up tool Qualalyser: ### File system structure: ``` ├── multiqc │   ├── modules │   |   └── qualalyser │   │      ├── __init__.py │   │      ├── qualalyser.py │   │      └── tests │   │         ├── __init__.py │   │         └── test_qualalyser.py │   └── search_patterns.yaml └── pyproject.toml ``` ### `__init__.py` ```python from .qualalyser import MultiqcModule __all__ = ["MultiqcModule"] ``` ### `qualalyser.py` ```python from collections import defaultdict from copy import deepcopy from typing import Callable, Dict, List, Any, Tuple, Union from multiqc.base_module import BaseMultiqcModule, ModuleNoSamplesFound from multiqc.plots import table, bargraph from multiqc.plots.bargraph import BarPlotConfig from multiqc.plots.table_object import TableConfig, ColumnMeta from multiqc.utils import mqc_colour from multiqc import config log = logging.getLogger(__name__) class MultiqcModule(BaseMultiqcModule): """ Qualalyser provides multiple subcommands, and the MultiQC module currently only supports `quality`. Qualalyser outputs useful information into stdout, and you need to capture it to a file for the module to recognize. To pipe stderr into a file, run the tool as follows: qualalyser quality 2> sample1.log Note the that the sample name is parsed from the filename by default, in this case, the reported name will be "sample1". #### Configuration By default, Qualalyser uses the following quality threshold: 10. To override it, use the following config: qualalyser: min_quality: 10 Version 1.1.0 of Qualalyser is tested. """ def __init__(self): super().__init__( name="Qualalyser", anchor="qualalyser", href="https://github.com/bioinformatics-centre/qualalyser/", info="Reports read quality and length from sequencing data", doi="10.21105/joss.02991", ) # Find and load any Qualalyser reports data_by_sample: Dict[str, Dict[str, float]] = {} for f in self.find_log_files("qualalyser/quality", filehandles=True): sample_data = parse_qualalyser_log(f) if sample_data: s_name = f['s_name'] if s_name in data_by_sample: log.debug(f"Duplicate sample name found! Overwriting: {s_name}") data_by_sample[s_name] = sample_data self.add_data_source(f) # Superfluous function call to confirm that it is used in this module # Replace None with actual version if it is available self.add_software_version(None) # Filter to strip out ignored sample names data_by_sample = self.ignore_samples(data_by_sample) if len(data_by_sample) == 0: raise ModuleNoSamplesFound log.info(f"Found {len(data_by_sample)} reports") # Add Qualalyser summary to the general stats table self.add_table(data_by_sample) # Quality distribution Plot self.reads_by_quality_plot(data_by_sample) # Read length distribution Plot self.reads_by_length_plot(data_by_sample) # Write parsed report data to a file self.write_data_file(data_by_sample, "multiqc_qualalyser") def add_table(self, data_by_sample: Dict[str, Dict[str, float]]) -> None: headers: Dict[str, Dict] = { "Number of reads": ColumnMeta( title="Reads", description="Number of reads", scale="Greens", shared_key="read_count", ), "Number of bases": ColumnMeta( title="Bases", description="Total bases sequenced", scale="Purples", shared_key="base_count", ), "N50 read length": ColumnMeta( title="Read N50", description="N50 read length", scale="Blues", suffix="bp", format="{:,.0f}", ), "Longest read": ColumnMeta( title="Longest Read", description="Longest read length", suffix="bp", scale="Oranges", format="{:,.0f}", ), "Mean read length": ColumnMeta( title="Mean Length", description="Mean read length", suffix="bp", scale="PuBuGn", ), "Median read length": ColumnMeta( title="Median Length", description="Median read length (bp)", scale="RdYlBu", format="{:,.0f}", ), "Mean read quality": ColumnMeta( title="Mean Qual", description="Mean read quality (Phred scale)", scale="PiYG", ), "Median read quality": ColumnMeta( title="Median Qual", description="Median read quality (Phred scale)", scale="Spectral", ), } self.add_section( name="Qualalyser Summary", anchor="qualalyser-summary", description="Statistics from Qualalyser reports", plot=table.plot( data_by_sample, headers, pconfig=TableConfig( id="qualalyser_table", title="Qualalyser Summary", ), ), ) # Add general stats table - hide all columns except for two general_stats_headers = deepcopy(headers) for h in general_stats_headers.values(): h["hidden"] = True general_stats_headers["Number of reads"]["hidden"] = False general_stats_headers["N50 read length"]["hidden"] = False # Add columns to the general stats table self.general_stats_addcols(data_by_sample, general_stats_headers) def reads_by_quality_plot(self, data_by_sample: Dict[str, Dict[str, float]]) -> None: barplot_data: Dict[str, Dict[str, float]] = defaultdict(dict) keys: List[str] = [] min_quality = getattr(config, "qualalyser", {}).get("min_quality", 10) for name, d in data_by_sample.items(): reads_by_q = {int(re.search(r"\d+", k).group(0)): v for k, v in d.items() if k.startswith("Reads > Q")} if not reads_by_q: continue thresholds = sorted(th for th in reads_by_q if th >= min_quality) if not thresholds: continue barplot_data[name], keys = get_ranges_from_cumsum( data=reads_by_q, thresholds=thresholds, total=d["Number of reads"], formatter=lambda x: f"Q{x}" ) colours = mqc_colour.mqc_colour_scale("RdYlGn-rev", 0, len(keys)) cats = { k: {"name": f"Reads {k}", "color": colours.get_colour(idx, lighten=1)} for idx, k in enumerate(keys[::-1]) } # Plot self.add_section( name="Read quality", anchor="qualalyser_plot_quality", description="Read counts categorised by read quality (Phred score).", helptext=""" Sequencing machines assign each generated read a quality score using the [Phred scale](https://en.wikipedia.org/wiki/Phred_quality_score). The phred score represents the liklelyhood that a given read contains errors. High quality reads have a high score. """, plot=bargraph.plot( barplot_data, cats, pconfig=bargraph.BarPlotConfig( id="qualalyser_plot_quality_plot", title="Qualalyser: read qualities", ), ), ) def parse_qualalyser_log(f) -> Dict[str, float]: """Parse output from Qualalyser""" stats: Dict[str, float] = dict() # Parse the file content segment = None summary_lines = [] length_threshold_lines = [] quality_threshold_lines = [] for line in f["f"]: line = line.strip() if line.startswith("Qualalyser Read Summary"): segment = "summary" continue elif line.startswith("Read length thresholds"): segment = "length_thresholds" continue elif line.startswith("Read quality thresholds"): segment = "quality_thresholds" continue if segment == "summary": summary_lines.append(line) elif segment == "length_thresholds": length_threshold_lines.append(line) elif segment == "quality_thresholds": quality_threshold_lines.append(line) for line in summary_lines: if ":" in line: metric, value = line.split(":", 1) stats[metric.strip()] = float(value.strip()) return stats ``` ### `pyproject.toml` ```toml ... [project.entry-points."multiqc.modules.v1"] qualalyser = "multiqc.modules.qualalyser:MultiqcModule" ... ``` ### `search_patterns.yaml` ```yaml --- qualalyser/quality: fn: "*.log" contents: "Qualalyser Read Summary" num_lines: 10 ``` ### `config_defaults.yaml` ```yaml --- # Order that modules should appear in report. Try to list in order of analysis. module_order: ... - qualalyser ... ``` --- ## Plotting functions MultiQC plotting functions are held within `multiqc.plots` submodules. To use them, simply import the modules you want, e.g.: ```python from multiqc.plots import bargraph, linegraph ``` Once you've done that, you will have access to the corresponding plotting functions: ```python from multiqc.plots import bargraph, linegraph, scatter, table, violin, heatmap, box bargraph.plot(data=..., cats=..., pconfig=...) linegraph.plot(data=..., pconfig=...) scatter.plot(data=..., pconfig=...) table.plot(data=..., headers=..., pconfig=...) violin.plot(data=..., headers=..., pconfig=...) heatmap.plot(data=..., xcats=..., ycats=..., pconfig=...) box.plot(list_of_data_by_sample=..., pconfig=...) ``` These have been designed to work in a similar manner to each other - you pass a data structure to them, along with optional extras such as categories and configuration options, and they return a string of HTML to add to the report. You can add this to the module introduction or sections as described above. For example: ```python from multiqc.plots import bargraph from multiqc import BaseMultiqcModule class MultiqcModule(BaseMultiqcModule): def __init__(self): super().__init__(...) data = ... self.add_section( name="Module Section", anchor="mymod_section", description="This plot shows some really nice data.", helptext="This longer string (can be **markdown**) helps explain how to interpret the plot", plot=bargraph.plot(data, cats=..., pconfig=...) ) ``` ## Common options All plots should as a minimum have a config with an `id` and a `title`. MultiQC is written to work with sensible defaults, so won't complain if you don't supply these, but it's good practice for usability (the ID is used as a filename when exporting plots, and all plots should have a title when exported). Plot titles should use the format _Module name: Plot name_ (this is partly for ease of use within MegaQC and other downstream tools). ### Plotly themes MultiQC plots use Plotly for visualization. You can customize the appearance of all plots by setting a Plotly theme using the `plot_theme` configuration option. This option accepts any [registered Plotly theme](https://plotly.com/python/templates/#view-available-themes) name as a string. ```yaml plot_theme: "plotly_dark" ``` ## Bar graphs Simple data can be plotted in bar graphs. Many MultiQC modules make use of stacked bar graphs. Here, the `bargraph.plot()` function comes to the rescue. A basic example is as follows: ```python from multiqc.plots import bargraph data = { 'sample 1': { 'aligned': 23542, 'not_aligned': 343, }, 'sample 2': { 'not_aligned': 7328, 'aligned': 1275, } } html = bargraph.plot(data, pconfig=...) ``` To specify the order of categories in the plot, you can supply a list of dictionary keys. This can also be used to exclude a key from the plot. ```python from multiqc.plots import bargraph cats = ['aligned', 'not_aligned'] html = bargraph.plot(..., cats, pconfig=...) ``` If `cats` is given as a dict instead of a list, you can specify a nice name and a colour too: ```python cats = { "aligned": { 'name': 'Aligned Reads', 'color': '#8bbc21' }, "not_aligned": { 'name': 'Unaligned Reads', 'color': '#f7a35c' } } ``` Finally, a third variable should be supplied with configuration variables for the plot. The defaults are as follows: ```python config = { # Building the plot "id": "", # HTML ID used for the plot "cpswitch": True, # Show the 'Counts / Percentages' switch? "cpswitch_c_active": True, # Initial display with 'Counts' specified? False for percentages. "cpswitch_counts_label": "Counts", # Label for 'Counts' button "cpswitch_percent_label": "Percentages", # Label for 'Percentages' button "logswitch": False, # Show the 'Log10' switch? "logswitch_active": False, # Initial display with 'Log10' active? "logswitch_label": "Log10", # Label for 'Log10' button "hide_zero_cats": True, # Hide categories where data for all samples is 0 # Customising the plot "title": None, # Plot title - should be in format "Module Name: Plot Title" "ylab": None, # Y axis label "ymax": None, # Max bar size limit (default is calculated from data) "xsuffix": "%", # Suffix for the X-axis values and labels. Parsed from tt_label by default "tt_label": "{x}: {y:.2f}%", # Customise tooltip label, e.g. '{point.x} base pairs' "stacking": "relative", # Set to "group" to have category bars side by side "sort_samples": True, # Sort samples by name "tt_decimals": 0, # Number of decimal places to use in the tooltip number "tt_suffix": "", # Suffix to add after tooltip number "height": 500 # The default height of the plot, in pixels } ``` :::note The keys `id` and `title` should always be passed as a minimum. The `id` is used for the plot name when exporting. If left unset the Plot Export panel will call the filename `mqc_hcplot_gtucwirdzx.png` (with some other random string). Plots should always have titles, especially as they can stand by themselves when exported. The title should have the format `Modulename: Plot Name` ::: ### Switching datasets It's possible to have single plot with buttons to switch between different datasets. To do this, give a list of data objects to the `plot` function and specify the `data_labels` config option with the text to be used for the buttons: ```python from multiqc.plots import bargraph pconfig = { 'data_labels': ['Reads', 'Bases'] } data1 = ... data2 = ... html = bargraph.plot([data1, data2], pconfig=pconfig) ``` You can also customise any plot configuration per-dataset, for example, the y-axis label, min/max values, or title: ```python pconfig = { "data_labels": [ { "name": "Reads", # Button label "ylab": "Reads", # Y-axis label }, { "name": "Base Pairs", "ylab": "Base Pairs", "ymax": 100, "title": "Number of Base Pairs", # Plot title }, ] } ``` If supplying multiple datasets, you can also supply a list of category objects. Make sure that they are in the same order as the data. Categories should contain data keys, so if you're supplying a list of two datasets, you should supply a list of two sets of keys for the categories. MultiQC will try to guess categories from the data keys if categories are missing. For example, with two datasets supplied as above: ```python cats = [ ["aligned_reads", "unaligned_reads"], ["aligned_base_pairs", "unaligned_base_pairs"], ] ``` Or with additional customisation such as name and colour: ```python from multiqc.plots import bargraph cats = [ { "aligned_reads": {"name": "Aligned Reads", "color": "#8bbc21"}, "unaligned_reads": {"name": "Unaligned Reads", "color": "#f7a35c"}, }, { "aligned_base_pairs": {"name": "Aligned Base Pairs", "color": "#8bbc21"}, "unaligned_base_pairs": {"name": "Unaligned Base Pairs", "color": "#f7a35c"}, }, ] data = ... html = bargraph.plot([data, data], cats, pconfig=...) ``` Note that, as in this example, the plot data can be the same dictionary supplied twice. ### Grouped stacked bar charts Use `sample_groups` to create grouped stacked bar charts where bars are organized into visual groups on the y-axis. The config is a dict mapping group labels to lists of `[sample name, group ID]` pairs: - **Group label** (dict key): Displayed on the y-axis - **Sample name**: The key in the data dict identifying this sample - **Group ID**: Determines the visual "lane" within each group. Samples with the same ID are aligned vertically across different group labels. ```python from multiqc.plots import bargraph data = { 'sample1_25nt': {'Frame0': 50, 'Frame1': 30, 'Frame2': 20}, 'sample1_26nt': {'Frame0': 60, 'Frame1': 25, 'Frame2': 15}, 'sample2_25nt': {'Frame0': 55, 'Frame1': 28, 'Frame2': 17}, 'sample2_26nt': {'Frame0': 65, 'Frame1': 22, 'Frame2': 13}, } pconfig = { 'id': 'my_bargraph', 'title': 'My Bar Graph', 'sample_groups': { '25nt': [['sample1_25nt', 'sample1'], ['sample2_25nt', 'sample2']], '26nt': [['sample1_26nt', 'sample1'], ['sample2_26nt', 'sample2']], } } html = bargraph.plot(data, cats, pconfig=pconfig) ``` In this example, for each read length group (`25nt`, `26nt`), bars with the same `offset_group` (`sample1` or `sample2`) are aligned at the same horizontal position, allowing direct visual comparison of sample1 vs sample2 across read lengths. ![bargraph sample groups](../../../docs/images/bargraph_sample_groups.png) See the [custom content example file](https://github.com/MultiQC/test-data/blob/main/data/custom_content/embedded_config/frame_bargraph_mqc.csv) to reproduce this plot. ## Line graphs This base function works much like the above, but for two-dimensional data, to produce line graphs. It expects a dictionary with sample identifiers, each containing numeric `x:y` points. For example: ```python from multiqc.plots import linegraph data = { "sample 1": { "": "", "": "", }, "sample 2": { "": "", "": "", }, } html = linegraph.plot(data) ``` Additionally, a configuration dict can be supplied. The defaults are as follows: ```python from multiqc.plots import linegraph pconfig = { # Building the plot "id": "", # HTML ID used for plot "categories": False, # Set to True to use x values as categories instead of numbers. "colors": dict(), # Provide dict with keys = sample names and values colours "smooth_points": None, # Supply a number to limit number of points / smooth data "smooth_points_sumcounts": True, # Sum counts in bins, or average? Can supply list for multiple datasets "logswitch": False, # Show the 'Log10' switch? "logswitch_active": False, # Initial display with 'Log10' active? "logswitch_label": "Log10", # Label for 'Log10' button "axis_controlled_by_switches": ["yaxis"], # Which axes should be impacted by the switch button (one or both of xaxis, yaxis) "extra_series": None, # See section below # Plot configuration "title": None, # Plot title - should be in format "Module Name: Plot Title" "xlab": None, # X axis label "ylab": None, # Y axis label "xmax": None, # Hard max x limit "xmin": None, # Hard min x limit "ymax": None, # Hard max y limit "ymin": None, # Hard min y limit "x_clipmax": None, # Max value allowed for automatic axis limit "x_clipmin": None, # Min value allowed for automatic axis limit "y_clipmax": None, # Max value allowed for automatic axis limit "y_clipmin": None, # Min value allowed for automatic axis limit "x_minrange": None, # Min range for x-axis (5 would allow 0..5, but also 15..20, etc.) "y_minrange": None, # Min range for y-axis (5 would allow 0..5, but also 15..20, etc.) "xlog": False, # Use log10 for the x-axis "ylog": False, # Use log10 scale for the y-axis "y_bands": None, # Horizontal colored background bands "x_bands": None, # Vertical colored background bands "y_lines": None, # Extra horizontal lines "x_lines": None, # Extra vertical lines "xsuffix": "%", # Suffix for the X-axis values and labels. Parsed from tt_label by default "ysuffix": "%", # Suffix for the Y-axis values and labels. Parsed from tt_label by default "tt_label": "{point.x}: {point.y:.2f}", # Customise tooltip label, e.g. '{point.x} base pairs' "tt_decimals": None, # Tooltip decimals when categories = True (when false use tt_label) "height": 500, # The default height of the plot, in pixels "style": "line", # The style of the line. Can be "line" or "lines+markers" } html = linegraph.plot(..., pconfig) ``` :::note The keys `id` and `title` should always be passed as a minimum. The `id` is used for the plot name when exporting. If left unset the Plot Export panel will call the filename `mqc_hcplot_gtucwirdzx.png` (with some other random string). Plots should always have titles, especially as they can stand by themselves when exported. The title should have the format `Modulename: Plot Name` ::: ### X-axis format Plotly will try to automatically parse the X-axis values. Strings that look like a number will be interpreted as numbers (e.g. `"13"` and `"2.0"` will turn into `13` and `2.0` and get ordered numerically: `2.0`, `13`); dates in ISO format will be parsed as datestamps (e.g. `"2021-01-01"` will turn into a `datetime` object and ordered chronologically). If you want to force the X-axis to be treated as plain strings, set `categories=True` in the plot config. ### Switching datasets You can also have a single plot with buttons to switch between different datasets. To do this, just supply a list of data dicts instead (same formats as described above). For example: ```python data = [ { "sample 1": {"": "", "": ""}, "sample 2": {"": "", "": ""}, }, { "sample 1": {"": "", "": ""}, "sample 2": {"": "", "": ""}, }, ] ``` You'll also want to add the following configuration options to give names to the buttons and graph labels: ```python config = { "data_labels": [ { "name": "DS 1", # Button label "ylab": "y axis 1", # Y-axis label "xlab": "x axis 1", # X-axis label }, { "name": "DS 2", "ylab": "y axis 2", "xlab": "x axis 2", }, ] } ``` All of these config values are optional, the function will default to sensible values if things are missing. ### Additional data series Sometimes, it's good to be able to specify specific data series manually. To do this, use `config['extra_series']`. For a single extra line this can be a dict (as below). For multiple lines, use a list of dicts. For multiple dataset plots, use a list of list of dicts. For example, to add a dotted `x = y` reference line: ```python from multiqc.plots import linegraph max_x_val = ... max_y_val = ... pconfig = { "extra_series": { "name": "x = y", "data": [[0, 0], [max_x_val, max_y_val]], "dash": "dash", "width": 1, "color": "#000000", "marker": {"enabled": False}, "showlegend": False, } } html = linegraph.plot(..., pconfig) ``` ### Background bands and lines Line graphs can include background bands and reference lines to highlight specific regions or thresholds. These are configured using the `x_bands`, `y_bands`, `x_lines`, and `y_lines` options. #### Background bands Background bands are colored rectangular regions that span across the plot. They can be used to highlight acceptable ranges, warning zones, or other meaningful regions in your data. ```python from multiqc.plots import linegraph pconfig = { "y_bands": [ {"from": 0, "to": 5, "color": "#009500", "opacity": 0.13}, # Good range (green) {"from": 5, "to": 20, "color": "#a07300", "opacity": 0.13}, # Warning range (yellow) {"from": 20, "to": 100, "color": "#990101", "opacity": 0.13}, # Bad range (red) ], "x_bands": [ {"from": 10, "to": 50, "color": "#f0f0f0", "opacity": 0.3}, # Highlighted region ] } html = linegraph.plot(data, pconfig) ``` Each band definition supports the following options: - `from`: Start value for the band - `to`: End value for the band - `color`: Background color (any valid CSS color) - `opacity`: Transparency level from 0.0 (fully transparent) to 1.0 (fully opaque). Defaults to 1.0 if not specified. #### Reference lines Reference lines are single horizontal or vertical lines that can mark specific thresholds or reference points. ```python pconfig = { "y_lines": [ {"value": 30, "color": "#ff0000", "width": 2, "dash": "dash", "label": "Threshold"} ], "x_lines": [ {"value": 25, "color": "#0000ff", "width": 1, "dash": "solid"} ] } ``` Each line definition supports: - `value`: Position of the line on the respective axis - `color`: Line color (any valid CSS color) - `width`: Line thickness in pixels (default: 2) - `dash`: Line style - "solid", "dash", "dot", "dashdot", etc. (default: "solid") - `label`: Optional text label for the line ## Box plots Box plots take similar data structure as line plots, but better visualize the underlying data distribution by emphasizing quartiles, mean, median, standard deviation, the extreme values and the outliers. Instead of x:y pairs, the box plot take a flat list of points for each sample: ```python from multiqc.plots import box data = { "sample 1": [9, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10], "sample 2": [2, 4, 6, 6, 6, 10, 0, 1], } html = box.plot(data, pconfig=...) ``` Similarly to other plot types, multiple datasets can be passed as `data`, along with dataset-specific configurations provided with the `pconfig["data_labels"]` option. ### Box plot outlier display Box plots now dynamically control outlier display based on the number of samples, similar to violin plots. The behavior is determined by two configuration thresholds: ```yaml box_min_threshold_outliers: 100 # For more than this number of samples, show only outliers box_min_threshold_no_points: 1000 # For more than this number of samples, show no points ``` **Dynamic behavior:** - **≤ 100 samples**: Show all data points (`"all"`) - **101-1000 samples**: Show only outliers (`"outliers"`) - **> 1000 samples**: Show no points (`false`) **Manual override:** You can still manually control the behavior using the `boxplot_boxpoints` configuration option, which will override the dynamic logic: ```yaml boxplot_boxpoints: "outliers" # Override dynamic behavior ``` Available options (as defined by [Plotly's box trace reference](https://plotly.com/python/reference/box/#box-boxpoints)): - `"outliers"`: Show only outlier points beyond the whiskers - `"all"`: Show all data points - `"suspectedoutliers"`: Show only suspected outliers (points beyond 1.5 × IQR but within 3 × IQR) - `false`: Hide all data points, showing only the box and whiskers This dynamic approach helps to: - Reduce visual clutter when dealing with many samples - Maintain interactivity for smaller datasets - Automatically optimize performance for large datasets - Highlight specific outlier patterns when appropriate ## Scatter plots Scatter plots work in almost exactly the same way as line plots. Most (if not all) config options are shared between the two. The data structure is similar but not identical: ```python from multiqc.plots import scatter data = { "sample 1": { "x": "", "y": "", }, "sample 2": { "x": "", "y": "", }, } html = scatter.plot(data) ``` Note that you must use the keys `x` and `y` for each data point. If you want more than one data point per sample, you can supply a list of dictionaries instead. You can also optionally specify point colours and sample name suffixes (these are appended to the sample name): ```python data = { "sample 1": [ {"x": "", "y": "", "color": "#a6cee3", "name": "Type 1"}, {"x": "", "y": "", "color": "#1f78b4", "name": "Type 2"}, ], "sample 2": [ {"x": "", "y": "", "color": "#b2df8a", "name": "Type 1"}, {"x": "", "y": "", "color": "#33a02c", "name": "Type 2"}, ], } ``` Remember that MultiQC reports can contain large numbers of samples, so this plot type is **not** suitable for large quantities of data - 20,000 genes might look good for one sample, but when someone runs MultiQC with 500 samples, it will crash the browser and be impossible to interpret. See the documentation about line plots for most config options. The scatter plot has a handful of unique ones in addition: ```python pconfig = { "square": False, # Force the plot to stay square? (Maintain aspect ratio) "xmin": None, # Hard min x limit "xmax": None, # Hard max x limit "ymin": None, # Hard min y limit "ymax": None, # Hard max y limit "x_clipmin": None, # Min value allowed for automatic axis limit "x_clipmax": None, # Max value allowed for automatic axis limit "y_clipmin": None, # Min value allowed for automatic axis limit "y_clipmax": None, # Max value allowed for automatic axis limit } ``` ## Creating a table Tables should work just like the functions above (most like the bar graph function). As a minimum, the function takes a dictionary containing data - the first keys will be sample names (row headers) and each key contained within will be a table column header. You can also supply a list of key names to restrict the data in the table to certain keys / columns. This also specifies the order that columns should be displayed in. For more customisation, the headers can be supplied as a dictionary. Each key should match the keys used in the data dictionary, but values can customise the output. Finally, the function accepts a config dictionary as a third parameter. This can set global options for the table (e.g. a title) and can also hold default values to customise the output of all table columns. The default header keys are: ```python single_header = { "namespace": "", # Name for grouping. Prepends desc and is in Config Columns modal "title": "[ dict key ]", # Short title, table column title "description": "[ dict key ]", # Longer description, goes in mouse hover text "max": None, # Minimum value in range, for bar / colour coding "min": None, # Maximum value in range, for bar / colour coding "ceiling": None, # Maximum value for automatic bar limit "floor": None, # Minimum value for automatic bar limit "minrange": None, # Minimum range for automatic bar "scale": "GnBu", # Colour scale for colour coding. False to disable. "bgcols": None, # Dict with values: background colours for categorical data. "colour": "", # Colour for column grouping "suffix": None, # Suffix for value (e.g. '%') "format": "{:,.1f}", # Value format string - default 1 decimal place "cond_formatting_rules": None, # Rules for conditional formatting table cell values - see docs below "cond_formatting_colours": None, # Styles for conditional formatting of table cell values "shared_key": None, # See below for description "modify": None, # Lambda function to modify values "hidden": False, # Set to True to hide the column on page load } ``` A third parameter can be specified with settings for the whole table: ```python table_config = { "namespace": "", # Name for grouping. Prepends desc and is in Config Columns modal "id": "", # ID used for the table "title": "", # Title of the table. Used in the column config modal "save_file": False, # Whether to save the table data to a file "raw_data_fn": "multiqc__table", # File basename to use for raw data file "sort_rows": True, # Whether to sort rows alphabetically "only_defined_headers": True, # Only show columns that are defined in the headers config "col1_header": "Sample Name", # The header used for the first column "no_violin": False, # Force a table to always be plotted (beeswarm by default if many rows) } ``` Most of the header keys can also be specified in the table config (`namespace`, `scale`, `format`, `colour`, `hidden`, `max`, `min`, `ceiling`, `floor`, `minrange`, `shared_key`, `modify`). These will then be applied to all columns prior to applying column-specific heading config. A very basic example of creating a table is shown below: ```python from multiqc.plots import table data = { "sample 1": { "aligned": 23542, "not_aligned": 343, }, "sample 2": { "aligned": 1275, "not_aligned": 7328, }, } html = table.plot(data, headers=..., pconfig=...) ``` A more complicated version with ordered columns, defaults and column-specific settings (e.g. no decimal places): ```python from multiqc.plots import table from multiqc import config data = { "sample 1": { "aligned": 23542, "not_aligned": 343, "aligned_percent": 98.563952271, }, "sample 2": { "aligned": 1275, "not_aligned": 7328, "aligned_percent": 14.820411484, }, } headers = { "aligned_percent": { "title": "% Aligned", "description": "Percentage of reads that aligned", "suffix": "%", "max": 100, "format": "{:,.0f}", # No decimal places please }, "aligned": { "title": "Aligned", "description": f"Aligned Reads ({config.read_count_desc})", "shared_key": "read_count", "suffix": f" {config.read_count_prefix}", "modify": lambda x: x * config.read_count_multiplier, }, "config": { "namespace": "My Module", "min": 0, "scale": "GnBu", }, } html = table.plot(data, headers=headers, pconfig=...) ``` ### Table decimal places You can customise how many decimal places a number has by using the `format` config key for that column. The default format string is `"{:,.1f}"`, which specifies a float number with a single decimal place. To remove decimals use `"{:,d}"`. To have two decimal places, use `"{:,.2f}"`. ### Table colour scales Colour scales are taken from [ColorBrewer2](http://colorbrewer2.org/). Colour scales can be reversed by adding the suffix `-rev` to the name. For example, `RdYlGn-rev`. The following scales are available: ![color brewer](../../../docs/images/cbrewer_scales.png) ### Custom cell background colours You can specify custom background colours for specific values using the `bgcols` header config. This takes precedence over `scale`. For example, a header config for a column could look like this: ```python headers = { "col": { "title": "My table column", "bgcols": { "bad data": "#f8d7da", "ok data": "#fff3cd", "good data": "#d1e7dd" } } } ``` ### Zero centrepoints If you set the header config `bars_zero_centrepoint` to `True`, the background bars will use the absolute values to calculate bar width. So a value of `0` will have a bar width of `0`, `20` a width of `20` and `-30` a width of `30`. This works well with a divergent colour-scheme as the bar width shows the magnitude of the value properly, whilst the colour scheme shows the difference between positive and negative values. For example: ```python headers = { "col": { "title": "My table column", "scale": "RdYlGn", "bars_zero_centrepoint": True, } } ``` ### Conditional formatting of data values MultiQC has configuration options to allow users to configure ["Conditional formatting"](../reports/customisation.md#conditional-formatting), with highlighted values in table cells. Developers can also make use of this functionality within the header config dictionaries for formatting data values. The functionality follows the same logic as for user configs with the parameters `cond_formatting_rules` and `cond_formatting_colours`. These correspond to the user config options `table_cond_formatting_rules` and `table_cond_formatting_colours`, with the exception that no column ID is needed for `table_cond_formatting_rules`. For example, a simple header config could look as follows: ```python headers = { "col": { "title": "My table column", "cond_formatting_rules": { "pass": [{"s_eq": "good data"}], "warn": [{"s_eq": "ok data"}], "fail": [{"s_eq": "bad data"}], } } } ``` A more complex version with multiple rules could be: ```python headers = { "col": { "title": "My table column", "cond_formatting_rules": { "brightgreen": [ {"s_contains": "amazing"}, {"s_contains": "incredible"}, ], "brown": [{"s_ne": "rubbish-data"}], "turquoise": [ {"gt": 4}, {"lt": 12}, ], }, "cond_formatting_colours": [ {"brightgreen": "#39FF14"}, {"brown": "#A52A2A"}, {"turquoise": "#30D5C8"}, ] } } ``` ### Specifying sorting of columns By default, each table is sorted by sample name alphabetically. You can override the sorting order using the `defaultsort` option. Here is an example: ```yaml custom_plot_config: general_stats_table: defaultsort: - column: "Mean Insert Length" direction: asc - column: "Starting Amount (ng)" quast_table: defaultsort: - column: "Largest contig" ``` In this case, the general stats table will be sorted by "Mean Insert Length" first, in ascending order, then by "Starting Amount (ng)", in descending (default) order. The table with the ID `quast_table` (which you can find by clicking the "Configure Columns" button above the table in the report) will be sorted by "Largest contig". ### Configurable columns Table columns can be reodered and change visibility using the "Configure Columns" button in the report. However, for very wide tables, the performance degrades, so the button is disabled when the number of rows exceeds `config.max_configurable_table_columns` (default is 200). You can adjust this value in the config file. ## Violin plots Violin plots work from the exact same data structure as tables, so the usage is just the same. Moreover, a for every table, a switch button is available to view a corresponding violin plot for the underlying data. ```python from multiqc.plots import violin data = { "sample 1": { "aligned": 23542, "not_aligned": 343, }, "sample 2": { "not_aligned": 7328, "aligned": 1275, }, } html = not violin.plot(data, headers=..., pconfig=...) ``` The function also accepts the same headers and config parameters. ## Heatmaps Heatmaps expect data in the structure of a list of lists. Then, a list of sample names for the x-axis, and optionally for the y-axis (defaults to the same as the x-axis). ```python from multiqc.plots import heatmap heatmap.plot(data=..., xcats=..., ycats=..., pconfig=...) ``` A simple example: ```python from multiqc.plots import heatmap data = [ [0.9, 0.87, 0.73, 0.6, 0.2, 0.3], [0.87, 1, 0.7, 0.6, 0.9, 0.3], [0.73, 0.8, 1, 0.6, 0.9, 0.3], [0.6, 0.8, 0.7, 1, 0.9, 0.3], [0.2, 0.8, 0.7, 0.6, 1, 0.3], [0.3, 0.8, 0.7, 0.6, 0.9, 1], ] names = ["one", "two", "three", "four", "five", "six"] html = heatmap.plot(data, xcats=names, pconfig=...) ``` Alternatively you can supply a dictionary of dictionaries, in which case xcats and ycats are optional: ```python data = { "sample 1": { "one": 0.9, "two": 0.87, "three": 0.73, "four": 0.6, "five": 0.2, }, "sample 2": { "two": 1, "three": 0.7, "four": 0.6, "six": 0.3, }, } from multiqc.plots import heatmap html = heatmap.plot(data, pconfig=...) ``` Much like the other plots, you can change the way that the heatmap looks using a config dictionary: ```python pconfig = { "title": None, # Plot title - should be in format "Module Name: Plot Title" "xlab": None, # X-axis title "ylab": None, # Y-axis title "zlab": None, # Z-axis title, shown in the hover tooltip "min": None, # Minimum value (when unset, derived automatically) "max": None, # Maximum value (when unset, derived automatically) "square": True, # Force the plot to stay square? (maintain aspect ratio) "xcats_samples": True, # Is the x-axis sample names? Set to "False" to prevent report toolbox from affecting. "ycats_samples": True, # Is the y-axis sample names? Set to "False" to prevent report toolbox from affecting. "colstops": [], # Scale colour stops. See below. "reverse_colors": False, # Reverse the order of the colour axis "tt_decimals": 2, # Number of decimal places for tooltip "legend": True, # Colour axis key enabled or not "display_values": True, # Show values in each cell. Defaults True when less than 20 samples. "height": 500 # The default height of the interactive plot, in pixels } ``` The colour stops are a bit special and can be used to define a custom colour scheme. These should be defined as a list of lists, with a number between 0 and 1 and a HTML colour. The default is `RdYlBu` from [ColorBrewer](http://colorbrewer2.org/): ```python pconfig = { "colstops": [ [0, "#313695"], [0.1, "#4575b4"], [0.2, "#74add1"], [0.3, "#abd9e9"], [0.4, "#e0f3f8"], [0.5, "#ffffbf"], [0.6, "#fee090"], [0.7, "#fdae61"], [0.8, "#f46d43"], [0.9, "#d73027"], [1, "#a50026"], ] } ``` ## Interactive / Flat image plots Note that the all plotting functions except for `table` can generate both interactive JavaScript-powered report plots _and_ flat image plots. This choice is made depending on the presence of the `--flat` (`config.plots_flat`) flag. Note that both plot types should come out looking pretty much identical. If you spot something that's missing in the flat image plots, let me know. --- ## MultiQC Plugins MultiQC is written around a system designed for extensibility and plugins. These features allow custom code to be written without polluting the central code base. Please note that we want MultiQC to grow as a community tool! So if you're writing a module or theme that can be used by others, please keep it within the main MultiQC framework and submit a pull request. ## Entry Points The plugin system works using setuptools [entry points](http://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins). In `pyproject.toml` you will see a section of code that looks like this _(truncated)_: ```toml [project.entry-points."multiqc.modules.v1"] qualimap = "multiqc.modules.qualimap:MultiqcModule" [project.entry-points."multiqc.templates.v1"] default = "multiqc.templates.default" # [project.entry-points."multiqc.cli_options.v1"] # my-new-option = "myplugin.cli:new_option" # [project.entry-points."multiqc.hooks.v1"] # before_config = "myplugin.hooks:before_config" ``` These sets of entry points can each be extended to add functionality to MultiQC: - `multiqc.modules.v1` - Defines the module classes. Used to add new modules. - `multiqc.templates.v1` - Defines the templates. Can be used for new templates. - `multiqc.cli_options.v1` - Allows plugins to add new custom command line options - `multiqc.hooks.v1` - Code hooks for plugins to add new functionality Any python program can create entry points with the same name, once installed MultiQC will find these and run them accordingly. If your Python project uses `setup.py` instead you can still tie into the entry points. For an example of this in action, see the [MultiQC_NGI](https://github.com/MultiQC/MultiQC_NGI/blob/master/setup.py) setup file: ```python entry_points = { 'multiqc.templates.v1': [ 'ngi = multiqc_ngi.templates.ngi', 'genstat = multiqc_ngi.templates.genstat', ], 'multiqc.cli_options.v1': [ 'project = multiqc_ngi.cli:pid_option' ], 'multiqc.hooks.v1': [ 'after_modules = multiqc_ngi.hooks:ngi_metadata', ] }, ``` Here, two new templates are added, a new command line option and a new code hook. ## Modules List items added to `multiqc.modules.v1` specify new modules. They should be described as follows: ```toml modname = "python_mod.dirname.submodname:classname" ``` Once this is done, everything else should be the same as described in the [writing modules](modules.md) documentation. ## Templates As above, though no need to specify a class name at the end. See the [writing templates](templates.md) documentation for further instructions. ## Command line options MultiQC handles command line interaction using the [click](http://click.pocoo.org/) framework. You can use the `multiqc.cli_options.v1` entry point to add new click decorators for command line options. For example, the MultiQC_NGI plugin uses the entry point above with the following code in `cli.py`: ```python pid_option = click.option('--project', type=str) ``` The values given from additional command line arguments are parsed by MultiQC and put into `config.kwargs`. The above plugin later reads the value given by the user with the `--project` flag in a hook: ```python from multiqc import config if config.kwargs['project'] is not None: # do some stuff ``` See the [click documentation](http://click.pocoo.org/) or the main MultiQC script for more information and examples of adding command line options. ## Hooks Hooks are a little more complicated - these define points in the core MultiQC code where you can run custom functions. This can be useful as your code is able to access data generated by other parts of the program. For example, you could tie into the `after_modules` hook to insert data processed by MultiQC modules into a database automatically. Here, the entry point names are the hook titles, described as commented out lines in the core MultiQC `setup.py`: `execution_start`, `config_loaded`, `before_modules`, `after_modules` and `execution_finish`. These should point to a function in your code which will be executed when that hook fires. Your custom code can import the core MultiQC modules to access configuration and loggers. For example: ```python """ MultiQC hook functions - we tie into the MultiQC core here to add in extra functionality. """ from multiqc.utils import report log = logging.getLogger('multiqc') def after_modules(): """ Plugin code to run when MultiQC modules have completed """ num_modules = len(report.modules) status_string = f"MultiQC hook - {num_modules} modules reported!" log.critical(status_string) ``` --- ## Writing new templates # Writing New Templates MultiQC is built around a templating system that uses the [Jinja](http://jinja.pocoo.org/) python package. This makes it very easy to create new report templates that fit your needs. ## Core or plugin If your template could be of use to others, it would be great if you could add it to the main MultiQC package. You can do this by creating a fork of the [MultiQC GitHub repository](https://github.com/MultiQC/MultiQC), adding your template and then creating a pull request to merge your changes back to the main repository. If it's very specific template, you can create a new Python package which acts as a plugin. For more information about this, see the [plugins documentation](plugins.md). ## Creating a template skeleton For a new template to be recognised by MultiQC, it must be a python submodule directory with a `__init__.py` file. This must be referenced in the `setup.py` installation script as an [entry point](http://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins). You can see the bundled templates defined in this way: ```python entry_points = { 'multiqc.templates.v1': [ 'default = multiqc.templates.default', 'simple = multiqc.templates.simple', 'geo = multiqc.templates.geo', ] } ``` Note that these entry points can point to any Python modules, so if you're writing a plugin module you can specify your module name instead. Just make sure that `multiqc.templates.v1` is the same. Once you've added the entry point, remember to install the package again: ```bash pip install -e . ``` Using `-e` tells `pip` to softlink the plugin files instead of copying, so changes made whilst editing files will be reflected when you run MultiQC. The `__init__.py` files must define two variables - the path to the template directory and the main jinja template file: ```python template_dir = os.path.dirname(__file__) base_fn = 'base.html' ``` ## Child templates The default MultiQC template contains a _lot_ of code. Importantly, it includes 1448 lines of custom JavaScript (at time of writing) which powers the plotting and dynamic functions in the report. You probably don't want to rewrite all of this for your template, so to make your life easier you can create a _child template_. To do this, add an extra variable to your template's `__init__.py`: ```python template_parent = 'default' ``` This tells MultiQC to use the template files from the `default` template unless a file with the same name is found in your child template. For instance, if you just want to add your own logo in the header of the reports, you can create your own `header.html` which will overwrite the default header. Files within the default template have comments at the top explaining what part of the report they generate. Child templates can also inherit template functions from their parent. For example, the default template provides the `material_icon` function which can be used in any child template without additional configuration. ## Extra init variables There are a few extra variables that can be added to the `__init__.py` file to change how the report is generated. Setting `output_dir` instructs MultiQC to put the report and it's contents into a subdirectory. Set the string to your desired name. Note that this will be prefixed if `-p`/`--prefix` is set at run time. Secondly, you can copy additional files with your report when it is generated. This is usually used to copy required images or scripts with the report. These should be a list of file or directory paths, relative to the `__init__.py` file. Directory contents will be copied recursively. You can also override config options in the template. For example, setting the value of `config.plots_force_flat` can force the report to only have static image plots. ```python from multiqc.utils import config output_subdir = 'multiqc_report' copy_files = ['assets'] config.plots_force_flat = True ``` ## Development mode When developing a template, you can use the `development: true` config option or the `--development` command line flag. This instructs MultiQC not to embed source files directly into the HTML and instead link to the MultiQC source code files: - JavaScript and CSS files are loaded directly from the source code template directory instead of being embedded - Plot images are linked from external files rather than being embedded as base64 data URIs - Plot data is exported as an uncompressed JSON file (`multiqc_plots.js`) in the data directory This allows you to see changes to your template files immediately without rebuilding or recompiling. Simply refresh the report in your browser after making changes. ## Jinja template variables There are a number of variables that you can use within your Jinja template. Two namespaces are available - `report` and `config`. You can print these using the Jinja curly brace syntax, _eg._ `{{ config.version }}`. See the [Jinja2 documentation](http://jinja.pocoo.org/docs/dev/templates/) for more information. The default MultiQC template includes dependencies in the HTML so that the report is standalone. If you would like to do the same, use the `include_file` function. For example: ```html ``` ### Material Design Icons The default template includes a `material_icon` function that embeds Material Design Icons as inline SVG. This function is available to child templates that inherit from the default template. Usage: ```jinja {{ material_icon('delete') }} {{ material_icon('warning', 16) }} {{ material_icon('info', 20, '#0066cc') }} ``` The function takes three parameters: - `icon_name` (required): Name of the Material Design Icon (e.g., 'delete', 'info', 'warning') - `size` (optional, default 24): Size of the icon in pixels - `color` (optional, default 'currentColor'): Color of the icon The function will try to load the filled variant first, then fall back to the outlined variant if the filled version is not found. If the icon cannot be found, it returns an empty string. In strict mode (`--strict`), missing icons will be reported as errors. ## Appendices ### Custom plotting functions If you don't like the default plotting functions built into MultiQC, you can write your own! If you create a callable variable in a template called either `bargraph` or `linegraph`, MultiQC will use that instead. For example: ```python def custom_linegraph(plotdata, pconfig): return 'Awesome line graph here' linegraph = custom_linegraph def custom_bargraph(plotdata, plotseries, pconfig): return 'Awesome bar graph here' bargraph = custom_bargraph ``` These particular examples don't do very much, but hopefully you get the idea. Note that you have to set the variable `linegraph` or `bargraph` to your function. --- ## Configuration # Configuring MultiQC Whilst most MultiQC settings can be specified on the command line, MultiQC is also able to parse system-wide and personal config files. At run time, it collects the configuration settings from the following places in this order (overwriting at each step if a conflicting config variable is found): 1. Hardcoded defaults in MultiQC code 1. System-wide config in `/multiqc_config.yaml` - Manual installations only, not `pip` or `conda` 1. User config in `$XDG_CONFIG_HOME/multiqc_config.yaml` (or `~/.config/multiqc_config.yaml` if `$XDG_CONFIG_HOME` is not set) 1. User config in `~/.multiqc_config.yaml` 1. File path set in environment variable `$MULTIQC_CONFIG_PATH` - For example, define this in your `~/.bashrc` file and keep the file anywhere you like 1. Environment variables prefixed with `MULTIQC_` - For example, `$MULTIQC_TITLE`, `$MULTIQC_TEMPLATE` - see [docs below](#config-with-environment-variables) 1. Config file in the current working directory: `multiqc_config.yaml` 1. Config file paths specified in the command with `--config` / `-c` - You can specify multiple files like this, they can have any filename. 1. Command line config (`--cl-config`) 1. Specific command line options (_e.g._ `--force`) ## Config Wizard You can build a config file visually in your browser with the [MultiQC Configuration Wizard](https://seqera.io/multiqc_config_wizard). It has every option as a form field, with live YAML editor and schema validation as you type. See the [Config Wizard docs](config_wizard.md) for more information. ## Sample name cleaning MultiQC typically generates sample names by taking the input or log file name, and 'cleaning' it. ### Cleaning extensions To do this, it uses the `fn_clean_exts` settings and looks for any matches. If it finds any matches, everything to the right is removed. :::info{title=Example} ```yaml fn_clean_exts: - ".gz" - ".fastq" ``` | Input | Cleaned sample name | | ---------------------------------------- | ------------------- | | `mysample.fastq.gz` | `mysample` | | `secondsample.fastq.gz_trimming_log.txt` | `secondsample` | | `thirdsample.vcf.gz_report.txt` | `thirdsample.vcf` | ::: To add to the MultiQC defaults instead of overwriting them, use `extra_fn_clean_exts`: ```yaml extra_fn_clean_exts: - ".myformat" - "_processedFile" ``` ### Trimming extensions To remove a substring only if it is at the start or end of a sample name, rather than trimming it and everything after it, use `fn_clean_trim`. :::info{title=Example} ```yaml fn_clean_trim: - ".fastq.gz" - "_report.txt" ``` | Input | Cleaned sample name | | ---------------------------------------- | ---------------------------------------- | | `mysample.fastq.gz` | `mysample` | | `secondsample.fastq.gz_trimming_log.txt` | `secondsample.fastq.gz_trimming_log.txt` | | `thirdsample.vcf.gz_report.txt` | `thirdsample.vcf.gz` | ::: Again, to add to the MultiQC defaults instead of overwriting them, use `extra_fn_clean_trim`: ```yaml extra_fn_clean_trim: - "#" - ".myext" ``` ### Other search types If needed, you can specify different string matching methods to `fn_clean_exts` and `extra_fn_clean_exts` for more complex sample name cleaning: #### `truncate` (default) This is the default method as described above. The two examples below are equivalent: ```yaml extra_fn_clean_exts: - ".fastq" ``` ```yaml extra_fn_clean_exts: - type: "truncate" pattern: ".fastq" ``` #### `remove` The `remove` type allows you to remove an exact match from the filename. This includes removing a substring within the middle of a sample name. :::info{title=Example} ```yaml extra_fn_clean_exts: - type: remove pattern: .sorted ``` | Input | Cleaned sample name | | ----------------------------------- | --------------------------- | |  `secondsample.sorted.deduplicated` | `secondsample.deduplicated` | ::: #### `regex` You can also remove a substring with a regular expression. A useful website to work with writing regexes is [regex101.com](https://regex101.com). :::info{title=Example} ```yaml extra_fn_clean_exts: - type: regex pattern: "^processed." ``` | Input | Cleaned sample name | | --------------------------------- | ----------------------- | | `processed.thirdsample.processed` | `thirdsample.processed` | ::: #### `regex_keep` If you'd rather like to only _keep_ the match of a regular expression and discard everything else, you can use the `regex_keep` type. This is particularly useful if you have predictable sample names or identifiers. :::info{title=Example} ```yaml extra_fn_clean_exts: - type: regex_keep pattern: "[A-Z]{3}[1-9]{2}" ``` | Input | Cleaned sample name | | ----------------------------------------- | ------------------- | | `merged.recalibrated.XZY97.alignment.bam` | `XZY97` | ::: #### `module` This key will tell MultiQC to only apply the pattern to a specific MultiQC module. This should be a string that matches the module's `anchor` - the `#module` bit when you click the main module heading in the sidebar (remove the `#`). For example, to truncate all sample names to 5 characters for just Kallisto: ```yaml extra_fn_clean_exts: - type: regex_keep pattern: "^.{5}" module: kallisto ``` You can also supply a list of multiple module anchors if you wish: ```yaml extra_fn_clean_exts: - type: regex_keep pattern: "^.{5}" module: - kallisto - cutadapt ``` ### Clashing sample names This process of cleaning sample names can sometimes result in exact duplicates. A duplicate sample name will overwrite previous results. Warnings showing these events can be seen with verbose logging using the `--verbose`/`-v` flag, or in `multiqc_data/multiqc.log`. Problems caused by this will typically be discovered be fewer results than expected. If you're ever unsure about where the data from results within MultiQC reports come from, have a look at `multiqc_data/multiqc_sources.txt`, which lists the path to the file used for every section of the report. #### Directory names One scenario where clashing names can occur is when the same file is processed in different directories. For example, if `sample_1.fastq` is processed with four sets of parameters in four different directories, they will all have the same name - `sample_1`. Only the last will be shown. If the directories are different, this can be avoided with the `--dirs`/`-d` flag. For example, given the following files: ``` ├── analysis_1 │ └── sample_1.fastq.gz.aligned.log ├── analysis_2 │ └── sample_1.fastq.gz.aligned.log └── analysis_3 └── sample_1.fastq.gz.aligned.log ``` Running `multiqc -d .` will give the following sample names: ``` analysis_1 | sample_1 analysis_2 | sample_1 analysis_3 | sample_1 ``` #### Filename truncation If the problem is with filename truncation, you can also use the `--fullnames`/`-s` flag, which disables all sample name cleaning. For example: ``` ├── sample_1.fastq.gz.aligned.log └── sample_1.fastq.gz.subsampled.fastq.gz.aligned.log ``` Running `multiqc -s .` will give the following sample names: ``` sample_1.fastq.gz.aligned.log sample_1.fastq.gz.subsampled.fastq.gz.aligned.log ``` You can turn off sample name cleaning permanently by setting `fn_clean_sample_names` to `false` in your config file. ## Toolbox Settings MultiQC includes a toolbox with features to highlight, rename, and hide samples. These settings can be configured through the UI, but you can also pre-configure them in your config file. ### Highlighting Samples You can pre-configure sample highlighting patterns in your config file: ```yaml highlight_patterns: - "sample_1" - "control_" highlight_colors: - "#e41a1c" # red - "#377eb8" # blue highlight_regex: false # set to true to use regex patterns ``` Each pattern in `highlight_patterns` will be paired with the corresponding color in `highlight_colors`. If there are more patterns than colors, the colors will be reused in sequence. ### Hiding Samples You can pre-configure which samples to show or hide: ```yaml show_hide_buttons: ["Hide controls"] show_hide_patterns: ["control_"] show_hide_regex: [false] show_hide_mode: ["hide"] # can be "show" or "hide" ``` Each entry in these lists corresponds to a button that will appear in the toolbox. An extra "Show all" button with empty patterns is prepended by default. ### Renaming Samples You can pre-configure sample renaming patterns: ```yaml sample_names_rename: - ["_R1", ""] - ["sample_", "SAMPLE_"] ``` Each entry is a pair of [from, to] values that will be applied to sample names. ### Advanced sample name replacement For more powerful sample name replacement options, including regex support and different replacement modes, see the [Sample name replacement](../reports/customisation.md#sample-name-replacement) section in the report customisation documentation. These advanced features include: - `sample_names_replace` - Direct pattern-to-replacement mapping in config files - `sample_names_replace_regex` - Regular expression support for complex patterns - `sample_names_replace_exact` and `sample_names_replace_complete` - Fine-tuned matching behavior ## Module search patterns Many bioinformatics tools have standard output formats, filenames and other signatures. MultiQC uses these to find output; for example, the FastQC module looks for files that end in `_fastqc.zip`. This works well most of the time, until someone has an automated processing pipeline that renames things. For this reason, as of version v0.3.2 of MultiQC, the file search patterns are loaded as part of the main config. This means that they can be overwritten in `/multiqc_config.yaml` or `~/.multiqc_config.yaml`. So if you always rename your `_fastqc.zip` files to `_qccheck.zip`, MultiQC can still work. To see the default search patterns, check a given module in the MultiQC documentation. Each module has its search patterns listed beneath any free-text docs. Alternatively, see the [`search_patterns.yaml`](https://github.com/MultiQC/MultiQC/blob/main/multiqc/search_patterns.yaml) file in the MultiQC source code. Copy the section for the program that you want to modify and paste this into your config file. Make sure you make it part of a dictionary called `sp` as follows: ```yaml sp: mqc_module: fn: _mysearch.txt ``` Search patterns can specify a filename match (`fn`) or a file contents match (`contents`), as well as a number of additional search keys. See [below](../development/modules.md#step-1---find-log-files) for the full reference. ## Using log filenames as sample names A substantial number of MultiQC modules take the sample name identifiers that you see in the report from the file contents - typically the filename of the input file. This is because log files can often be called things like `mytool.log` or even concatenated. Using the input filename used by the tool is typically safer and more consistent across modules. However, sometimes this does not work well. For example, if the input filename is not relevant (eg. using a temporary file or FIFO, process substitution or stdin etc.). In these cases your log files may have useful filenames but MultiQC will not be using them. To force MultiQC to use the log filename as the sample identifier, you can use the `--fn_as_s_name` command line flag or set the `use_filename_as_sample_name`: ```yaml use_filename_as_sample_name: true ``` This affects all modules and all search patterns. If you want to limit this to just one or more specific modules or search patterns, you can do by giving a list: ```yaml use_filename_as_sample_name: - verifybamid - verifybamid/selfsm - prokka - trimmomatic - fastp - picard ``` You can specify either: - Module anchors (e.g., `verifybamid`, `prokka`) to apply to all search patterns for that module - Search pattern keys (e.g., `verifybamid/selfsm`, `picard/gcbias`) to apply to specific patterns Note that this should be the search pattern key and not just the module name. This is because some modules search for multiple files. The log filename will still be cleaned. To use the raw log filenames, combine with the `--fullnames`/`-s` flag or `fn_clean_sample_names` config option described above. ## Ignoring Files MultiQC begins by indexing all of the files that you specified and building a list of the ones it will use. You can specify files and directories to skip on the command line using `-x`/`--ignore`, or for more permanent memory, with the following config file options: `fn_ignore_files`, `fn_ignore_dirs` and `fn_ignore_paths` (the command line option simply adds to all of these). For example, given the following files: ``` ├── analysis_1 │ └── sample_1.fastq.gz.aligned.log ├── analysis_2 │ └── sample_1.fastq.gz.aligned.log └── analysis_3 └── sample_1.fastq.gz.aligned.log ``` You could specify the following relevant config options: ```yaml fn_ignore_files: - "*.log" fn_ignore_dirs: - "analysis_1" - "analysis_2" fn_ignore_paths: - "*/analysis_*/sample_1*" ``` Note that the searched file paths will usually be relative to the working directory and can be highly variable, so you'll typically want to start patterns with a `*` to match any preceding directory structure. ## Ignoring samples Some modules get sample names from the contents of the file and not the filename (for example, `stdout` logs can contain multiple samples). You can skip samples by their resolved sample names (after cleaning) with two config options: `sample_names_ignore` and `sample_names_ignore_re`. The first takes a list of strings to be used for glob pattern matching (same behaviour as the command line option `--ignore-samples`), the latter takes a list of regex patterns. For example: ```yaml sample_names_ignore: - "SRR*" sample_names_ignore_re: - '^SR{2}\d{7}_1$' ``` ## Large sample numbers MultiQC has been written with the intention of being used for any number of samples. This means that it _should_ work well with 6 samples or 6000. Very large sample numbers are becoming increasingly common, for example with single cell data. Producing reports with data from many hundreds or thousands of samples provides some challenges, both technically and also in terms of data visualisation and report usability. ### Disabling on-load plotting One problem with large reports is that the browser can hang when the report is first loaded. This is because it loading and processing the data for all plots at once. To mitigate this, large reports may show plots as grey boxes with a _"Show Plot"_ button. Clicking this will render the plot as normal and prevents the browser from trying to do everything at once. By default this behaviour kicks in when a plot has 50 samples or more. This can be customised by changing the `plots_num_samples_do_not_automatically_load` config option. ### Flat / interactive plots Reports with many samples start to need a lot of data for plots. This results in inconvenient report file sizes (can be 100s of megabytes) and worse, web browser crashes. To allow MultiQC to scale to these sample numbers, most plot types have two plotting methods in the code base - interactive and flat. Flat plots take up the same disk space irrespective of sample number and do not consume excessive resources to display. By default, MultiQC generates flat plots when there are 1000 or more samples. This cutoff can be changed by changing the `plots_flat_numseries` config option. This behaviour can also be changed by running MultiQC with the `--flat` / `--interactive` command line options or by setting the `plots_force_flat` / `plots_force_interactive` config options to `True`. ### Tables / violin plots Report tables with thousands of samples (table rows) can quickly become impossible to use. To avoid this, tables with large numbers of rows are instead plotted as a violin plot. These plots have fixed dimensions with any number of samples, and can be helpful to see the data distribution of each table column. By default, MultiQC starts using violin plots when a table has 500 rows or more. This can be changed by setting the `max_table_rows` config option. There are also interactive dots for separate samples that can be hovered to show sample name and highlight this sample in other rows. For efficiency, if the number of samples is above `violin_min_threshold_outliers` (default value 100), only dots for outliers within the distribution are shown, and for more than `violin_min_threshold_no_points` (1000) samples, only the violins without points are rendered. When the number of samples is above `violin_downsample_after` (2000), the underlying violin data itself is downsampled to keep the interactive reports efficient. ## Coloured log output As of MultiQC version 1.8, log output is coloured using the [coloredlogs](https://pypi.org/project/coloredlogs/) Python package. The code attempts to detect if the logs on the terminal are being redirected to a file or piped to another tool and will disable colours if so. If the colours annoy you or you're ending up with weird characters in your MultiQC output, you can disable this feature with the command line flag `--no-ansi`. Sadly it's not possible to set this in a config file, as the logger is initilised before configs are loaded. ## Checks for new versions When MultiQC runs it automatically checks to see if there is a new version available to download. If so, a log message is printed at the top of the run saying where to download it (_MultiQC Version v0.6 now available!_). This helps people stay up to date and reduces the number of bug reports that are due to outdated MultiQC versions. The timeout for the version check is set to 5 seconds, so if you're running offline it should fail silently and add negligable run time. However, if you prefer you can explicitly disable the version check by adding `no_version_check: true` to your MultiQC config. The check is done with the main [MultiQC API](https://api.multiqc.info/) (see [source code](https://github.com/MultiQC/api.multiqc.info)). The only statistics that are collected are the number of checks and a handful of metrics about the running environment of MultiQC, such as the Python version and installation method (see [source code](https://github.com/MultiQC/MultiQC/blob/06faefd772ade811c3f9968d8db6106bd14eb57a/multiqc/core/version_check.py#L24-L34)). No identifiable information (such as IP address) is stored. ## Command-line config Sometimes it's useful to specify a single small config option just once, where creating a config file for the occasion may be overkill. In these cases you can use the `--cl-config` option to supply additional config values on the command line. Config variables should be given as a YAML string. You will usually need to enclose this in quotes. If MultiQC is unable to understand your config you will get an error message saying `Could not parse command line config`. As an example, the following command configures the coverage levels to use for the Qualimap module: _(as [described in the docs](../modules/qualimap.md))_ ```bash multiqc ./datadir --cl-config "qualimap_config: { general_stats_coverage: [20,40,200] }" ``` ## Config with environment variables Config parameters can be set through environment variables prefixed with `MULTIQC_`. For example, setting: ```bash export MULTIQC_TITLE="My report" export MULTIQC_FILESEARCH_LINES_LIMIT=10 ``` Is equivalent to setting these in YAML: ```yaml title: "My report" filesearch_lines_limit: 10 ``` :::tip Some variables such as `title` can be also directly set through the command line options: `--title "My report"`. For a list of all parameters, run `multiqc --help`. ::: Note that it is _not_ possible to set nested config parameters through environment variables, such as those that expect lists or dicts as values (e.g. `fn_clean_exts`). ## Referencing environment variables in YAML configs It is also supported to interpolate environment variables with config files. For example, if you have a config file `multiqc_config.yaml` with the following content: ```yaml title: !ENV "${TITLE}" report_header_info: - Contact E-mail: !ENV "${NAME:info}@${DOMAIN:example.com}" ``` And you have the following environment variables set: ```bash export TITLE="My report" export NAME="John" ``` You will get the following report header: ``` *My report* Contact E-mail: John@example.com ``` See that the `$DOMAIN` environment variable was not set, and the default value `"example.com"` is used instead. For more details on environment variable interpolation, refer to the documentation of [pyaml_env](https://github.com/mkaranasou/pyaml_env), that is used by MultiQC internally to process user YAML files. ## Optimising run-time Usually, MultiQC run time is fairly insignificant - in the order of seconds. Unless you are running MultiQC on many thousands of analysis files, the optimisations described below will have limited practical benefit. In other words, if you're running with 15 RNAseq samples, you may as well save yourself some time and stick with the defaults. ### Profile your MultiQC run time As of version 1.9, MultiQC has a command line option to profile what it spends its time doing: `--profile-runtime` (`config.profile_runtime`). Whilst you're working with writing your pipeline / setting up your analysis, you can specify and MultiQC will add a section to the bottom of your report describing how much time it spent searching files and what it did with those files. You'll also get a breakdown in the command-line log of how long the different steps of MultiQC execution took: ``` [INFO ] multiqc : MultiQC complete [INFO ] multiqc : Run took 35.28 seconds [INFO ] multiqc : - 31.01s: Searching files [INFO ] multiqc : - 1.75s: Running modules [INFO ] multiqc : - 0.96s: Compressing report data [INFO ] multiqc : For more information, see the 'Run Time' section in multiqc_report.html ``` If MultiQC is finishing in a few seconds or minutes, you probably don't need to do anything. If you are working with huge numbers of files then it may be worth looking into these results to see if you can speed up MultiQC. The documentation below explains how to do this. ### Be picky with which modules are run Probably the easiest way to speed up MultiQC is to only use the modules that you know you have files for. MultiQC supports a _lot_ of different tools and searches for matching files for all of them every time you run it. You can do this with the `-m` / `--module` flag (can be repeated) or in a MultiQC config file by using `config.module_order`. See [Order of modules](../reports/customisation.md#order-of-modules). ### Optimise file search patterns Secondly, think about customising the search patterns of the slowest searches. As an example, logs from Picard are published to `STDOUT` and so can have any file name. Some people concatenate logs, so the contents can be anywhere in the file and the files must also be searched by subsequent tools in case they contain multiple outputs. If you know that all of your Picard MarkDuplicate log files have the filename `mysamplename_markduplicates.log` then you can safely customise that search pattern with the following MultiQC config: ```yaml sp: picard/markdups: fn: "*_markduplicates.log" ``` If you know that this is the only type of Picard output that you're interested in, you can also change all of the other Picard search patterns to use `skip: True`: ```yaml sp: picard/markdups: fn: "*_markduplicates.log" picard/alignment_metrics: skip: true picard/basedistributionbycycle: skip: true picard/gcbias: skip: true picard/hsmetrics: skip: true picard/insertsize: skip: true picard/oxogmetrics: skip: true picard/pcr_metrics: skip: true picard/quality_by_cycle: skip: true picard/quality_score_distribution: skip: true picard/quality_yield_metrics: skip: true picard/rnaseqmetrics: skip: true picard/rrbs_metrics: skip: true picard/sam_file_validation: skip: true picard/variant_calling_metrics: skip: true picard/wgs_metrics: skip: true ``` This can speed up execution a bit if you really want to squeeze that running time. The [MultiQC Modules documentation](../development/modules.md) shows the search patterns for every module. :::tip Note that it's only worth using `skip: true` on search patterns if you want to use one from a module that has several. Usually it's better to just [specify which modules you want to run](#be-picky-with-which-modules-are-run) instead. ::: ### Force interactive plots One step that can take some time is generating static-image plots (see [Flat / interactive plots](../development/plots.md#interactive--flat-image-plots)). You can force MultiQC to skip this and only use interactive plots by using the `--interactive` command line option (`config.plots_force_interactive`). This approach is **not recommended if you have a very large number of samples**, as this can produce a huge report file with all of the embedded plot data and crash your browser when opening it. If you are running MultiQC for the `multiqc_data` folder and never intend to look at the report, it speed things up though. ### Skip the report if you don't need it If you're running MultiQC just to get parsed data / exported plots (`multiqc_data`) or the output for MegaQC and don't actually need the report, you can skip it with `--no-report`. This prevents any HTML report from being generated, including the data compression step that precedes it. This can cut a few seconds off the MultiQC execution time. ## Custom CSS files MultiQC generates HTML reports. You can include custom CSS in your final report if you wish. Simply add CSS files to the `custom_css_files` config option: ```yaml custom_css_files: - myfile.css ``` Or pass `--custom-css-file` (can be specified multiple times) and MultiQC will include them in the final report HTML. ## JSON Schema validation MultiQC provides a JSON Schema for validating configuration files. This allows editors like VSCode to provide autocompletion and validation while editing MultiQC config files. ### JSON Schema Store The MultiQC config JSON schema is available via [https://www.schemastore.org/](https://www.schemastore.org/), so [most code editors](https://www.schemastore.org/json/#editors) should automatically provide autocompletion and validation if your config files file are named as any of the following: - `multiqc_config.yaml` - `multiqc_config.yml` - `.multiqc_config.yaml` - `.multiqc_config.yml` In many situations this should just work, without any additional action needed. If not (custom filenames for your config, or variations in IDE settings), see below to do this in a more explicit manner. ### Using with VSCode 1. Install the YAML extension for VSCode 2. Add the following to your VSCode settings.json: ```json { "yaml.schemas": { "https://raw.githubusercontent.com/MultiQC/MultiQC/main/multiqc/utils/config_schema.json": [ "**/multiqc_config.y*ml" ] } } ``` This will enable: - Autocompletion of config options - Validation of config values - Hover documentation for each option - Warning highlights for invalid values ### Using with other editors Most modern editors support JSON Schema validation for YAML files. You can point them to the schema URL: ``` https://raw.githubusercontent.com/MultiQC/MultiQC/main/multiqc/utils/config_schema.json ``` Alternatively, you can download the schema file locally and reference it in your editor configuration. ### Adding schema reference to config files You can also add a reference to the schema directly in your YAML config files: ```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/MultiQC/MultiQC/main/multiqc/utils/config_schema.json title: "My MultiQC Report" subtitle: "Quality Control Results" ``` This will enable validation in editors that support it, without requiring editor-specific configuration. ### Schema validation in Python The schema is also used internally by MultiQC when loading config files. If validation fails, a warning will be printed but execution will continue (to maintain backwards compatibility). To enable strict validation that fails on invalid configs, set the `strict` config option to `true`: ```yaml strict: true ``` Or use the `--strict` command line flag. --- ## Config Wizard # MultiQC Configuration Wizard The MultiQC Configuration Wizard is a visual editor for `multiqc_config.yaml`. Every option in MultiQC appears as a form field with a description and inline examples. A live YAML editor next to the form stays in sync as you edit either side. :::tip[Open the Config Wizard] **[seqera.io/multiqc_config_wizard ↗](https://seqera.io/multiqc_config_wizard)** ::: ## What it does - Live two-way sync - Form changes merge into the editor text, preserving comments and key order. Editor changes parse the YAML and push values back into the form once it's valid. - Schema validation - Every option is checked against the same `MultiQCConfig` Pydantic schema MultiQC uses to load configs. Type mismatches and enum violations show as red squiggles in the editor; unknown keys get an amber squiggle with a "did you mean?" suggestion. Form rows pick up a matching coloured status label. - Status filters - Chips at the top of the form help you to narrow it to just what's set, broken, unfilled, or matching the default. - Hover docs - Hover over a key in the editor to see its description, type, and default. - Click to reveal - Click a form row to highlight its line in the editor. Click a key in the editor to scroll the matching form row into view. When you're done, hit **Copy** to put the YAML on the clipboard, or **Download** to save it as `multiqc_config.yaml`. Drop the file in your project directory (or anywhere MultiQC looks; see [Configuring MultiQC](config.md) for the search paths) and run MultiQC as usual. ## How to use it 1. Open [seqera.io/multiqc_config_wizard](https://seqera.io/multiqc_config_wizard) 2. Browse the sections in the left sidebar, search by key name, or paste an existing YAML into the editor to start from there. 3. Edit the fields you care about. Unset fields fall back to the MultiQC defaults; you don't need to touch them. 4. Copy or download the result. You can leave the page and come back later: your in-progress YAML and form state persist in your browser's `localStorage`. ## Run it anywhere The wizard is a single self-contained HTML file. It loads Monaco, Ajv, js-yaml, and Google Fonts from CDNs on first load; everything else lives in the page. For offline use, on an air-gapped network, or pinned to your installed MultiQC version, download `docs/multiqc_config_wizard.html` from the [MultiQC repository](https://github.com/MultiQC/MultiQC) and open it in any modern browser: ```bash open multiqc_config_wizard.html ``` The local file and the one on https://seqera.io come from the same template, regenerated on every MultiQC release. ## How it works The wizard is generated from `MultiQCConfig`, the Pydantic model in `multiqc/utils/config_schema.py` that MultiQC itself uses at runtime. Each field's description, type, default, examples, and `Literal` enum flow through to the form, so the wizard tracks MultiQC release by release. At build time, `scripts/generate_config_wizard.py` reads the schema, classifies each field into a section, and substitutes the resulting JSON into a single HTML template (`scripts/wizard_template.html`). The output is `docs/multiqc_config_wizard.html`, checked in alongside the source. In the browser, [js-yaml](https://github.com/nodeca/js-yaml) parses the editor text into a JavaScript object on every change, and [Ajv](https://ajv.js.org/) validates that object against the JSON Schema exported from `MultiQCConfig`. Errors land in [Monaco's](https://microsoft.github.io/monaco-editor/) marker API as squiggles and hover tooltips. The form ↔ editor sync is two-way. Form changes regenerate the YAML and merge them into the existing editor text, preserving comments where possible. Editor changes parse the YAML and push values back into the form widgets. Cycle guards stop the two from re-triggering each other. The full source lives in the [MultiQC repository](https://github.com/MultiQC/MultiQC/tree/main/scripts). --- ## Installation # Installing MultiQC MultiQC is written in Python and can be installed in a number of ways. Which method you should use depends on how you're using MultiQC and how familiar you are with the Python ecosystem. If you're new to software packaging, this page can be a little overwhelming. If in doubt, a general rule is: - _Running MultiQC in a pipeline?_   Use [Docker](#docker) or [Singularity](#singularity). - _Running MultiQC locally?_   Use [uv](#uv), [Pip](#pip--pypi), or [Conda](#conda). :::tip{title="Installation cheat sheet"} Know what you're doing with this kind of thing? Here's a quick reference: MethodCommand uv ```bash uv tool install multiqc ``` Pip ```bash pip install multiqc ``` Conda ```bash conda install multiqc ``` uv (dev version) ```bash uv tool install git+https://github.com/MultiQC/MultiQC.git ``` Pip (dev version) ```bash pip install --upgrade --force-reinstall git+https://github.com/MultiQC/MultiQC.git ``` Docker ```bash docker run -t -v `pwd`:`pwd` -w `pwd` multiqc/multiqc multiqc . ``` ::: ## Installing Python MultiQC is written in Python and needs a Python installation to run. To run MultiQC manually install, you'll typically install it into a local Python environment. MultiQC requires Python version 3.9 or above. :::tip If you use [uv](#uv) to install MultiQC, you don't need to install Python separately — uv automatically downloads and manages Python for you. ::: ### System Python Python comes installed on most operating systems. You can install MultiQC directly here, but it is _not_ recommended. This often causes problems, and it's a little risky to mess with it. :::danger If you find yourself prepending `sudo` to any MultiQC commands, take a step back and think about Python virtual environments / conda instead. ::: ### Python with uv [uv](https://docs.astral.sh/uv/) is a fast Python package and project manager that can also install and manage Python versions. If you don't have Python installed, uv will automatically download it when needed — no separate Python installation required. To install uv: ```bash # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` uv will automatically download a suitable Python version when you install or run a Python package. If you'd like to install a specific Python version explicitly, you can do so with: ```bash uv python install 3.13 ``` ### Python with Conda To see if you have python installed, run `python --version` on the command line. MultiQC needs Python version 3.9+. We recommend using virtual environments to manage your Python installation. Our favourite is _conda_, a cross-platform tool to manage Python environments. You can follow installation instructions for Miniconda [here](https://docs.conda.io/en/latest/miniconda.html). Once conda is installed, you can create a Python environment with the following commands: ```bash conda create --name py3.13 python=3.13 conda activate py3.13 ``` You'll want to add the `conda activate py3.13` line to your `.bashrc` file, so that the environment is loaded every time you load the terminal. ### Using a specific python interpreter If you prefer, you can also run MultiQC with a specific python interpreter. The command line usage and flags are then exactly the same as if you ran just `multiqc`. For example: ```bash python -m multiqc . python3 -m multiqc . ~/my_env/bin/python -m multiqc . ``` ## Installing MultiQC locally There are a few different ways to install MultiQC into your local Python environment: ### uv [uv](https://docs.astral.sh/uv/) is a fast Python package and project manager, written in Rust. It can replace pip, pip-tools, pipx, pyenv, and virtualenv — all in a single tool. uv automatically manages Python installations, so you don't need to install Python separately. The recommended way to install MultiQC with uv is as a tool: ```bash uv tool install multiqc ``` This installs MultiQC into an isolated environment and adds the `multiqc` command to your PATH. You can then run `multiqc` directly: ```bash multiqc . ``` Alternatively, you can run MultiQC without installing it permanently using `uvx` (an alias for `uv tool run`): ```bash uvx multiqc . ``` To upgrade MultiQC: ```bash uv tool upgrade multiqc ``` #### Development version If you would like the development version from GitHub instead: ```bash uv tool install git+https://github.com/MultiQC/MultiQC.git ``` To update the dev version between releases, use `--reinstall`: ```bash uv tool install --reinstall git+https://github.com/MultiQC/MultiQC.git ``` You can also run the dev version directly without installing, using `uvx`: ```bash uvx --from git+https://github.com/MultiQC/MultiQC.git multiqc . ``` :::tip uv can also be used as a drop-in replacement for pip inside virtual environments. See the [uv documentation](https://docs.astral.sh/uv/) for more details. ::: ### Conda MultiQC is available on [Bioconda](https://bioconda.github.io/). ```bash conda install multiqc ``` Note that the order of conda channels is important. Please make sure that you have [configured your conda channels](https://bioconda.github.io/#usage) prior to installing anything with Bioconda: ```bash conda config --add channels bioconda conda config --add channels conda-forge conda config --set channel_priority strict ``` :::warning In the past we used `-c bioconda` in the installation command, but this is no longer the correct usage. Doing so will likely cause weird stuff to happen (such as only being able to install very old versions). ::: ### Pip / PyPI `pip` is the package manager for the Python Package Index. It comes bundled with recent versions of Python, otherwise you can find installation instructions [here](https://pip.pypa.io/en/stable/installation/). You can install MultiQC from [PyPI](https://pypi.python.org/pypi/multiqc) as follows: ```bash pip install multiqc ``` Use the `--upgrade` flag to update to the latest version. If you have problems with read-only directories, you can install to your home directory with the `--user` parameter: ```bash pip install --user multiqc ``` #### Development version If you would like the development version, the command is: ```bash pip install git+https://github.com/MultiQC/MultiQC.git ``` To update the dev version between releases, use `--upgrade --force-reinstall`. This is needed as the version number isn't changing. ### Spack MultiQC [is available on spack](https://packages.spack.io/package.html?name=py-multiqc) as `py-multiqc`: ```bash spack install py-multiqc ``` ### FreeBSD If you're using the [FreeBSD](https://www.freebsd.org/) operating system, you can install MultiQC via [FreeBSD ports](https://www.freebsd.org/ports/): ```bash pkg install py39-multiqc ``` This will install a prebuilt binary using only highly-portable optimizations. FreeBSD ports can also be built and installed from source: ```bash cd /usr/ports/biology/py-multiqc make install ``` To report issues with a FreeBSD port, please submit a PR on the [FreeBSD bug reports page](https://www.freebsd.org/support/bugreports.html). ### Cloning the repository If you'd rather not use either of these tools, you can clone the code and install the code yourself: ```bash git clone https://github.com/MultiQC/MultiQC.git cd MultiQC pip install . ``` Or, using uv: ```bash git clone https://github.com/MultiQC/MultiQC.git cd MultiQC uv pip install . ``` This will fetch the latest development code. To update to the latest changes, use `git pull`. Use the `--editable` flag (`pip install -e .` or `uv pip install -e .`) if you intend to develop the code locally. This symlinks the source files so that you don't have to reinstall every time you edit a file. `git` not installed? No problem - just download the flat files: ```bash curl -LOk https://github.com/MultiQC/MultiQC/archive/main.zip unzip main.zip cd MultiQC-main pip install . ``` ### Nix If you're using the [nix package manager](https://nixos.org/download.html#download-nixm) with [flakes](https://nixos.wiki/wiki/Flakes) enabled, you can run `nix develop` in the cloned MultiQC repository to enter a shell with required dependencies. To build MultiQC, run `nix build`. ## MultiQC container images ### Docker A Docker container is provided on Docker Hub called [`multiqc/multiqc`](https://hub.docker.com/r/multiqc/multiqc/). It's based on a `python-slim` base image to give the smallest image size possible. To use, call the `docker run` with your current working directory mounted as a volume and working directory. Then just specify the MultiQC command at the end as usual: ```bash docker run -t -v `pwd`:`pwd` -w `pwd` multiqc/multiqc multiqc . ``` - `-t`: Runs docker with a pseudo-tty, for nice terminal colours - `-v`: Mounts the current working directory into the container - `-w`: Sets the working directory in the container as your local working directory You can specify additional MultiQC parameters as normal at the end of the command: ```bash docker run -t -v `pwd`:`pwd` -w `pwd` multiqc/multiqc multiqc . --title "My amazing report" -b "This was made with docker" ``` By default, docker will use the `:latest` tag. For MultiQC, this is set to be the most recent release. To use the most recent development code, use `multiqc/multiqc:dev`. You can also specify specific versions, eg: `multiqc/multiqc:v1.20`. #### Docker image variants MultiQC provides two Docker image variants to suit different needs: 1. **Standard image** (recommended for most users): `multiqc/multiqc:latest` (~1.5GB) - Includes all core MultiQC functionality - Smaller image size for faster downloads and reduced storage 2. **PDF-enabled image**: `multiqc/multiqc:pdf-latest` (~3.2GB) - Includes Pandoc and LaTeX (LuaLaTeX) for PDF report generation - Required if you need to use the `--pdf` flag - Significantly larger due to LaTeX dependencies To use the PDF-enabled image: ```bash docker run -t -v `pwd`:`pwd` -w `pwd` multiqc/multiqc:pdf-latest multiqc . --pdf ``` Both variants are also available with the `:dev` tag for the latest development version (e.g., `multiqc/multiqc:pdf-dev`), and with specific version tags (e.g., `multiqc/multiqc:pdf-v1.20`). Note that all files on the command line (eg. config files) must also be mounted in the docker container to be accessible. For more help, look into [the Docker documentation](https://docs.docker.com/engine/reference/commandline/run/). :::warning{title="Docker image name change"} The docker image used to be called `ewels/multiqc`. All releases prior to MultiQC v1.19 can be found at [ewels/multiqc](https://hub.docker.com/r/ewels/multiqc/) and everything from v1.20 onwards can be found at [multiqc/multiqc](https://hub.docker.com/r/multiqc/multiqc/). ::: :::tip{title="Tip: Docker bash alias"} The docker command above is a little verbose, so if you are using this a lot it may be worth adding the following bash alias to your `~/.bashrc` file: ```bash alias multiqc="docker run -tv `pwd`:`pwd` -w `pwd` multiqc/multiqc multiqc" ``` Once applied (first log out and in again) you can then just use the `multiqc` command instead: ```bash multiqc . ``` ::: These docker images are [multi-platform images](https://docs.docker.com/build/building/multi-platform/) – each build contains two digests, one for `linux/amd64` and one for `linux/arm64`. Generally, the Docker client should be clever enough to pull the digest appropriate for your local compute architecture. However, if you wish you can force it with the `--platform` flag. ```bash docker pull --platform linux/arm64 multiqc/multiqc:latest ``` ### GitHub Packages If you prefer, the Docker images above are also available from [GitHub packages](https://github.com/MultiQC/MultiQC/pkgs/container/multiqc). Usage is identical, the only difference is that the URI has a `ghcr.io/` prefix: ```bash docker pull ghcr.io/multiqc/multiqc docker pull ghcr.io/multiqc/multiqc:pdf-latest ``` This image was also renamed, versions up to v1.19 can be found at [`ghcr.io/ewels/multiqc`](https://github.com/users/ewels/packages/container/package/multiqc). ### Singularity To build a singularity container image from the docker image, use the following command: _(change `1.20` to the current MultiQC version)_ ```bash singularity build multiqc-1.20.sif docker://multiqc/multiqc:v1.20 ``` Then, use `singularity run` to run the image with the normal MultiQC arguments: ```bash singularity run multiqc-1.20.sif my_results/ --title "Report made using Singularity" ``` :::info{title="Import errors with Singularity"} Sometimes, Singularity can be over-ambitious with sharing file paths which can result in the Python environment in your local system interacting with Python inside the image. This can give rise to `ImportError` errors for `numpy` and other packages. The giveaway for when this is the problem is that traceback will list python package paths which are on your system and look different that of MultiQC inside the container (eg. `/usr/lib/python3.8/site-packages/multiqc/`). To fix this, run the command `export PYTHONNOUSERSITE=1` before running MultiQC. This variable [tells Python](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONNOUSERSITE) not to add site-packages to the system path when loading, which should avoid the conflicts. ::: :::tip If you prefer, you can download a pre-built Singularity image from BioContainers, see below. ::: ### BioContainers [BioContainers](https://biocontainers.pro/) is a project that automatically builds Docker and Singularity container images from [Bioconda](https://bioconda.github.io/). The images are less fine-tuned for MultiQC so tend to have a larger filesize, but they should work well and are convenient. To see available images, visit the BioContainers [registry page for MultiQC](https://biocontainers.pro/tools/multiqc). ## Using MultiQC in a Python script You can import and run MultiQC from within a Python script, using the `multiqc.run()` function as follows: ```python multiqc.run("/path/to/dir") ``` More development of interactive usage is planned for the future. Currently you can't do a lot more than just running MultiQC. ## Galaxy ### On the main Galaxy instance The easiest and fast manner to use MultiQC is to use the [usegalaxy.org](https://usegalaxy.org/) main Galaxy instance where you will find [MultiQC Galaxy tool](https://usegalaxy.org/?tool_id=toolshed.g2.bx.psu.edu%2Frepos%2Fengineson%2Fmultiqc%2Fmultiqc%2F1.0.0.0&version=1.0.0.0&__identifer=2sjdq8d9r3l) under the _NGS: QC and manipualtion_ tool panel section. ### On your instance You can install MultiQC on your own Galaxy instance through your Galaxy admin space, searching on the [main Toolshed](https://toolshed.g2.bx.psu.edu/) for the [MultiQC repository](https://toolshed.g2.bx.psu.edu/view/iuc/multiqc/3bad335ccea9) available under the _visualization_, _statistics_ and _Fastq Manipulation_ sections. ## Environment modules Many people using MultiQC will be working on a HPC environment. Every server / cluster is different, and you're probably best off asking your friendly sysadmin to install MultiQC for you. However, with that in mind, here are a few general tips for installing MultiQC into an environment module system: MultiQC comes in two parts - the `multiqc` python package and the `multiqc` executable script. The former must be available in `$PYTHONPATH` and the script must be available on the `$PATH`. A typical installation procedure with an environment module Python install might look like this: _(Note that `$PYTHONPATH` must be defined before `pip` installation.)_ ```bash VERSION=0.7 INST=/path/to/software/multiqc/$VERSION module load python/3.11 mkdir $INST export PYTHONPATH=$INST/lib/python2.7/site-packages pip install --install-option="--prefix=$INST" multiqc ``` Once installed, you'll need to create an environment module file. Again, these vary between systems a lot, but here's an example: ```bash #%Module1.0##################################################################### ## ## MultiQC ## set components [ file split [ module-info name ] ] set version [ lindex $components 1 ] set modroot /path/to/software/multiqc/$version proc ModulesHelp { } { global version modroot puts stderr "\tMultiQC - use MultiQC $version" puts stderr "\n\tVersion $version\n" } module-whatis "Loads MultiQC environment." # load required modules module load python/3.11 # only one version at a time conflict multiqc # Make the directories available prepend-path PATH $modroot/bin prepend-path PYTHONPATH $modroot/lib/python3.11/site-packages ``` --- ## Quick start # MultiQC: Quick start This tutorial covers installation and first run for a typical user. It's not meant to be comprehensive - see the rest of the documentation for that - it's just to get the majority up and running quickly so you can get a taste for how to use MultiQC. ## Install MultiQC ### Option A: Using uv (recommended) [uv](https://docs.astral.sh/uv/) is a fast Python package manager that handles everything — including installing Python for you automatically. No need to install Python separately (see [full docs](installation/#uv)). 1. Install uv: ```bash # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh ``` 2. Install MultiQC: ```bash uv tool install multiqc ``` ### Option B: Using Conda Alternatively, you can use Conda (see [full docs](installation/#python-with-conda)). 1. [Download miniconda](https://conda.io/miniconda.html) for your operating system. 2. Run the bash script and follow the prompts. 3. Restart your terminal shell. 4. [Configure your conda channels](https://bioconda.github.io/#usage) to work with Bioconda: ```bash conda config --add channels bioconda conda config --add channels conda-forge conda config --set channel_priority strict ``` 5. Create a new conda environment: ```bash conda create --name myenv python=3.11 conda activate myenv ``` 6. Install MultiQC: ```bash conda install multiqc ``` ### Verify installation Check that it worked by printing the MultiQC version (or `--help` text): ```bash multiqc --version ``` ```txt multiqc, version 1.33 ``` ## Get some example data To try MultiQC out quickly, you can fetch some example input data from the [Example reports](https://seqera.io/multiqc/#reports) page. Each example report has a link to _Download input data_. You should be able to recreate the example report using this. For example, for the [RNA-seq report](https://seqera.io/examples/rna-seq/multiqc_report): ```bash curl -O -J -L https://seqera.io/examples/rna-seq/data.zip unzip data.zip ``` You should now have a directory called `data` which is full of analysis result files. For the RNA-seq example, we have outputs from a bioinformatics analysis of some publicly available data. We have logs and reports from [FastQC](https://www.bioinformatics.babraham.ac.uk/projects/fastqc/), [TrimGalore!](https://www.bioinformatics.babraham.ac.uk/projects/trim_galore/) ([Cutadapt](https://cutadapt.readthedocs.io/)), [STAR](https://github.com/alexdobin/STAR) and [featureCounts](https://subread.sourceforge.net/). ## Run MultiQC There isn't much to running MultiQC really - just point it at the directory that contains your files and it will search recursively for anything it recognises. Assuming that you are still in the directory where you just extracted the data, the current working directory (`.`) contains your files: ```bash multiqc . ``` ```txt /// MultiQC 🔍 | v1.33 | multiqc | Search path : /demo/data | searching | ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 121/121 | feature_counts | Found 8 reports | star | Found 8 reports | cutadapt | Found 16 reports | fastqc | Found 32 reports | multiqc | Report : multiqc_report.html | multiqc | Data : multiqc_data | multiqc | MultiQC complete ``` ## Open the report You can see in the log output that MultiQC created a file called `multiqc_report.html`. Open it and take a look (you can usually ctrl/cmd + click the filename in most terminals). It should look basically the same as [this example report](https://seqera.io/examples/rna-seq/multiqc_report). Try using the toolbox features in the right hand sidebar, for example hiding and highlighting specific samples. Also have a look at the directory `multiqc_data` that was created. This contains the parsed data in a nice friendly format, ready for any further downstream analysis. ## Customise the report When you want to set a title, hide modules, rename samples, or change anything else about the report, MultiQC reads a `multiqc_config.yaml` from your project directory. The easiest way to write one is the [Config Wizard](config_wizard.md): a browser-based editor with a live YAML preview and schema validation. See the [Configuration](config.md) page for the precedence rules and search paths. --- ## Running MultiQC Once installed, just go to your analysis directory and run `multiqc`, followed by a list of directories to search. At it's simplest, this can just be `.` (the current working directory): ```bash multiqc . ``` That's it! MultiQC will scan the specified directories and produce a report based on details found in any log files that it recognises. See [Using MultiQC Reports](../reports/reports.md) for more information about how to use the generated report. For a description of all command line parameters, run `multiqc --help`. :::info Every command-line flag mentioned on this page has a corresponding configuration variable that can be set in a MultiQC config YAML file. This may be preferable if using a lot of options, or running in a pipeline. See [Configuration](config.md) for the search paths, or use the [Config Wizard](config_wizard.md) to build a config file in your browser. ::: ## Choosing where to scan You can supply MultiQC with as many directories or files as you like. Above, we supply `.` - just the current directory, but all of these would work too: ```bash multiqc data/ multiqc data/ ../proj_one/analysis/ /tmp/results multiqc data/*_fastqc.zip multiqc data/sample_1* ``` If the `--ignore-symlinks` flag is set, MultiQC will ignore symlinked directories and files. ### Ignoring files You can also ignore files or directories using the `-x`/`--ignore` option. This can be specified multiple times and accepts glob patterns (eg. using the `*` and `?` wildcards). :::warning Glob patterns should be enclosed in quotes to prevent them being expanded by bash. ::: The argument can match filenames, directory names and entire paths. For example: ```bash multiqc . --ignore "file" multiqc . --ignore "fileA" --ignore "fileB" multiqc . --ignore "_R?.zip" multiqc . --ignore "run_two/*" multiqc . --ignore "*/run_three/*/fastqc/*_R2.zip" ``` Some modules get sample names from the contents of the file and not the filename (for example, `stdout` logs can contain multiple samples). In this case, you can skip samples by name instead: ```bash multiqc . --ignore-samples "sample_3*" ``` These strings are matched using glob logic (`*` and `?` are wildcards). All of these settings can be saved in a MultiQC config file so that you don't have to type them on the command line for every run. ### File of search paths If you have a large list of specific files, you can supply a file containing a list of file paths, one per row. MultiQC will only search the listed files. ```bash multiqc --file-list my_file_list.txt ``` ## Renaming reports The report is called `multiqc_report.html` by default. Tab-delimited data files are created in `multiqc_data/`, containing additional information. You can use a custom name for the report with the `-n`/`--filename` parameter, or instruct MultiQC to create them in a subdirectory using the `-o`/`--outdir` parameter. Note that different MultiQC templates may have different defaults. ## Overwriting existing reports It's quite common to repeatedly create new reports as new analysis results are generated. Instead of manually deleting old reports, you can just specify the `-f`/`--force` parameter and MultiQC will overwrite any conflicting report filenames. ## Choosing which modules to run Sometimes, it's desirable to choose which MultiQC modules run. This could be because you're only interested in one type of output and want to keep the reports small. Or perhaps the output from one module is misleading in your situation. You can do this by using `-m`/`--modules` to explicitly define which modules you want to run. Alternatively, use `-e`/`--exclude` to run all modules _except_ those listed. If an explicitly requested module couldn't find any expected input files, MultiQC will just continue with other modules. You can change this behaviour and make MultiQC strict about missing input by setting the `--require-logs` flag. If set, MultiQC will exit with an error and exit code `1` if any of the modules specified with `-m` did not produce a section in the report. ## Directory prefixes in sample names Sometimes, the same samples may be processed in different ways. If MultiQC finds log files with the same sample name, the previous data will be overwritten (this can be inspected by running MultiQC with `-v`/`--verbose`). To avoid this, run MultiQC with the `-d`/`--dirs` parameter. This will prefix every sample name with the directory path for that log file. As such, sample names should now be unique, and not overwrite one-another. By default, `--dirs` will prepend the entire path to each sample name. You can choose which directories are added with the `-dd`/`--dirs-depth` parameter. Set to a positive integer to use that many directories at the end of the path. A negative integer takes directories from the start of the path. For example, show the full relative file path in the sample name: ``` $ multiqc -d . # analysis_1 | results | type | sample_1 | file.log # analysis_2 | results | type | sample_2 | file.log # analysis_3 | results | type | sample_3 | file.log ``` Prepend just the last directory name: ``` $ multiqc -d -dd 1 . # sample_1 | file.log # sample_2 | file.log # sample_3 | file.log ``` Prepend the first directory name: ``` $ multiqc -d -dd -1 . # analysis_1 | file.log # analysis_2 | file.log # analysis_3 | file.log ``` ## Printing to stdout If you would like to generate MultiQC reports on the fly, you can print the output to standard out by specifying `-n stdout`. The data directory will not be generated and the template used must create stand-alone HTML reports. ## Using different templates MultiQC is built around a templating system. You can produce reports with different styling by using the `-t`/`--template` option. The available templates are listed with `multiqc --help`. If you're interested in creating your own custom template, see the [writing new templates](../development/templates.md) section. ## Parsed data directory By default, MultiQC creates a directory alongside the report containing tab-delimited files with the parsed data. This is useful for downstream processing, especially if you're running MultiQC with very large numbers of samples. Typically, these files are tab-delimited tables. However, you can get `JSON` or `YAML` output for easier downstream parsing by specifying `-k`/`--data-format` on the command line or `data_format` in your configuration file. You can also choose whether to produce the data by specifying either the `--data-dir` or `--no-data-dir` command line flags or the `make_data_dir` variable in your configuration file. Note that the data directory is never produced when printing the MultiQC report to `stdout`. To zip the data directory, use the `-z`/`--zip-data-dir` flag. ## Exporting Plots In addition to the HTML report, it's also possible to get MultiQC to save plots as standalone files. You can do this with the `-p`/`--export` command line flag. By default, plots will be saved in a directory called `multiqc_plots` as `.png`, `.svg` and `.pdf` files. Raw data for the plots are also saved to files. You can instruct MultiQC to always do this by setting the `export_plots` config option to `true`, though note that this will add a few seconds on to execution time. The `plots_dir_name` changes the default directory name for plots and the `export_plot_formats` specifies what file formats should be created (must be supported by Plotly). Note that not all plot types are yet supported, so you may find some plots are missing. :::note You can always save static image versions of plots from within MultiQC reports, using the [Export toolbox](../reports#exporting-plots) in the side bar. ::: ### Export timeout Static plot generation uses [Kaleido](https://github.com/plotly/Kaleido) under the hood, which can occasionally hang. To prevent this from blocking report generation indefinitely, MultiQC applies a timeout to each plot export. If the timeout is exceeded, the plot export is skipped and report generation continues. The default timeout is 60 seconds per plot. You can adjust this with the `export_plots_timeout` config option. ## PDF Reports Whilst HTML is definitely the format of choice for MultiQC reports due to the interactive features that it can offer, PDF files are an integral part of some people's workflows. To try to accommodate this, MultiQC has a `--pdf` command line flag which will try to create a PDF report for you. :::danger PDF export support for MultiQC can be difficult to use and disables many core MultiQC features and even some plots. It should only be used as a last resort. ::: To generate PDFs, MultiQC uses the `simple` template. This uses flat plots, has no navigation or toolbar and strips out all JavaScript. The resulting HTML report is pretty basic, but this simplicity is helpful when generating PDFs. Once the report is generated MultiQC attempts to call [Pandoc](http://pandoc.org/), a command line tool able to convert documents between different file formats. **You must have Pandoc already installed for this to work**. If you don't have Pandoc installed, you will get an error message that looks like this: ``` Error creating PDF - pandoc not found. Is it installed? http://pandoc.org/ ``` Please note that Pandoc is a complex tool and has a number of its own dependencies for PDF generation. Notably, it uses LaTeX / LuaLaTeX which you must also have installed. Please make sure that you have the latest version of Pandoc and that it can successfully convert basic HTML files to PDF before reporting and errors. Error messages from Pandoc are piped through to the MultiQC log, for example if the lualatex dependency is not installed you will see the following: ``` lualatex not found. Please select a different --pdf-engine or install lualatex ``` :::tip{title="Using Docker for PDF generation"} If you're using Docker, a PDF-enabled image is available that includes all required dependencies (Pandoc and LaTeX). See the [Docker installation documentation](installation.md#docker-image-variants) for details on using `multiqc/multiqc:pdf-latest`. ::: Note that not all plots have flat image equivalents, so some will be missing (at time of writing: FastQC sequence content plot, beeswarm dot plots, heatmaps). --- ## MultiQC overview MultiQC is a reporting tool that parses results and statistics from bioinformatics tool outputs, such as log files and console outputs. It helps to summarise experiments containing multiple samples and multiple analysis steps. It's designed to be placed at the end of pipelines or to be run manually when you've finished running your tools. :::note MultiQC doesn't _do_ any analysis for you - it just finds results from other tools that you have already run and generates nice reports. ::: When you launch MultiQC, it recursively searches through any provided file paths and finds files that it recognises. It parses relevant information from these and generates a single stand-alone HTML report file. In addition to the HTML report, MultiQC generates a directory of parsed data files with consistent data structure. This can be useful for further downstream analysis. --- ## Adapter Removal :::note Removes adapter sequences, trims low quality bases from 3' ends, or merges overlapping pairs into consensus. [https://github.com/mikkelschubert/adapterremoval](https://github.com/mikkelschubert/adapterremoval) ::: AdapterRemoval searches for and removes remnant adapter sequences from High-Throughput Sequencing (HTS) data and (optionally) trims low quality bases from the 3' end of reads following adapter removal. It can analyze both single end and paired end data, and can be used to merge overlapping paired-ended reads into (longer) consensus sequences. Additionally, the AdapterRemoval may be used to recover a consensus adapter sequence for paired-ended data, for which this information is not available. The module parses `*.settings` logs from Adapter Removal. Supported setting file results: - `single end` - `paired end noncollapsed` - `paired end collapsed` ### File search patterns ```yaml adapterremoval: contents: AdapterRemoval fn: '*.settings' num_lines: 1 ``` --- ## AfterQC :::note Automatic filtering, trimming, error removing, and quality control for FastQ data. [https://github.com/OpenGene/AfterQC](https://github.com/OpenGene/AfterQC) ::: AfterQC goes through all FastQ files in a folder and outputs three folders: good, bad and QC folders, which contains good reads, bad reads and the QC results of each fastq file/pair. ### File search patterns ```yaml afterqc: contents: allow_mismatch_in_poly fn: '*.json' num_lines: 10000 ``` --- ## Anglerfish :::note Quality controls Illumina libraries sequenced on Oxford Nanopore flowcells. [https://github.com/remiolsen/anglerfish](https://github.com/remiolsen/anglerfish) ::: Assessment of pool balancing, contamination, and insert sizes are currently supported ### File search patterns ```yaml anglerfish: contents: anglerfish_version fn: '*.json' ``` --- ## ATAQV :::note Toolkit for quality control and visualization of ATAC-seq data. [https://github.com/ParkerLab/ataqv/](https://github.com/ParkerLab/ataqv/) ::: ### File search patterns ```yaml ataqv: contents: ataqv_version fn: '*.json' num_lines: 10 ``` --- ## Bakta :::note Rapid & standardized annotation of bacterial genomes, MAGs & plasmids. [https://github.com/oschwengers/bakta](https://github.com/oschwengers/bakta) ::: The module analyses summary results from the Bakta annotation pipeline for bacterial genomes. The summary text file used is included in the Bakta output since v1.3.0. The MultiQC module was written for the output of v1.7.0. ### File search patterns ```yaml bakta: contents: 'Bakta:' fn: '*.txt' ``` --- ## Bamdst :::note Lightweight tool to stat the depth coverage of target regions of BAM file(s). [https://https://github.com/shiquan/bamdst](https://https://github.com/shiquan/bamdst) ::: The module reads data from two types of Bamdst logs: - `coverage.report`: used to build a table with coverage statistics. The sample name is read from this file. - `chromosomes.report`: if this file is found in the same directory as the file above, additionally a per-contig coverage plot will be generated. This file must be named exactly this way, with the `.report` extension. Note that for the sample names, the module will attempt to use the input BAM name in the header in the `coverage.report` file: ``` ## The file was created by bamdst ## Version : 1.0.9 ## Files : ST0217_Lg.bam ... ``` However, if the tool was run in a piped manner, the file name will be just `-` or `/dev/stdin`, and instead MultiQC will fall back to using the log file name `coverage.report`. Make sure to run MultiQC with `--dirs` if use have multiple samples run in this way, otherwise MultiQC will only report the first found sample under the name `coverage`. For the per-contig coverage plot, you can include and exclude contigs based on name or pattern. For example, you could add the following to your MultiQC config file: ```yaml bamdst: include_contigs: - "chr*" exclude_contigs: - "*_alt" - "*_decoy" - "*_random" - "*_fix" - "HLA*" - "chrUn*" - "chrEBV" - "chrM" ``` Note that exclusion supersedes inclusion for the contig filters. To additionally avoid cluttering the plot, MultiQC can exclude contigs with a low relative coverage. ```yaml bamdst: # Should be a fraction, e.g. 0.001 (exclude contigs with 0.1% coverage of sum of # coverages across all contigs) perchrom_fraction_cutoff: 0.001 ``` If you want to see what is being excluded, you can set `show_excluded_debug_logs` to `True`: ```yaml bamdst: show_excluded_debug_logs: True ``` This will then print a debug log message (use `multiqc -v`) for each excluded contig. This is disabled by default as there can be very many in some cases. ### File search patterns ```yaml bamdst/coverage: contents: '## The file was created by bamdst' num_lines: 5 ``` --- ## Bamtools :::note Provides both a programmer's API and an end-user's toolkit for handling BAM files. [https://github.com/pezmaster31/bamtools](https://github.com/pezmaster31/bamtools) ::: The module parses `bamtools stats` logs generated by Bamtools. Supported commands: `stats` ### File search patterns ```yaml bamtools/stats: contents: 'Stats for BAM file(s):' num_lines: 10 ``` --- ## Bases2Fastq :::note Demultiplexes and converts Element AVITI base calls into FASTQ files. [https://docs.elembio.io/docs/bases2fastq/introduction/](https://docs.elembio.io/docs/bases2fastq/introduction/) ::: Bases2Fastq is Element Biosciences' secondary analysis software for demultiplexing sequencing data from AVITI systems and converting base calls into FASTQ files. Data Flow Overview ------------------ The module handles three distinct data hierarchy levels: 1. **Run Level**: Single sequencing run with all samples in one output - Directory: `/` - Files: `RunStats.json`, `RunManifest.json` - Samples identified by: `{RunName}-{AnalysisID}__{SampleName}` 2. **Project Level**: Demultiplexing by project, samples split into project subdirectories - Directory: `/Samples//` - Files: Project-specific `RunStats.json` - Run-level `RunManifest.json` accessed via `../../RunManifest.json` - Samples identified by: `{RunName}-{AnalysisID}__{SampleName}` 3. **Combined Level**: Both run and project data present (merged view) Parsing Flow ------------ ``` __init__() │ ├─> _init_data_structures() # Initialize empty dicts for all data levels │ ├─> _parse_and_validate_data() # Main parsing entry point │ │ │ ├─> _parse_run_project_data("bases2fastq/run") # Parse run-level RunStats.json │ │ └─> Populates: run_level_data, run_level_samples, run_level_samples_to_project │ │ │ ├─> _parse_run_project_data("bases2fastq/project") # Parse project-level RunStats.json │ │ └─> Populates: project_level_data, project_level_samples, project_level_samples_to_project │ │ │ └─> _determine_summary_path() # Returns: "run_level" | "project_level" | "combined_level" │ ├─> _select_data_by_summary_path() # Route to appropriate data sources │ │ │ ├─> _parse_run_manifest() or _parse_run_manifest_in_project() │ │ └─> Returns: manifest_data (lane settings, adapter info) │ │ │ ├─> _parse_index_assignment() or _parse_index_assignment_in_project() │ │ └─> Returns: index_assignment_data (per-sample index stats) │ │ │ └─> _parse_run_unassigned_sequences() (run_level only) │ └─> Returns: unassigned_sequences (unknown barcodes) │ ├─> _setup_colors() # Assign colors to runs/projects/samples │ └─> _generate_plots() # Create all report sections and plots ``` Data Structures --------------- - `run_level_data`: Dict[run_name, run_stats] - Run-level QC metrics - `run_level_samples`: Dict[sample_id, sample_stats] - Sample metrics from run-level - `project_level_data`: Dict[project_name, project_stats] - Project-level QC metrics - `project_level_samples`: Dict[sample_id, sample_stats] - Sample metrics from project-level - `*_samples_to_project`: Dict[sample_id, project_name] - Maps samples to their projects Sample Naming Convention ------------------------ Samples are uniquely identified as: `{RunName}-{AnalysisID[0:4]}__{SampleName}` This ensures uniqueness across multiple runs while keeping names readable. Files Parsed ------------ - `RunStats.json`: Run/project QC metrics, sample statistics, lane data - `RunManifest.json`: Sample sheet info, index sequences, adapter settings Metrics Displayed ----------------- - Polony counts and yields - Base quality distributions (histogram and by-cycle) - Index assignment statistics - Per-sample sequence content and GC distribution - Adapter content analysis - Unassigned/unknown barcode sequences (run-level only) ### File search patterns ```yaml bases2fastq/manifest: contents: Settings fn: RunManifest.json num_lines: 100 bases2fastq/project: contents: SampleStats fn: '*_RunStats.json' num_lines: 100 bases2fastq/run: contents: SampleStats fn: RunStats.json num_lines: 100 ``` --- ## BBDuk :::note Common data-quality-related trimming, filtering, and masking operations with a kmer based approach. [https://jgi.doe.gov/data-and-tools/software-tools/bbtools/bb-tools-user-guide/bbduk-guide/](https://jgi.doe.gov/data-and-tools/software-tools/bbtools/bb-tools-user-guide/bbduk-guide/) ::: The module produces summary statistics from the stdout logging information from the BBDuk tool of the [BBTools](http://jgi.doe.gov/data-and-tools/bbtools/bb-tools-user-guide/) suite of tools. "Duk" stands for Decontamination Using Kmers. BBDuk was developed to combine most common data-quality-related trimming, filtering, and masking operations into a single high-performance tool. The module can summarise data from the following BBDuk funtionality (descriptions from command line help output): - `entropy` - entropy filtering - `ktrim` - kmer trimming - `qtrim` - quality trimming - `maq` - read quality filtering - `ref` contaminant filtering Additional information on the BBMap tools is available on [SeqAnswers](http://seqanswers.com/forums/showthread.php?t=41057). ### File search patterns ```yaml bbduk: contents: Executing jgi.BBDuk num_lines: 2 ``` --- ## BBTools :::note Pre-processing, assembly, alignment, and statistics tools for DNA/RNA sequencing reads. [http://jgi.doe.gov/data-and-tools/bbtools/](http://jgi.doe.gov/data-and-tools/bbtools/) ::: The module produces summary statistics from the [BBMap](http://jgi.doe.gov/data-and-tools/bbtools/bb-tools-user-guide/) suite of tools. The module can summarise data from the following BBMap output files (descriptions from command line help output): - `stats` - BBDuk filtering statistics. - `covstats` _(not yet implemented)_ - Per-scaffold coverage info. - `rpkm` _(not yet implemented)_ - Per-scaffold RPKM/FPKM counts. - `covhist` - Histogram of # occurrences of each depth level. - `basecov` _(not yet implemented)_ - Coverage per base location. - `bincov` _(not yet implemented)_ - Print binned coverage per location (one line per X bases). - `scafstats` _(not yet implemented)_ - Statistics on how many reads mapped to which scaffold. - `bbsplit` - Statistics on how many reads mapped to which reference genome. - `bhist` - Base composition histogram by position. - `qhist` - Quality histogram by position. - `qchist` - Count of bases with each quality value. - `aqhist` - Histogram of average read quality. - `bqhist` - Quality histogram designed for box plots. - `lhist` - Read length histogram. - `gchist` - Read GC content histogram. - `indelhist` - Indel length histogram. - `mhist` - Histogram of match, sub, del, and ins rates by read location. - `statsfile` _(not yet implemented)_ - Mapping statistics are printed here. Additional information on the BBMap tools is available on [SeqAnswers](http://seqanswers.com/forums/showthread.php?t=41057). ### File search patterns ```yaml bbmap/aqhist: contents: "#Quality\tcount1\tfraction1\tcount2\tfraction2" num_lines: 10 bbmap/bbsplit: contents: "#name\t%unambiguousReads\tunambiguousMB\t%ambiguousReads" num_lines: 5 bbmap/bhist: contents: "#Pos\tA\tC\tG\tT\tN" num_lines: 10 bbmap/bincov: contents: "#RefName\tCov\tPos\tRunningPos" num_lines: 10 bbmap/bqhist: contents: "#BaseNum\tcount_1\tmin_1\tmax_1\tmean_1\tQ1_1\tmed_1\tQ3_1\tLW_1\tRW_1\t\ count_2\tmin_2\tmax_2\tmean_2\tQ1_2\tmed_2\tQ3_2\tLW_2\tRW_2" num_lines: 10 bbmap/covhist: contents: "#Coverage\tnumBases" num_lines: 10 bbmap/covstats: contents: "#ID\tAvg_fold" num_lines: 10 bbmap/ehist: contents: "#Errors\tCount" num_lines: 10 bbmap/gchist: contents: - "#Mean\t" - "#GC\tCount" num_lines: 10 bbmap/idhist: contents: - '#Mean_reads' - "#Identity\tReads\tBases" num_lines: 10 bbmap/ihist: contents: - "#Mean\t" - "#InsertSize\tCount" num_lines: 10 bbmap/indelhist: contents: "#Length\tDeletions\tInsertions" num_lines: 10 bbmap/lhist: contents: "#Length\tCount" num_lines: 10 bbmap/mhist: contents: "#BaseNum\tMatch1\tSub1\tDel1\tIns1\tN1\tOther1\tMatch2\tSub2\tDel2\t\ Ins2\tN2\tOther2" num_lines: 10 bbmap/qahist: contents: "#Quality\tMatch\tSub\tIns\tDel" num_lines: 10 bbmap/qchist: contents_re: "#Quality\tcount1\tfraction1$" num_lines: 10 bbmap/qhist: contents: "#BaseNum\tRead1_linear\tRead1_log\tRead1_measured" num_lines: 10 bbmap/rpkm: contents: - "#File\t" - "#Reads\t" - "#Mapped\t" - "#RefSequences\t" - '#Name Length' num_lines: 10 bbmap/stats: contents: - '#File' - '#Total' - '#Matched' - "#Name\tReads\tReadsPct" num_lines: 10 bbmap/statsfile: contents: - 'Reads Used:' - 'Mapping:' - 'Reads/sec:' - 'kBases/sec:' num_lines: 10 bbmap/statsfile_machine: contents: Reads Used= num_lines: 10 ``` --- ## Bcftools :::note Utilities for variant calling and manipulating VCFs and BCFs. [https://samtools.github.io/bcftools/](https://samtools.github.io/bcftools/) ::: Supported commands: `stats` #### Collapse complementary substitutions In non-strand-specific data, reporting the total numbers of occurences for both changes in a comlementary pair - like `A>C` and `T>G` - might not bring any additional information. To collapse such statistics in the substitutions plot, you can add the following section into [your configuration](../getting_started/config): ```yaml bcftools: collapse_complementary_changes: true ``` MultiQC will sum up all complementary changes and show only `A>*` and `C>*` substitutions in the resulting plot. ### File search patterns ```yaml bcftools/stats: contents: This file was produced by bcftools stats ``` --- ## bcl2fastq :::note Demultiplexes data and converts BCL files to FASTQ file formats for downstream analysis. [https://support.illumina.com/sequencing/sequencing_software/bcl2fastq-conversion-software.html](https://support.illumina.com/sequencing/sequencing_software/bcl2fastq-conversion-software.html) ::: There are two versions of this software: `bcl2fastq` for MiSeq and HiSeq sequencing systems running RTA versions earlier than 1.8, and `bcl2fastq2` for Illumina sequencing systems running RTA version 1.18.54 and above. This module currently only covers output from the latter. ### File search patterns ```yaml bcl2fastq: contents: DemuxResults fn: Stats.json num_lines: 300 ``` --- ## BCL Convert :::note Demultiplexes data and converts BCL files to FASTQ file formats for downstream analysis. [https://support.illumina.com/sequencing/sequencing_software/bcl-convert.html](https://support.illumina.com/sequencing/sequencing_software/bcl-convert.html) ::: This BclConvert module is based on the bcl2fastq multiqc module. It can parse multiple bclconvert run outputs as long as they are from the same sequencing run. When doing this, the undetermined reads will be 'corrected' and re-calculated (as an unknown read from one run might not be truly unknown, but simply from another run). #### Calculate estimated depth You can specify a genome size in config It's often useful to talk about sequencing yield in terms of estimated depth of coverage. In order to make MultiQC show the estimated depth for each sample, specify the reference genome/target size in your [MultiQC configuration](../getting_started/config): ```yaml bclconvert: genome_size: 3049315783 ``` The coverage depth will be estimated as the yield Q30 dvivided by the genome size. MultiQC comes with effective genome size presets for Human and Mouse, so you can provide the genome build name instead, like this: `genome_size: hg38_genome`. The following values are supported: `hg19_genome`, `hg38_genome`, `mm10_genome`. #### Add barplots containing undetermined barcodes By default, the bar plot of undetermined barcodes is only shown when reporting from a single demultiplexing run. If you would like to show it with multiple runs (eg. bclconvert runs are split by lane), you can specify following parameter in your MultiQC config: ```yaml bclconvert: create_undetermined_barcode_barplots: True ``` The default of this configuration value is `False` ### File search patterns ```yaml bclconvert/adaptermetrics: fn: Adapter_Metrics.csv bclconvert/demux: fn: Demultiplex_Stats.csv bclconvert/quality_metrics: fn: Quality_Metrics.csv bclconvert/runinfo: fn: RunInfo.xml bclconvert/unknown_barcodes: fn: Top_Unknown_Barcodes.csv ``` --- ## biobambam2 :::note Tools for early stage alignment file processing. [https://gitlab.com/german.tischler/biobambam2](https://gitlab.com/german.tischler/biobambam2) ::: Currently, the biobambam2 module only processes output from the `bamsormadup` command. Not only that, but it cheats by using the module code from Picard/MarkDuplicates. The output is so similar that the code simply sets up a module with unique name and filename search pattern and then uses the parsing code from the Picard module. Apart from behind the scenes coding, this module should work in exactly the same way as all other MultiQC modules. ### File search patterns ```yaml biobambam2/bamsormadup: contents: '# bamsormadup' num_lines: 2 ``` --- ## BioBloom Tools :::note Assigns reads to different references using bloom filters. This is faster than alignment and can be used for contamination detection. [https://github.com/bcgsc/biobloom/](https://github.com/bcgsc/biobloom/) ::: BioBloom tools (BBT) create filters for a given reference and then to categorize sequences. This methodology is faster than alignment but does not provide mapping locations. BBT was initially intended to be used for pre-processing and QC applications like contamination detection, but is flexible to accommodate other purposes. This tool is intended to be a pipeline component to replace costly alignment steps. ### File search patterns ```yaml biobloomtools: contents: "filter_id\thits\tmisses\tshared\trate_hit\trate_miss\trate_shared" num_lines: 2 ``` --- ## BISCUIT :::note Maps bisulfite converted DNA sequence reads and determines cytosine methylation states. [https://github.com/huishenlab/biscuit](https://github.com/huishenlab/biscuit) ::: The module parses logs generated by the BISCUIT quality control script, `QC.sh`, which wraps `biscuit qc` and `biscuit qc_coverage` and adds an extra metric of base-averaged cytosine retention. It will search for all files output from `QC.sh`, though the user may run `biscuit qc` or `biscuit qc_coverage` separately, if desired. **Note**: As of MultiQC v1.9, the module supports only BISCUIT version v0.3.16 and onwards. If you have BISCUIT data from before this, please use MultiQC v1.8. #### Insert Size Distribution The second tab of this plot uses the config option `read_count_multiplier`, so if millions of reads is not useful for your data you can customise this. See [Number base (multiplier)](../reports/customisation#number-base-multiplier) in the documentation. ### File search patterns ```yaml biscuit/align_isize: contents: BISCUITqc Insert Size Table fn: '*_isize_table.txt' num_lines: 3 biscuit/align_mapq: contents: BISCUITqc Mapping Quality Table fn: '*_mapq_table.txt' num_lines: 3 biscuit/align_strand: contents: BISCUITqc Strand Table fn: '*_strand_table.txt' num_lines: 3 biscuit/base_avg_retention_rate: fn: '*_totalBaseConversionRate.txt' biscuit/covdist_all_base: fn: '*_covdist_all_base_table.txt' biscuit/covdist_all_base_botgc: fn: '*_covdist_all_base_botgc_table.txt' biscuit/covdist_all_base_topgc: fn: '*_covdist_all_base_topgc_table.txt' biscuit/covdist_all_cpg: fn: '*_covdist_all_cpg_table.txt' biscuit/covdist_all_cpg_botgc: fn: '*_covdist_all_cpg_botgc_table.txt' biscuit/covdist_all_cpg_topgc: fn: '*_covdist_all_cpg_topgc_table.txt' biscuit/covdist_q40_base: fn: '*_covdist_q40_base_table.txt' biscuit/covdist_q40_base_botgc: fn: '*_covdist_q40_base_botgc_table.txt' biscuit/covdist_q40_base_topgc: fn: '*_covdist_q40_base_topgc_table.txt' biscuit/covdist_q40_cpg: fn: '*_covdist_q40_cpg_table.txt' biscuit/covdist_q40_cpg_botgc: fn: '*_covdist_q40_cpg_botgc_table.txt' biscuit/covdist_q40_cpg_topgc: fn: '*_covdist_q40_cpg_topgc_table.txt' biscuit/cpg_retention_readpos: fn: '*_CpGRetentionByReadPos.txt' biscuit/cph_retention_readpos: fn: '*_CpHRetentionByReadPos.txt' biscuit/dup_report: contents: BISCUITqc Read Duplication Table fn: '*_dup_report.txt' num_lines: 3 biscuit/qc_cv: contents: BISCUITqc Uniformity Table fn: '*_cv_table.txt' num_lines: 3 biscuit/read_avg_retention_rate: fn: '*_totalReadConversionRate.txt' ``` --- ## Bismark :::note Maps bisulfite converted sequence reads and determine cytosine methylation states. [http://www.bioinformatics.babraham.ac.uk/projects/bismark/](http://www.bioinformatics.babraham.ac.uk/projects/bismark/) ::: ### File search patterns ```yaml bismark/align: fn: '*_[SP]E_report.txt' bismark/bam2nuc: fn: '*.nucleotide_stats.txt' bismark/dedup: fn: '*.deduplication_report.txt' bismark/m_bias: fn: '*M-bias.txt' bismark/meth_extract: fn: '*_splitting_report.txt' ``` --- ## Bowtie 1 :::note Ultrafast, memory-efficient short read aligner. [http://bowtie-bio.sourceforge.net/](http://bowtie-bio.sourceforge.net/) ::: ### File search patterns ```yaml bowtie1: contents: '# reads processed:' exclude_fn: - bowtie.left_kept_reads.log - bowtie.left_kept_reads.m2g_um.log - bowtie.left_kept_reads.m2g_um_seg1.log - bowtie.left_kept_reads.m2g_um_seg2.log - bowtie.right_kept_reads.log - bowtie.right_kept_reads.m2g_um.log - bowtie.right_kept_reads.m2g_um_seg1.log - bowtie.right_kept_reads.m2g_um_seg2.log shared: true ``` --- ## Bowtie 2 / HiSAT2 :::note Results from both Bowtie 2 and HISAT2, tools for aligning reads against a reference genome. [http://bowtie-bio.sourceforge.net/bowtie2/](http://bowtie-bio.sourceforge.net/bowtie2/), [https://ccb.jhu.edu/software/hisat2/](https://ccb.jhu.edu/software/hisat2/) ::: The module parses results generated by [Bowtie 2](http://bowtie-bio.sourceforge.net/bowtie2/) and [HISAT2](https://ccb.jhu.edu/software/hisat2/), ultrafast and memory-efficient tools for aligning sequencing reads to long reference sequences. Unfortunately, both tools have identical log output by default, so it is impossible to distinguish which tool was used. Please note that the Bowtie 2 and HISAT2 logs are difficult to parse as they don't contain much extra information (such as what the input data was). A typical log looks like this: ``` 314537 reads; of these: 314537 (100.00%) were paired; of these: 111016 (35.30%) aligned concordantly 0 times 193300 (61.46%) aligned concordantly exactly 1 time 10221 (3.25%) aligned concordantly >1 times ---- 111016 pairs aligned concordantly 0 times; of these: 11377 (10.25%) aligned discordantly 1 time ---- 99639 pairs aligned 0 times concordantly or discordantly; of these: 199278 mates make up the pairs; of these: 112779 (56.59%) aligned 0 times 85802 (43.06%) aligned exactly 1 time 697 (0.35%) aligned >1 times 82.07% overall alignment rate ``` The logs are from `STDERR` - some pipelines (such as [Cluster Flow](http://clusterflow.io)) print the command before this, so MultiQC looks to see if this can be recognised in the same file. If not, it takes the filename as the sample name. Bowtie 2 and HISAT2 are used by other tools too, so if your log file contains the word `bisulfite`, MultiQC will assume that this is actually Bismark and ignore the Bowtie 2 or HISAT2 logs. ### File search patterns ```yaml bowtie2: contents: 'reads; of these:' exclude_contents: - bisulfite - HiC-Pro shared: true ``` --- ## BUSCO :::note Assesses genome assembly and annotation completeness. [http://busco.ezlab.org/](http://busco.ezlab.org/) ::: BUSCO v2 provides quantitative measures for the assessment of genome assembly, gene set, and transcriptome completeness, based on evolutionarily-informed expectations of gene content from near-universal single-copy orthologs selected from OrthoDB v9. The module parses the `short_summary_[samplename].txt` files and plots the proportion of BUSCO types found. MultiQC has been tested with output from BUSCO v1.22 - v2. ### File search patterns ```yaml busco: contents: 'BUSCO version is:' fn: short_summary* num_lines: 1 ``` --- ## Bustools :::note Tools for BUS files - a file format for single-cell RNA-seq data designed to facilitate the development of modular workflows for data processing. [https://bustools.github.io/](https://bustools.github.io/) ::: This module parses the report generated by Bustools `inspect`, and expects the file to be named `inspect.json`. This is the default naming pattern when you make use of the [kallisto-bustools wrapper](https://www.kallistobus.tools/). The sample name is set as the name of the directory containing the file. For the rest, this module should work in exactly the same way as all other MultiQC modules. ### File search patterns ```yaml bustools: fn: '*inspect.json' ``` --- ## CCS :::note PacBio tool that generates highly accurate single-molecule consensus reads (HiFi Reads). [https://github.com/PacificBiosciences/ccs](https://github.com/PacificBiosciences/ccs) ::: CCS takes multiple subreads of the same SMRTbell molecule and combines them using a statistical model to produce one highly accurate consensus sequence, also called HiFi read, with base quality values. This tool powers the Circular Consensus Sequencing workflow in SMRT Link. ### File search patterns ```yaml ccs/v4: contents: ZMWs generating CCS max_filesize: 1024 num_lines: 2 ccs/v5: contents: '"id": "ccs_processing"' fn: '*.json' ``` --- ## Cell Ranger :::note Analyzes single cell expression or VDJ data produced by 10X Genomics. [https://support.10xgenomics.com/single-cell-gene-expression/software/pipelines/latest/what-is-cell-ranger](https://support.10xgenomics.com/single-cell-gene-expression/software/pipelines/latest/what-is-cell-ranger) ::: The module summarizes the main information useful for QC, including: - sequencing metrics - mapping metrics - estimated number of cells and reads / cell - UMI counts - mean detect genes per cell - antibody cell counts and distribution Note that information such as clustering and differential expression are not reported. The input files are web summaries generated by Cell Ranger. Expected file names are `*web_summary.html`. Sample IDs are parsed directly from the reports and the module will automatically recognize if they are generated from VDJ or count analysis. If present in the original report, any warning is reported as well. ### File search patterns ```yaml cellranger/count_html: - contents: '"command":"Cell Ranger","subcommand":"count"' fn: '*.html' num_lines: 20 - contents: '"command": "Cell Ranger", "subcommand": "count"' fn: '*.html' num_lines: 20 cellranger/vdj_html: - contents: '"command":"Cell Ranger","subcommand":"vdj"' fn: '*.html' num_lines: 20 - contents: '"command": "Cell Ranger", "subcommand": "vdj"' fn: '*.html' num_lines: 20 ``` --- ## Cell Ranger ARC :::note Analyzes single-cell multiome ATAC and gene expression data produced by 10X Genomics. [https://www.10xgenomics.com/support/software/cell-ranger-arc/latest](https://www.10xgenomics.com/support/software/cell-ranger-arc/latest) ::: The module summarizes the main information from Cell Ranger ARC which is useful for QC: - sequencing metrics - cell metrics - targeting metrics - mapping metrics - atac TSS plots - atac insert size distribution plots - gex saturaiton plots - gex genes per cell plots Note that information such as clustering and differential expression are not reported. The input files are web summaries generated by Cell Ranger ARC. Expected file names are `*web_summary.html`. Sample IDs are parsed directly from the reports. If present in the original report, any warning is reported as well. ### File search patterns ```yaml cellranger_arc: - contents: Cell Ranger ARC fn: '*.html' num_lines: 250 ``` --- ## cells2stats :::note Generate output files and statistics from Element Biosciences Teton cytoprofiling assays. [https://docs.elembio.io/docs/cells2stats/introduction/](https://docs.elembio.io/docs/cells2stats/introduction/) ::: ### File search patterns ```yaml cells2stats/run: contents: '"AnalysisID": "c2s.' fn: RunStats.json num_lines: 100 ``` --- ## CheckAtlas :::note A one-liner tool for quality control of your single-cell atlases. [https://github.com/becavin-lab/checkatlas](https://github.com/becavin-lab/checkatlas) ::: CheckAtlas is a one-liner tool to check the quality of your single-cell atlases. For every atlas, it produces quality control tables and figures which can then be processed by MultiQC. CheckAtlas is able to load Scanpy, Seurat, and CellRanger files. MultiQC parses the following tables produced by CheckAtlas: - `summary/sample_name.tsv` - Summary tables with general information on atlases - `adata/sample_name.tsv` - Table with all scanpy adata features - `qc/sample_name.tsv` - Quality control tables for every atlas - `cluster/sample_name.tsv` - Table with cluster metrics calculated for every atlas - `annot/sample_name.tsv` - Table with annotation metrics calculated for every atlas - `dimred/sample_name.tsv` - Table with dimensionality reduction metrics calculated for every atlas ### File search patterns ```yaml checkatlas/adata: contents_re: ^atlas_obs\tobsm\tvar\tvarm\tuns fn: '*.tsv' num_lines: 1 checkatlas/annotation: contents_re: ^Annot_Sample\tReference\tobs fn: '*.tsv' num_lines: 1 checkatlas/cluster: contents_re: ^Clust_Sample\tobs fn: '*.tsv' num_lines: 1 checkatlas/dimred: contents_re: ^Dimred_Sample\tobsm fn: '*.tsv' num_lines: 1 checkatlas/qc: contents_re: cellrank_(total_counts|n_genes_by_counts|pct_counts_mt) fn: '*.tsv' num_lines: 1 checkatlas/summary: contents_re: ^AtlasFileType\tNbCells\tNbGenes fn: '*.tsv' num_lines: 1 ``` --- ## CheckM :::note Estimates genome completeness and contamination based on the presence or absence of marker genes. [https://github.com/Ecogenomics/CheckM](https://github.com/Ecogenomics/CheckM) ::: The module parses the output files generated by CheckM. It will only parse an output file from `checkm lineage_wf`, `checkm taxonomy_wf`, and `checkm qa`. The output file needs to be in format 1 (`-o 1`). All statistics for all samples are saved to `multiqc_data/checkm-table.txt`. Tested with CheckM v1.2.1 ### File search patterns ```yaml checkm: - contents_re: ".*Bin Id(?:\t| {3,})Marker lineage(?:\t| {3,})# genomes(?:\t| {3,})#\ \ markers(?:\t| {3,})# marker sets.*" num_lines: 10 ``` --- ## CheckM2 :::note Assesses microbial genome quality using machine learning. [https://github.com/chklovski/CheckM2](https://github.com/chklovski/CheckM2) ::: The module parses the `quality_report.tsv` files generated by CheckM2. All statistics for all samples are saved to `multiqc_data/checkm2-first-table.txt`. Tested with CheckM2 v1.0.1 and v1.0.2 ### File search patterns ```yaml checkm2: contents: "Name\tCompleteness\tContamination\tCompleteness_Model_Used\tTranslation_Table_Used" num_lines: 10 ``` --- ## CheckQC :::note Checks a set of quality criteria against an Illumina runfolder. [https://github.com/Molmed/checkQC](https://github.com/Molmed/checkQC) ::: The module parses a CheckQC JSON file, so make sure to use CheckQC with the `--json` flag and collect the stdout in a file. ### File search patterns ```yaml checkqc: contents: instrument_and_reagent_type fn: '*.json' ``` --- ## ClipAndMerge :::note Adapter clipping and read merging for ancient DNA data. [http://www.github.com/apeltzer/ClipAndMerge](http://www.github.com/apeltzer/ClipAndMerge) ::: Note that the versions < 1.7.8 use the basename of the file path to distinguish samples, whereas newer versions produce logfiles with a sample identifer that gets parsed by MultiQC. ### File search patterns ```yaml clipandmerge: contents: ClipAndMerge ( num_lines: 5 ``` --- ## Cluster Flow :::note Simple and flexible bioinformatics pipeline tool. [http://clusterflow.io](http://clusterflow.io) ::: The module for Cluster Flow parses `*_clusterflow.txt` logs and finds consensus commands executed by modules in each pipeline run. The Cluster Flow `*.run` files are also parsed and pipeline information shown (some basic statistics plus the pipeline steps / params used). ### File search patterns ```yaml clusterflow/logs: fn: '*_clusterFlow.txt' shared: true clusterflow/runfiles: contents: Cluster Flow Run File fn: '*.run' num_lines: 2 ``` --- ## Conpair :::note Estimates concordance and contamination for tumor–normal pairs. [https://github.com/nygenome/Conpair](https://github.com/nygenome/Conpair) ::: Useful for tumor-normal studies. Performs concordance verification (= samples coming from the same individual), and cross-individual contamination level estimation in WGS and WES sequencing experiments ### File search patterns ```yaml conpair/concordance: contents: markers (coverage per marker threshold num_lines: 3 conpair/contamination: contents: 'Tumor sample contamination level: ' num_lines: 3 ``` --- ## Cutadapt :::note Finds and removes adapter sequences, primers, poly-A tails, and other types of unwanted sequences. [https://cutadapt.readthedocs.io/](https://cutadapt.readthedocs.io/) ::: This module should be able to parse logs from a wide range of versions of Cutadapt. It works with both the regular Cutadapt report output and also with [JSON reports (`--json`)](https://cutadapt.readthedocs.io/en/latest/guide.html#json-report). Although the module parsing code works with very old log files, if you are working with ancient versions (such as v1.2) you may need to change the search pattern to the following: ```yaml sp: cutadapt: contents: "cutadapt version" ``` See the [module search patterns](../getting_started/config#module-search-patterns) section of the MultiQC documentation for more information. The module also understands logs saved by Trim Galore, which contain cutadapt logs. ### File search patterns ```yaml cutadapt: - contents: This is cutadapt exclude_contents_re: 'Trim Galore version: (?:[2-9]|\d{2,})\.' num_lines: 100 - contents: Cutadapt report fn: '*.json' ``` --- ## DamageProfiler :::note DNA damage pattern retrieval for ancient DNA analysis. [https://github.com/Integrative-Transcriptomics/DamageProfiler](https://github.com/Integrative-Transcriptomics/DamageProfiler) ::: ### File search patterns ```yaml damageprofiler: fn: '*dmgprof.json' ``` --- ## Deacon :::note Search and depletion of FASTA/FASTQ files and streams using accelerated minimizer matching. [https://github.com/bede/deacon](https://github.com/bede/deacon) ::: [Deacon](https://github.com/bede/deacon) filters DNA sequences in FASTA/Q files and streams using SIMD-accelerated minimizer comparison against an indexed query. It can either keep matching sequences (search mode, default) or remove them (depletion mode, `-d` / `--deplete`). Built with panhuman host depletion in mind but useful for searching large sequence collections. This module parses the JSON summary log written by `deacon filter` when called with `-s` / `--summary`, and reports the number of input, kept, and removed sequences and base pairs alongside the filter mode. ## Generating compatible output The module looks for the JSON summary file produced by the `--summary` (`-s`) option: ```bash # Search mode: keep matching reads deacon filter index.idx reads.fq.gz -o matches.fq.gz -s summary.json # Depletion mode: remove matching reads (e.g. host depletion) deacon filter -d panhuman-1.k31w15.idx reads.fq.gz -o depleted.fq.gz -s summary.json ``` ## Interpreting results `seqs_removed` and `bp_removed` count sequences and base pairs that matched the indexed query and were therefore filtered out. In depletion mode (`Deplete = True`) these are typically host reads to discard; in search mode they are non-target reads. The `Deplete` column distinguishes the two modes so the same report can mix search and depletion samples. ### File search patterns ```yaml deacon: contents: '"version": "deacon' fn: '*.json' num_lines: 30 ``` --- ## DeDup :::note Improved Duplicate Removal for merged/collapsed reads in ancient DNA analysis. [http://www.github.com/apeltzer/DeDup](http://www.github.com/apeltzer/DeDup) ::: By default, tables show read counts in thousands. To customise this, you can set the following MultiQC config variables: ```yaml ancient_read_count_prefix: "K" ancient_read_count_desc: "thousands" ancient_read_count_multiplier: 0.001 ``` ### File search patterns ```yaml dedup: contents: '"tool_name": "DeDup"' fn: '*.json' num_lines: 20 ``` --- ## deepTools :::note Tools to process and analyze deep sequencing data. [http://deeptools.readthedocs.io](http://deeptools.readthedocs.io) ::: deepTools addresses the challenge of handling the large amounts of data that are now routinelygenerated from DNA sequencing centers. deepTools contains useful modules to process the mapped reads data for multiple quality checks, creating **normalized coverage files** in standard bedGraph and bigWig file formats, that allow comparison between different files (for example, treatment and control). Finally, using such normalized and standardized files, deepTools can create many publication-ready **visualizations** to identify enrichments and for functional annotations of the genome. The module for deepTools parses a number of the text files that deepTools can produce. In particular, the following are supported: - `bamPEFragmentSize --table` - `bamPEFragmentSize --outRawFragmentLengths` - `estimateReadFiltering` - `plotCoverage ---outRawCounts` (as well as the content written normally to the console) - `plotEnrichment --outRawCounts` - `plotFingerprint --outQualityMetrics --outRawCounts` - `plotPCA --outFileNameData` - `plotCorrelation --outFileCorMatrix` - `plotProfile --outFileNameData` Please be aware that some tools (namely, `plotFingerprint --outRawCounts` and `plotCoverage --outRawCounts`) are only supported as of deepTools version 2.6. For earlier output from `plotCoverage --outRawCounts`, you can use `#'chr' 'start' 'end'` in `search_patterns.yaml` (see [here](../getting_started/config#module-search-patterns) for more details). Also for these types of files, you may need to increase the maximum file size supported by MultiQC (`log_filesize_limit` in the MultiQC configuration file). You can find details regarding the configuration file location [here](../getting_started/config). Note that sample names are parsed from the text files themselves, they are not derived from file names. ### File search patterns ```yaml deeptools/bamPEFragmentSizeDistribution: contents: '#bamPEFragmentSize' num_lines: 1 deeptools/bamPEFragmentSizeTable: contents: "\tFrag. Sampled\tFrag. Len. Min.\tFrag. Len. 1st. Qu.\tFrag. Len. Mean\t\ Frag. Len. Median\tFrag. Len. 3rd Qu." num_lines: 1 deeptools/estimateReadFiltering: contents: "Sample\tTotal Reads\tMapped Reads\tAlignments in blacklisted regions\t\ Estimated mapped reads" num_lines: 1 deeptools/plotCorrelationData: contents: '#plotCorrelation --outFileCorMatrix' num_lines: 1 deeptools/plotCoverageOutRawCounts: contents: '#plotCoverage --outRawCounts' num_lines: 1 deeptools/plotCoverageStdout: contents: "sample\tmean\tstd\tmin\t25%\t50%\t75%\tmax" num_lines: 1 deeptools/plotEnrichment: contents: "file\tfeatureType\tpercent\tfeatureReadCount\ttotalReadCount" num_lines: 1 deeptools/plotFingerprintOutQualityMetrics: contents: "Sample\tAUC\tSynthetic AUC\tX-intercept\tSynthetic X-intercept\tElbow\ \ Point\tSynthetic Elbow Point" num_lines: 1 deeptools/plotFingerprintOutRawCounts: contents: '#plotFingerprint --outRawCounts' num_lines: 1 deeptools/plotPCAData: contents: '#plotPCA --outFileNameData' num_lines: 1 deeptools/plotProfile: contents: bin labels num_lines: 1 ``` --- ## DIAMOND :::note Sequence aligner for protein and translated DNA searches, a drop-in replacement for the NCBI BLAST. [https://github.com/bbuchfink/diamond](https://github.com/bbuchfink/diamond) ::: Key features are: - Pairwise alignment of proteins and translated DNA at 100x-10,000x speed of BLAST. - Frameshift alignments for long read analysis. - Low resource requirements and suitable for running on standard desktops or laptops. - Various output formats, including BLAST pairwise, tabular and XML, as well as taxonomic classification. The module takes summary statistics from the `diamond.log` file (`--log` option). It parses and reports the number of sequences aligned and displays them in the General Stats table. ### File search patterns ```yaml diamond: fn: diamond.log ``` --- ## Disambiguate :::note Disambiguate reads aligned to two different species (e.g. human and mouse). [https://github.com/AstraZeneca-NGS/disambiguate](https://github.com/AstraZeneca-NGS/disambiguate) ::: ### File search patterns ```yaml disambiguate: contents: unique species A pairs num_lines: 2 ``` --- ## DRAGEN :::note Illumina Bio-IT Platform that uses FPGA for secondary analysis of sequencing data. [https://www.illumina.com/products/by-type/informatics-products/dragen-bio-it-platform.html](https://www.illumina.com/products/by-type/informatics-products/dragen-bio-it-platform.html) ::: DRAGEN has a number of different pipelines and outputs, including base calling, DNA and RNA alignment, post-alignment processing and variant calling, covering virtually all stages of typical NGS data processing. For each stage, it generates QC files with metrics resembling those of samtools-stats, mosdepth, bcftools-stats and alike. This MultiQC module supports some of the output but not all. Contributions are welcome! - `.wgs_fine_hist_.csv` - Coverage distribution and cumulative coverage plots - `.mapping_metrics.csv` - General stats table, a dedicated table, and a few barplots - `.wgs_coverage_metrics_.csv` - General stats table and a dedicated table - `.qc-coverage-region-<1|2|3>_coverage_metrics.csv` - General stats table and a dedicated table - `.wgs_contig_mean_cov_.csv` - A histogram like in mosdepth, with each chrom as a category on X axis, plus a category for autosomal chromosomes average - `.fragment_length_hist.csv` - A histogram plot - `.ploidy_estimation_metrics.csv` - Add just Ploidy estimation into the general stats table - `.vc_metrics.csv` - A dedicated table and the total number of Variants into the general stats table - `.gc_metrics.csv` - A histogram and summary statistics table on GC content metrics - `.trimmer_metrics.csv` - A summary table of tirmmer metrics - `.time_metrics.metrics` - A bar graph of the total run time and a breakdown of the run time of each individual step - `.quant.metrics.csv` - A bar graph of RNA fragments - `.quant.transcript_coverage.txt` - A line plot of average coverage along RNA transcripts - `.scRNA.metrics.csv` or `.scRNA_metrics.csv` - Summary table for single-cell RNA metrics - `.scATAC.metrics.csv` or `.scATAC_metrics.csv` - Summary table for single-cell ATAC metrics The code is structured in a way so every mix-in parses one type of QC file that DRAGEN generates (e.g. *.mapping_metrics.csv, *.wgs_fine_hist_normal.csv, etc.). If a corresponding file is found, a mix-in adds a section into the report. DRAGEN can be treated as a fast aligner with additional features on top, as users will unlikely use any features without enabling DRAGEN mapping. So we will treat this module as an alignment tool module and place it accordingly in the module_order list, in docs, etc. ### File search patterns ```yaml dragen/coverage_metrics: fn_re: .*_coverage_metrics.*\.csv dragen/fragment_length_hist: fn: '*.fragment_length_hist.csv' dragen/gc_metrics: fn: '*.gc_metrics.csv' dragen/gvcf_metrics: fn: '*.gvcf_metrics.csv' dragen/mapping_metrics: contents: Number of unique reads (excl. duplicate marked reads) fn: '*.mapping_metrics.csv' num_lines: 50 dragen/overall_mean_cov_metrics: fn_re: .*_overall_mean_cov.*\.csv dragen/ploidy_estimation_metrics: fn: '*.ploidy_estimation_metrics.csv' dragen/rna_quant_metrics: fn: '*.quant[._]metrics.csv' dragen/rna_transcript_cov: fn: '*.quant.transcript_coverage.txt' dragen/sc_atac_metrics: fn: '*.scATAC[._]metrics.csv' dragen/sc_rna_metrics: fn: '*.scRNA[._]metrics.csv' dragen/time_metrics: fn: '*.time_metrics.csv' dragen/trimmer_metrics: fn: '*.trimmer_metrics.csv' dragen/vc_metrics: fn: '*.vc_metrics.csv' dragen/wgs_contig_mean_cov: fn_re: .*\.wgs_contig_mean_cov_?(tumor|normal)?\.csv dragen/wgs_fine_hist: fn_re: .*\.wgs_fine_hist_?(tumor|normal)?\.csv ``` --- ## DRAGEN-FastQC :::note Illumina Bio-IT Platform that uses FPGA for secondary analysis of sequencing data. [https://www.illumina.com/products/by-type/informatics-products/dragen-bio-it-platform.html](https://www.illumina.com/products/by-type/informatics-products/dragen-bio-it-platform.html) ::: DRAGEN has a number of different pipelines and outputs, including base calling, DNA and RNA alignment, and many others. Starting with the release of DRAGEN v3.6, it also supports primary analysis of sequencing data, modelled after the QC metrics generated by the widely used FastQC tool. This module parses the output from that hardware-accelerated QC tool, and uses it to generate similar plots to both FastQC and MultiQC's current FastQC module. These plots are presented in their own section and module, such that they can be run indepedently or in conjunction with other MultiQC DRAGEN modules as desired. - `.fastqc_metrics.csv` - Pre-calculated positional QV quantiles - Mean QVs by read position and base - A histogram of estimated read-level qualities - A histogram of read lengths - A smoothed histogram of sample GC content - Average read quality values for each GC content bin - Positional prevalence of ambiguous bases - Positional base content - Adapter/Kmer sequence start positions #### Quality score box plots By default, the box plots showing the range of quality scores are only shown if there are maximum 2 samples in the report. You can change this threshold with the following MultiQC config (eg. to max 10 samples): ```yaml dragen_fastqc: quality_range_boxplots_max_samples: 10 ``` If you prefer, you can force MultiQC to generate these box plots for _all_ samples using the following configuration: ```yaml dragen_fastqc: force_quality_range_boxplots: true ``` ### File search patterns ```yaml dragen_fastqc: fn: '*.fastqc_metrics.csv' ``` --- ## eigenstratdatabasetools :::note Tools to compare and manipulate the contents of EingenStrat databases, and to calculate SNP coverage statistics in such databases. [https://github.com/TCLamnidis/EigenStratDatabaseTools](https://github.com/TCLamnidis/EigenStratDatabaseTools) ::: ### File search patterns ```yaml eigenstratdatabasetools: fn: '*_eigenstrat_coverage.json' ``` --- ## fastp :::note All-in-one FASTQ preprocessor (QC, adapters, trimming, filtering, splitting...). [https://github.com/OpenGene/fastp](https://github.com/OpenGene/fastp) ::: Fastp goes through fastq files in a folder and perform a series of quality control and filtering. Quality control and reporting are displayed both before and after filtering, allowing for a clear depiction of the consequences of the filtering process. Notably, the latter can be conducted on a variety of parameters including quality scores, length, as well as the presence of adapters, polyG, or polyX tailing. The module also supports [fasterp](https://github.com/drbh/fasterp), a Rust reimplementation of fastp that produces identical JSON output. When a `fasterp_version` field is found in the summary, the software version is tracked separately as fasterp. By default, the module generates the sample names based on the `--report_title` / `-R` option in the fastp command line (if present), or the input FastQ file names if not. If you prefer, you can tell the module to use the filenames as sample names instead. To do so, use the following config option: ```yaml use_filename_as_sample_name: - fastp ``` See [Using log filenames as sample names](../getting_started/config#using-log-filenames-as-sample-names) for more details. ### File search patterns ```yaml fastp: contents: '"before_filtering": {' fn: '*.json' num_lines: 50 ``` --- ## FastQ Screen :::note Screens a library of sequences in FastQ format against a set of sequence databases to see if the composition of the library matches with what you expect. [http://www.bioinformatics.babraham.ac.uk/projects/fastq_screen/](http://www.bioinformatics.babraham.ac.uk/projects/fastq_screen/) ::: By default, the module creates a plot that emulates the FastQ Screen output with blue and red stacked bars showing unique and multimapping read counts. This plot only works for a handful of samples however, so if `# samples * # organisms >= 160`, a simpler stacked barplot is shown. This is also shown when generating flat-image plots. To always show this style of plot, add the following line to a MultiQC config file: ```yaml fastqscreen_simpleplot: true ``` ### File search patterns ```yaml fastq_screen: fn: '*_screen.txt' ``` --- ## FastQC :::note Quality control tool for high throughput sequencing data. [http://www.bioinformatics.babraham.ac.uk/projects/fastqc/](http://www.bioinformatics.babraham.ac.uk/projects/fastqc/) ::: FastQC and [Falco](https://github.com/smithlabcode/falco) (a high-performance drop-in replacement) generate an HTML report which is what most people use when they run the program. However, they also helpfully generate a file called `fastqc_data.txt` which is relatively easy to parse. A typical run will produce the following files: ``` mysample_fastqc.html mysample_fastqc/ Icons/ Images/ fastqc.fo fastqc_data.txt fastqc_report.html summary.txt ``` Sometimes the directory is zipped, with just `mysample_fastqc.zip`. The FastQC MultiQC module looks for files called `fastqc_data.txt` or ending in `_fastqc.zip`. If the zip files are found, they are read in memory and `fastqc_data.txt` parsed. :::note The directory and zip file are often both present. To speed up MultiQC execution, zip files will be skipped if the file name suggests that they will share a sample name with data that has already been parsed. ::: You can customise the patterns used for finding these files in your MultiQC config (see [Module search patterns](../getting_started/config#module-search-patterns)). The below code shows the default file patterns: ```yaml sp: fastqc/data: fn: "*fastqc_data.txt" fastqc/zip: fn: "*_fastqc.zip" ``` :::note Sample names are discovered by parsing the line beginning `Filename` in `fastqc_data.txt`, _not_ based on the FastQC report names. ::: #### Theoretical GC Content It is possible to plot a dashed line showing the theoretical GC content for a reference genome. MultiQC comes with genome and transcriptome guides for Human and Mouse. You can use these in your reports by adding the following MultiQC config keys (see [Configuring MultiQC](../getting_started/config)): ```yaml fastqc_config: fastqc_theoretical_gc: "hg38_genome" ``` Only one theoretical distribution can be plotted. The following guides are available: _(txome = transcriptome)_ - `hg38_genome` - `hg38_txome` - `mm10_genome` - `mm10_txome` Alternatively, a custom theoretical guide can be used in reports. To do this, create a file with `fastqc_theoretical_gc` in the filename and place it with your analysis files. It should be tab delimited with the following format (column 1 = %GC, column 2 = % of genome): ```bash # FastQC theoretical GC content curve: YOUR REFERENCE NAME 0 0.005311768 1 0.004108502 2 0.004060371 3 0.005066476 [...] ``` You can generate these files using an R package called [fastqcTheoreticalGC](https://github.com/mikelove/fastqcTheoreticalGC) written by [Mike Love](https://github.com/mikelove). Please see the [package readme](https://github.com/mikelove/fastqcTheoreticalGC) for more details. Result files from this package are searched for with the following search pattern (can be customised as described above): ```yaml sp: fastqc/theoretical_gc: fn: "*fastqc_theoretical_gc*" ``` If you want to always use a specific custom file for MultiQC reports without having to add it to the analysis directory, add the full file path to the same MultiQC config variable described above: ```yaml fastqc_config: fastqc_theoretical_gc: "/path/to/your/custom_fastqc_theoretical_gc.txt" ``` #### Overrepresented sequences The overrepresented sequences table shows the most common sequences found, measured by the number of samples they occur as overrepresented. By default, the table shows top 20 sequences. This can be customised in the config: ```yaml fastqc_config: top_overrepresented_sequences: 50 ``` You can also choose to rank the top sequences by the total number of reads rather than by number of samples: ```yaml fastqc_config: top_overrepresented_sequences_by: "total" ``` #### Changing the order of sections Remember that it is possible to customise the order in which the different module sections appear in the report if you wish. See [the docs](../reports/customisation#order-of-module-and-module-subsection-output) for more information. For example, to show the _Status Checks_ section at the top, use the following config: ```yaml report_section_order: fastqc_status_checks: order: -1000 ``` #### Showing FastQC status checks FastQC uses thresholds to mark samples as "pass", "warn" or "fail" for various checks. If you prefer the MultiQC module to ignore those thresholds, and use standard MultiQC colors for samples instead, use the following config: ```yaml fastqc_config: status_checks: false ``` ### File search patterns ```yaml fastqc/data: fn: '*fastqc_data.txt' fastqc/theoretical_gc: fn: '*fastqc_theoretical_gc*' fastqc/zip: fn: '*_fastqc.zip' ``` --- ## FastQE :::note Uses emoji to represent FASTQ sequence quality scores. [https://github.com/fastqe/fastqe](https://github.com/fastqe/fastqe) ::: FastQE uses emoji to represent FASTQ sequence quality scores, providing a fun and visually intuitive way to assess sequencing data quality. The module parses the tab-separated output from FastQE and displays the emoji quality strings for each sample in the report. **Note** — MultiQC parses the standard output from FastQE. You must capture FastQE stdout to a file when running, for example: ```bash fastqe input.fastq > fastqe_output.txt ``` The saved file must have `fastqe` somewhere in the file name. ### File search patterns ```yaml fastqe: contents: "Filename\tStatistic\tQualities" fn: '*fastqe*' num_lines: 1 ``` --- ## featureCounts :::note Counts mapped reads for genomic features such as genes, exons, promoter, gene bodies, genomic bins and chromosomal locations. [http://subread.sourceforge.net/](http://subread.sourceforge.net/) ::: As of MultiQC v1.10, the module should also work with output from [Rsubread](https://bioconductor.org/packages/release/bioc/html/Rsubread.html). Note that your filenames must end in `.summary` to be discovered. See [Module search patterns](../getting_started/config#module-search-patterns) for how to customise this. Please note that if files are in "Rsubread mode" then lines will be split by any whitespace, instead of tab characters. As such, filenames with spaces in will cause the parsing to fail. ### File search patterns ```yaml featurecounts: fn: '*.summary' shared: true ``` --- ## fgbio :::note Processing and evaluating data containing UMIs. [http://fulcrumgenomics.github.io/fgbio/](http://fulcrumgenomics.github.io/fgbio/) ::: The module currently supports tool the following outputs: - [GroupReadsByUmi](http://fulcrumgenomics.github.io/fgbio/tools/latest/GroupReadsByUmi.html) - [ErrorRateByReadPosition](http://fulcrumgenomics.github.io/fgbio/tools/latest/ErrorRateByReadPosition.html) ### File search patterns ```yaml fgbio/errorratebyreadposition: contents: "read_number\tposition\tbases_total\terrors\terror_rate\ta_to_c_error_rate\t\ a_to_g_error_rate\ta_to_t_error_rate\tc_to_a_error_rate\tc_to_g_error_rate\tc_to_t_error_rate" num_lines: 3 fgbio/groupreadsbyumi: contents: fraction_gt_or_eq_family_size num_lines: 3 ``` --- ## Filtlong :::note Filters long reads by quality. [https://github.com/rrwick/Filtlong](https://github.com/rrwick/Filtlong) ::: It can take a set of long reads and produce a smaller, better subset. It uses both read length (longer is better) and read identity (higher is better) when choosing which reads pass the filter. The module takes summary statistics of number of long reads filtered and displays them in the General Stats table. #### Bases Kept Sometimes, the Filtlong log message contains this: ``` Filtering long reads target: 123456789 bp reads already fall below target after filtering Outputting passed long reads ``` In these cases we cannot say for sure how many bases were kept. As such, this field is left blank. If you have a better solution, please suggest in an issue or pull request. ### File search patterns ```yaml filtlong: contents: Scoring long reads contents_re: .*Filtering long reads.* num_lines: 5 ``` --- ## FLASh :::note Merges paired-end reads from next-generation sequencing experiments. [https://ccb.jhu.edu/software/FLASH/](https://ccb.jhu.edu/software/FLASH/) ::: To create a log file suitable for the module, you can use `tee`. From the FLASh help: ```bash flash reads_1.fq reads_2.fq 2>&1 | tee logfilename.log ``` The sample name is set by the first input filename listed in the log. However, this can be changed to using the first output filename (i.e. if you used FLASh's `--output-prefix=PREFIX` option) by using the following config: ```yaml flash: use_output_name: true ``` The module can also parse the `.hist` numeric histograms output by FLASh. Note that the histogram's file format and extension are too generic by themselves which could result in the accidental parsing a file output by another tool. To get around this, the MultiQC module only parses files with the filename pattern `*flash*.hist`. To customise this (for example, enabling for any file ending in `*.hist`), use the following config change: ```yaml sp: flash/hist: fn: "*.hist" ``` ### File search patterns ```yaml flash/hist: fn: '*flash*.hist' flash/log: contents: '[FLASH]' ``` --- ## Flexbar :::note Barcode and adapter removal tool. [https://github.com/seqan/flexbar](https://github.com/seqan/flexbar) ::: Flexbar efficiently preprocesses high-throughput sequencing data. It demultiplexes barcoded runs and removes adapter sequences. Moreover, trimming and filtering features are provided. Flexbar increases read mapping rates and improves genome as well as transcriptome assemblies. ### File search patterns ```yaml flexbar: contents: Flexbar - flexible barcode and adapter removal ``` --- ## Freyja :::note Recovers relative lineage abundances from mixed SARS-CoV-2 samples. [https://github.com/andersen-lab/Freyja](https://github.com/andersen-lab/Freyja) ::: Freyja is a tool to recover relative lineage abundances from mixed SARS-CoV-2 samples from a sequencing dataset and uses lineage-determining mutational "barcodes" derived from the UShER global phylogenetic tree to solve the constrained (unit sum, non-negative) de-mixing problem. ### File search patterns ```yaml freyja: contents: "summarized\t[" fn: '*.tsv' num_lines: 6 ``` --- ## Ganon :::note Metagenomics classification: quickly assigns sequence fragments to their closest reference among thousands of references via Interleaved Bloom Filters of k-mer/minimizers. [https://pirovc.github.io/ganon/](https://pirovc.github.io/ganon/) ::: The module takes summary statistics from a file containing stdout from `ganon classify`. ### File search patterns ```yaml ganon: contents: - ganon-classify processed num_lines: 100 ``` --- ## GATK :::note Wide variety of tools with a primary focus on variant discovery and genotyping. [https://www.broadinstitute.org/gatk/](https://www.broadinstitute.org/gatk/) ::: Supported tools: - `AnalyzeSaturationMutagenesis` - `BaseRecalibrator` - `VariantEval` #### AnalyzeSaturationMutagenesis [AnalyzeSaturationMutagenesis](https://gatk.broadinstitute.org/hc/en-us/articles/4404604903451-AnalyzeSaturationMutagenesis-BETA-) is a (beta!) tool for counting variants in saturation mutagenesis experiments. It accepts mapped reads and a reference sequence and outputs a number of files for further analysis. #### BaseRecalibrator [BaseRecalibrator](https://software.broadinstitute.org/gatk/documentation/tooldocs/current/org_broadinstitute_gatk_tools_walkers_bqsr_BaseRecalibrator.php) is a tool for detecting systematic errors in read base quality scores of aligned high-throughput sequencing reads. It outputs a base quality score recalibration table that can be used in conjunction with the [PrintReads](https://software.broadinstitute.org/gatk/documentation/tooldocs/current/org_broadinstitute_gatk_tools_walkers_readutils_PrintReads.php) tool to recalibrate base quality scores. #### VariantEval [VariantEval](https://software.broadinstitute.org/gatk/gatkdocs/current/org_broadinstitute_gatk_tools_walkers_varianteval_VariantEval.php) is a general-purpose tool for variant evaluation. It gives information about percentage of variants in dbSNP, genotype concordance, Ti/Tv ratios and a lot more. ### File search patterns ```yaml gatk/analyze_saturation_mutagenesis: contents: '>>Reads in disjoint pairs evaluated separately:' fn: '*.readCounts' num_lines: 10 gatk/base_recalibrator: - contents: '#:GATKTable:Arguments:Recalibration' num_lines: 3 - contents: '#:SENTIEON_QCAL_TABLE:Arguments:Recalibration' num_lines: 3 gatk/varianteval: contents: '#:GATKTable:TiTvVariantEvaluator' ``` --- ## GffCompare :::note Tool to compare, merge and annotate one or more GFF files with a reference annotation in GFF format. [https://ccb.jhu.edu/software/stringtie/gffcompare.shtml](https://ccb.jhu.edu/software/stringtie/gffcompare.shtml) ::: The program `gffcompare` can be used to compare, merge, annotate and estimate accuracy of one or more GFF files (the "query" files), when compared with a reference annotation (also provided as GFF). The _Sensitivity / Precision_ values are displayed in a single plot, different loci levels can be switched by choosing a different dataset. :::warning Please use `gffcompare` only with single samples. Multi-Sample comparisons are not correctly rendered by this MultiQC module. ::: Note that exported data in `multiqc_data/multiqc_gffcompare.{tsv,yaml,json}` only works when exporting with YAML or JSON - the default `.tsv` output will not contain any data. Please use `-k yaml` or `-k json` to export in a structured format. It is hoped to refactor this code in a future release - please submit a PR if you are interested. ### File search patterns ```yaml gffcompare: contents: '# gffcompare' fn: '*.stats' num_lines: 2 ``` --- ## GLIMPSE :::note Low-coverage whole genome sequencing imputation. [https://odelaneau.github.io/GLIMPSE/](https://odelaneau.github.io/GLIMPSE/) ::: The program `GLIMPSE2` is based on the GLIMPSE model and designed for reference panels containing hundreds of thousands of reference samples, with a special focus on rare variants. The concordance rates values are displayed in a scatter plot, with the option to switch between the different concordance metrics. The supported files are generated from the `GLIMPSE2_concordance` command. The following files are supported: - `*.error.spl.txt` - `*.error.grp.txt` ### File search patterns ```yaml glimpse/err_grp: fn: '*.error.grp.txt.gz' num_lines: 1 glimpse/err_spl: fn: '*.error.spl.txt.gz' num_lines: 1 ``` --- ## goleft indexcov :::note Quickly estimate coverage from a whole-genome bam index, providing 16KB resolution. [https://github.com/brentp/goleft/tree/master/indexcov](https://github.com/brentp/goleft/tree/master/indexcov) ::: This is useful as a quick QC to get coverage values across the genome. The module uses the PED and ROC data files to create diagnostic plots of coverage per sample, helping to identify sample gender and coverage issues. By default, we attempt to only plot chromosomes using standard human-like naming (chr1, chr2... chrX or 1, 2 ... X) but you can specify chromosomes for detailed ROC plots for alternative naming schemes in your configuration with: ```yaml goleft_indexcov_config: chromosomes: - I - II - III ``` The number of plotted chromosomes is limited to 50 by default, you can customise this with the following: ```yaml goleft_indexcov_config: max_chroms: 80 ``` ### File search patterns ```yaml goleft_indexcov/ped: fn: '*-indexcov.ped' goleft_indexcov/roc: fn: '*-indexcov.roc' ``` --- ## GoPeaks :::note Calls peaks in CUT&TAG/CUT&RUN datasets. [https://github.com/maxsonBraunLab/gopeaks](https://github.com/maxsonBraunLab/gopeaks) ::: Gopeaks uses a binomial distribution to model the read counts in sliding windows across the genome and calculate peak regions that are enriched over the background. The module recognizes files with the `*_gopeaks.json` suffix (which is the default behavior), and will report the number of peaks called per sample via the general table and the bar plot. ### File search patterns ```yaml gopeaks: fn: '*_gopeaks.json' ``` --- ## GTDB-Tk :::note Assigns objective taxonomic classifications to bacterial and archaeal genomes. [https://ecogenomics.github.io/GTDBTk/index.html](https://ecogenomics.github.io/GTDBTk/index.html) ::: The module parses `summary.tsv` outputs from GTDB-Tk's `classify.py` and `classify_wf.py`. The module only works for version >= 2.4.0 because column names changed. `classify.py` and `classify_wf.py` are used to determine the taxonomic classification of input genomes. ### File search patterns ```yaml gtdbtk: contents: "user_genome\tclassification\tclosest_genome_reference\tclosest_genome_reference_radius\t\ closest_genome_taxonomy\tclosest_genome_ani" num_lines: 10 ``` --- ## Haplocheck :::note Detects in-sample contamination in mtDNA or WGS sequencing studies by analyzing the mitchondrial content. [https://github.com/genepi/haplocheck/](https://github.com/genepi/haplocheck/) ::: ### File search patterns ```yaml haplocheck: contents: "\"Sample\"\t\"Contamination Status\"\t\"Contamination Level\"\t\"Distance\"\ \t\"Sample Coverage\"" num_lines: 10 ``` --- ## hap.py :::note Benchmarks variant calls against gold standard truth datasets. [https://github.com/Illumina/hap.py](https://github.com/Illumina/hap.py) ::: Som.py output supported in separate sompy module. ### File search patterns ```yaml happy: contents: Type,Filter,TRUTH fn: '*.summary.csv' ``` --- ## HiCExplorer :::note Hi-C analysis from processing to visualization. [https://hicexplorer.readthedocs.io](https://hicexplorer.readthedocs.io) ::: The module parses results generated by HiCExplorere's hicBuildMatrix, a subtool to create an interaction matrix out of mapped Hi-C reads. ### File search patterns ```yaml hicexplorer: contents: Min rest. site distance max_filesize: 4096 num_lines: 26 ``` --- ## HiC-Pro :::note Pipeline for Hi-C data processing. [https://github.com/nservant/HiC-Pro](https://github.com/nservant/HiC-Pro) ::: **Note** - because this module shares sample identifiers across multiple files, the `--fn_as_s_name` / `config.use_filename_as_sample_name` functionality has been disabled and has no effect. The MultiQC module is supported since HiC-Pro v2.11.0. ### File search patterns ```yaml hicpro/assplit: fn: '*assplit.stat' hicpro/mRSstat: contents: Valid_interaction_pairs fn: '*RSstat' hicpro/mergestat: contents: valid_interaction fn: '*.mergestat' num_lines: 10 hicpro/mmapstat: contents: total_R fn: '*mapstat' num_lines: 10 hicpro/mpairstat: contents: Total_pairs_processed fn: '*pairstat' num_lines: 10 ``` --- ## hicstuff :::note Hi-C pipeline that generates contact maps from sequencing reads. [https://github.com/koszullab/hicstuff](https://github.com/koszullab/hicstuff) ::: The module parses two file types from the [hicstuff](https://github.com/koszullab/hicstuff) Hi-C pipeline: - **Pipeline log files** (`*.log`, `*.txt`), identified by the `## hicstuff:` header line. The end-of-run summary stats dictionary feeds the General Statistics table and the Read Fate stacked bar plot. - **Distance law tables** (default `distance_law.txt`, also commonly seen with `.tsv` extensions), identified by a `## distance_law` header. These drive the P(s) contact-probability line graph and its log-log slope plot. hicstuff writes a summary stats dictionary to the log at the end of each run: ``` ## hicstuff: v3.2.2 log file ## date: 2024-02-16 14:00:23 ## enzyme: DpnII,HinfI ## input1: ../tinyMapper/tests/testHiC_R1.fq.gz ## input2: ../tinyMapper/tests/testHiC_R2.fq.gz ## ref: /home/rsg/genomes/S288c/S288c.fa --- ... 2024-02-16,14:00:43 :: INFO :: 77% reads (single ends) mapped with Q >= 30 (154272/200000) 2024-02-16,14:00:44 :: INFO :: 66943 pairs successfully mapped (66.94%) 2024-02-16,14:00:46 :: INFO :: Fetching mapping and pairing stats 2024-02-16,14:00:46 :: INFO :: {'Sample': 'testHiC^CGNT57', 'Total read pairs': 100000, 'Mapped reads': 154272, 'Unmapped reads': 45728, 'Recovered contacts': 66943, 'Final contacts': 66943, 'Removed contacts': 0, 'Filtered out': 0, 'Loops': 0, 'Uncuts': 0, 'Weirds': 0, 'PCR duplicates': 0} 2024-02-16,14:00:46 :: INFO :: Contact map generated after 0h 0m 23s ``` ### File search patterns ```yaml hicstuff/distancelaw: contents: '## distance_law' num_lines: 5 hicstuff/pipeline_stats: - contents: '## hicstuff:' fn: '*.txt' num_lines: 100 - contents: '## hicstuff:' fn: '*.log' num_lines: 10 ``` --- ## HiCUP :::note Mapping and quality control on Hi-C data. [http://www.bioinformatics.babraham.ac.uk/projects/hicup/](http://www.bioinformatics.babraham.ac.uk/projects/hicup/) ::: ### File search patterns ```yaml hicup: fn: HiCUP_summary_report* hicup/html: fn: '*HiCUP_summary_report*.html' ``` --- ## HiFi-Trimmer :::note Filters and trims adapter sequences from HiFi reads using BLAST. [https://github.com/sanger-tol/hifi-trimmer](https://github.com/sanger-tol/hifi-trimmer) ::: Parse HiFi-Trimmer JSON summaries and optionally merge sample totals from matching samtools stats reports. ### File search patterns ```yaml hifi_trimmer: contents: '"total_reads_trimmed"' fn: '*.json' num_lines: 10 ``` --- ## HiFiasm :::note Haplotype-resolved assembler for accurate Hifi reads. [https://github.com/chhylp123/hifiasm](https://github.com/chhylp123/hifiasm) ::: ### File search patterns ```yaml hifiasm: contents: '[M::ha_analyze_count]' num_lines: 1 ``` --- ## HISAT2 :::note Maps DNA or RNA reads against a genome or a population of genomes. [https://ccb.jhu.edu/software/hisat2/](https://ccb.jhu.edu/software/hisat2/) ::: The module parses summary statistics generated by versions >= v2.1.0 where the command line option `--new-summary` has been specified. Note that running HISAT2 without this option (and older versions) gives log output identical to Bowtie2. These logs are indistinguishable and summary statistics will appear in MultiQC reports labelled as Bowtie2. See GitHub issues on the [HISAT2 repository](https://github.com/infphilo/hisat2/issues/48) and the [MultiQC repository](https://github.com/MultiQC/MultiQC/issues/221) for more information. HISAT2 does not report the input file names in the log, so MultiQC takes the filename as the sample. Note that if you specify `--summary-file` when running HISAT2 the same summary output appears both there and in the `stdout`. So if you save both with different names you may end up with duplicate samples in your MultiQC report. ### File search patterns ```yaml hisat2: contents: 'HISAT2 summary stats:' ``` --- ## HOMER :::note Motif discovery and next-gen sequencing analysis. [http://homer.ucsd.edu/homer/](http://homer.ucsd.edu/homer/) ::: HOMER contains many useful tools for analyzing ChIP-Seq, GRO-Seq, RNA-Seq, DNase-Seq, Hi-C and numerous other types of functional genomics sequencing data sets. The module currently only parses output from the `findPeaks` and `TagDirectory` tools. If you would like support to be added for other HOMER tools please open a [new issue](https://github.com/MultiQC/MultiQC/issues/new) on the MultiQC GitHub page. #### FindPeaks The HOMER findPeaks MultiQC module parses the summary statistics found at the top of HOMER peak files. Three key statistics are shown in the General Statistics table, all others are saved to `multiqc_data/multiqc_homer_findpeaks.txt`. #### TagDirectory The HOMER tag directory submodule parses output from files [tag directory](http://homer.ucsd.edu/homer/ngs/tagDir.html) output files, generating a number of diagnostic plots. ### File search patterns ```yaml homer/FreqDistribution: fn: petag.FreqDistribution_1000.txt homer/GCcontent: fn: tagGCcontent.txt homer/LengthDistribution: fn: tagLengthDistribution.txt homer/RestrictionDistribution: fn: petagRestrictionDistribution.*.txt homer/findpeaks: contents: '# HOMER Peaks' num_lines: 3 homer/genomeGCcontent: fn: genomeGCcontent.txt homer/tagInfo: fn: tagInfo.txt ``` --- ## HOPS :::note Ancient DNA characteristics screening tool of output from the metagenomic aligner MALT. [https://github.com/rhuebler/HOPS/](https://github.com/rhuebler/HOPS/) ::: This module takes the JSON output of the HOPS postprocessing R script (version >= 0.34) to recreate the possible positives heatmap, with the heat intensity representing the number of 'ancient DNA characteristics' categories (small edit distance, damage, both edit distance and aDNA damage) that a particular taxon has. ### File search patterns ```yaml hops: fn: heatmap_overview_Wevid.json ``` --- ## Hostile :::note Removes host sequences from short and long read (meta)genomes, from paired or unpaired fastq[.gz]. [https://github.com/bede/hostile](https://github.com/bede/hostile) ::: Hostile write the log in JSON format. Which is being used to generate the report. ```log $ hostile clean --fastq1 human_1_1.fastq.gz --fastq2 human_1_2.fastq.gz >log.json INFO: Hostile version 1.0.0. Mode: paired short read (Bowtie2) INFO: Found cached standard index human-t2t-hla INFO: Cleaning… INFO: Cleaning complete ``` ## JSON output ```log.json [ { "version": "1.0.0", "aligner": "bowtie2", "index": "human-t2t-hla", "options": [], "fastq1_in_name": "human_1_1.fastq.gz", "fastq1_in_path": "/path/to/human_1_1.fastq.gz", "fastq1_out_name": "human_1_1.clean_1.fastq.gz", "fastq1_out_path": "/path/to/human_1_1.clean_1.fastq.gz", "reads_in": 2, "reads_out": 0, "reads_removed": 2, "reads_removed_proportion": 1.0, "fastq2_in_name": "human_1_2.fastq.gz", "fastq2_in_path": "/path/to/human_1_2.fastq.gz", "fastq2_out_name": "human_1_2.clean_2.fastq.gz", "fastq2_out_path": "/path/to/human_1_2.clean_2.fastq.gz" } ] ``` A barplot using the JSON reports from different samples. Plot will shows the number of reads classified as host-reads vs cleaned-reads (non-host reads). ### File search patterns ```yaml hostile: contents: '"reads_removed_proportion"' fn: '*.json' num_lines: 100 ``` --- ## HTSeq Count :::note Part of the HTSeq package: counts reads covering specified genomic features. [https://htseq.readthedocs.io/en/master/htseqcount.html](https://htseq.readthedocs.io/en/master/htseqcount.html) ::: HTSeq is a general purpose Python package that provides infrastructure to process data from high-throughput sequencing assays. `htseq-count` is a tool that is part of the main HTSeq package - it takes a file with aligned sequencing reads, plus a list of genomic features and counts how many reads map to each feature. ### File search patterns ```yaml htseq: - contents_re: ^feature\tcount$ num_lines: 1 shared: true - contents_re: ^\w+.*\t\d+$ num_lines: 1 shared: true ``` --- ## HUMID :::note Reference-free tool to quickly remove duplicates from FastQ files, with or without UMIs. [https://github.com/jfjlaros/HUMID](https://github.com/jfjlaros/HUMID) ::: ### File search patterns ```yaml humid/clusters: contents_re: '[0-9]+ [0-9]+' fn: clusters.dat num_lines: 1 humid/counts: contents_re: '[0-9]+ [0-9]+' fn: counts.dat num_lines: 1 humid/neighbours: contents_re: '[0-9]+ [0-9]+' fn: neigh.dat num_lines: 1 humid/stats: contents: 'total: ' fn: stats.dat num_lines: 1 ``` --- ## Illumina InterOp Statistics :::note Reading and writing InterOp metric files. [http://illumina.github.io/interop/index.html](http://illumina.github.io/interop/index.html) ::: The Illumina InterOp libraries are a set of common routines used for reading and writing InterOp metric files. These metric files are binary files produced during a run providing detailed statistics about a run. In a few cases, the metric files are produced after a run during secondary analysis (index metrics) or for faster display of a subset of the original data (collapsed quality scores). This module parses the output from the InterOp Summary executable and creates a table view. The aim is to replicate the `Run & Lane Metrics` table from the [Illumina Basespace](https://basespace.illumina.com) interface. The executable used can easily be installed from the Bioconda channel using `conda install -c bioconda illumina-interop`. The MultiQC interop module can parse the outputs of the `interop_summary` and `interop_index-summary` executables. Note that these must be run with the `--csv=1` option. ### File search patterns ```yaml interop/index-summary: contents: Total Reads,PF Reads,% Read Identified (PF),CV,Min,Max interop/summary: contents: Level,Yield,Projected Yield,Aligned,Error Rate,Intensity C1,%>=Q30 ``` --- ## Iso-Seq :::note Identifies transcripts in PacBio single-molecule sequencing data (HiFi reads). [https://github.com/PacificBiosciences/IsoSeq](https://github.com/PacificBiosciences/IsoSeq) ::: Supports outputs generated by two commands: - [IsoSeq `refine`](https://github.com/PacificBiosciences/IsoSeq/blob/master/isoseq-clustering.md#step-3---refine) trims poly(A) tails and removes concatemers. - [IsoSeq `cluster`](https://github.com/PacificBiosciences/IsoSeq/blob/master/isoseq-clustering.md#step-4---clustering) performs clustering using hierarchical n*log(n) alignment and iterative cluster merging. ### File search patterns ```yaml isoseq/cluster-csv: contents: cluster_id fn: '*cluster_report.csv' num_lines: 1 isoseq/refine-csv: contents: id,strand,fivelen,threelen,polyAlen,insertlen,primer fn: '*.csv' isoseq/refine-json: contents: '"num_reads_fl"' fn: '*.json' ``` --- ## iVar :::note Functions for viral amplicon-based sequencing. [https://github.com/andersen-lab/ivar](https://github.com/andersen-lab/ivar) ::: This module parses the output from the `ivar trim` command and creates a table view. Both output from V1 and V2 of the tool are supported and parsed accordingly. ### File search patterns ```yaml ivar/trim: contents: Number of references num_lines: 8 ``` --- ## JCVI Genome Annotation :::note Computes statistics on genome annotation. [https://pypi.org/project/jcvi/](https://pypi.org/project/jcvi/) ::: The JCVI module parses the output of `python -m jcvi.annotation.stats genestats `. The file name is used as the sample name. If the output from the `python -m jcvi.annotation.stats stats ` is present in the same directory, it is used to draw complementary plots. A typical result directory will contain: ``` ├── Exon_Count │   ├── sample1.txt │   └── sample2.txt ├── Exon_Length │   ├── sample1.txt │   └── sample2.txt ├── Gene_Length │   ├── sample1.txt │   └── sample2.txt ├── Intron_Length │   ├── sample1.txt │   └── sample2.txt ├── sample1_genestats.txt └── sample2_genestats.txt ``` The JCVI module has been tested with output from JCVI v1.0.9. ### File search patterns ```yaml jcvi: contents: ' o % GC % of genome Average size (bp) Median size (bp) Number Total length (Mb)' ``` --- ## Jellyfish :::note Counting k-mers in DNA. [https://github.com/gmarcais/Jellyfish](https://github.com/gmarcais/Jellyfish) ::: A k-mer is a substring of length k, and counting the occurrences of all such substrings is a central step in many analyses of DNA sequence. JELLYFISH can count k-mers using an order of magnitude less memory and an order of magnitude faster than other k-mer counting packages by using an efficient encoding of a hash table and by exploiting the "compare-and-swap" CPU instruction to increase parallelism. The module parses _only_ `*_jf.hist` files. The general usage of jellyfish to be parsed by MultiQC module needs to be: - `gunzip -c file.fastq.gz | jellyfish count -o file.jf -m ...` - `jellyfish histo -o file_jf.hist -f file.jf` In case a user wants to customise the matching pattern for jellyfish, then multiqc can be run with the option `--cl-config "sp: { jellyfish: { fn: 'PATTERN' } }"` where `PATTERN` is the pattern to be matched. For example: ```bash multiqc . --cl-config "sp: { jellyfish: { fn: '*.hist' } }" ``` ### File search patterns ```yaml jellyfish: fn: '*_jf.hist' ``` --- ## Kaiju :::note Taxonomic classification for metagenomics. [http://kaiju.binf.ku.dk/](http://kaiju.binf.ku.dk/) ::: The module parses output generated by kaiju2table, e.g: ```bash kaiju -i R1.fq.gz -j R2.fq.gz -o output_kaiju.txt kaiju2table -t nodes.dmp -n names.dmp -r species -o kaiju2table_species.txt output_kaiju.txt kaiju2table -t nodes.dmp -n names.dmp -r phylum -o kaiju2table_phylum.txt output_kaiju.txt ``` ### File search patterns ```yaml kaiju: contents_re: file\tpercent\treads\ttaxon_id\ttaxon_name num_lines: 1 ``` --- ## Kallisto :::note Quantifies abundances of transcripts (or more generally, of target sequences) from RNA-Seq data. [http://pachterlab.github.io/kallisto/](http://pachterlab.github.io/kallisto/) ::: **Note** - MultiQC parses the standard out from Kallisto, _not_ any of its output files (`abundance.h5`, `abundance.tsv`, and `run_info.json`). As such, you must capture the Kallisto stdout to a file when running to use the MultiQC module. ### File search patterns ```yaml kallisto: contents: '[quant] finding pseudoalignments for the reads' ``` --- ## K-mer Analysis Toolkit :::note Analyses sequencing data via its k-mer spectra. [https://github.com/TGAC/KAT](https://github.com/TGAC/KAT) ::: The KAT multiqc module interprets output from KAT distribution analysis json files, which typically contain information such as estimated genome size and heterozygosity rates from your k-mer spectra. ### File search patterns ```yaml kat: fn: '*.dist_analysis.json' ``` --- ## Kraken :::note Taxonomic classification using exact k-mer matches to find the lowest common ancestor (LCA) of a given sequence. [https://ccb.jhu.edu/software/kraken/](https://ccb.jhu.edu/software/kraken/) ::: The MultiQC module supports outputs from Kraken. It works with report files generated using the `--report` flag, that look like the following: ```ts 11.66 98148 98148 U 0 unclassified 88.34 743870 996 - 1 root 88.22 742867 0 - 131567 cellular organisms 88.22 742866 2071 D 2 Bacteria 87.95 740514 2914 P 1239 Firmicutes ``` A bar graph is generated that shows the number of fragments for each sample that fall into the top-5 categories for each taxa rank. The top categories are calculated by summing the library percentages across all samples. The number of top categories to plot can be customized in the config file: ```yaml kraken: top_n: 5 ``` The module also handles [Bracken](https://ccb.jhu.edu/software/bracken/) outputs, which uses Kraken internally. ### File search patterns ```yaml kraken: contents_re: ^\s{0,2}(\d{1,3}\.\d{1,2})\t(\d+)\t(\d+)\t((\d+)\t(\d+)\t)?([URDKPCOFGS-]\d{0,2})\t(\d+)(\s+)[root|unclassified] num_lines: 2 ``` --- ## leeHom :::note Bayesian reconstruction of ancient DNA. [https://github.com/grenaud/leeHom](https://github.com/grenaud/leeHom) ::: leeHom is a Bayesian maximum a posteriori algorithm for stripping sequencing adapters and merging overlapping portions of reads. The algorithm is mostly aimed at ancient DNA and Illumina data but can be used for any dataset. ### File search patterns ```yaml leehom: contents: Adapter dimers/chimeras num_lines: 100 ``` --- ## Librarian :::note Predicts the sequencing library type from the base composition of a FastQ file. [https://github.com/DesmondWillowbrook/Librarian](https://github.com/DesmondWillowbrook/Librarian) ::: Librarian reads from high throughput sequencing experiments show base compositions that are characteristic for their library type. For example, data from RNA-seq and WGBS-seq libraries show markedly different distributions of G, A, C and T across the reads. Librarian makes use of different composition signatures for library quality control: Test library compositions are extracted and compared against previously published data sets from mouse and human. This module generates the _Prediction Plot_ showing the likelihood that samples are a given library type. #### General Stats The module can also show the most likely library type in the General Statistics table, however this is disabled by default. This is because several library types are very similar to each other and can come out as a mix. It's often misleading to show only the top one (even if it has a low score), but very clear when looking at the full heatmap. If you really want to show the most likely library type, you can enable this in your MultiQC config file: ```yaml librarian: show_general_stats: true ``` ### File search patterns ```yaml librarian: fn: librarian_heatmap.txt ``` --- ## Lima :::note Demultiplex PacBio single-molecule sequencing reads. [https://github.com/PacificBiosciences/barcoding](https://github.com/PacificBiosciences/barcoding) ::: Lima, the PacBio barcode demultiplexer, is the standard tool to identify barcode sequences in PacBio single-molecule sequencing data. Starting in SMRT Link v5.1.0, it is the tool that powers the Demultiplex Barcodes GUI-based analysis application. The module parses the report and count files generated by [Lima](https://github.com/PacificBiosciences/barcoding), a PacBio tool to demultiplex PacBio single-molecule sequencing data. By default, Lima will use `barcode1--barcode2` as the sample names. To prevent these barcodes showing up in the General Statistics table of MultiQC, the Lima results are added to their own section. If you want to include the Lima results in the General Statistics table, you can rename the `barcode1--barcode2` filenames to their apropriate samples using the [--replace-names](../reports/customisation#sample-name-replacement) option. Each sample that is specified in this way will be moved from the Lima section to the General Statistics table. ### File search patterns ```yaml lima/counts: contents: "IdxFirst\tIdxCombined\tIdxFirstNamed\tIdxCombinedNamed\tCounts\tMeanScore" num_lines: 1 lima/summary: contents: ZMWs above all thresholds max_filesize: 1024 num_lines: 2 ``` --- ## Long Ranger :::note Sample demultiplexing, barcode processing, alignment, quality control, variant calling, phasing, and structural variant calling. [https://support.10xgenomics.com/genome-exome/software/pipelines/latest/what-is-long-ranger](https://support.10xgenomics.com/genome-exome/software/pipelines/latest/what-is-long-ranger) ::: Currently supported Longranger pipelines: - `wgs` - `targeted` - `align` Usage: ```bash longranger wgs --fastqs=/path/to/fastq --id=NA12878 multiqc /path/to/NA12878 ``` This module will look for the files `_invocation` and `summary.csv` in the `NA12878` folder, i.e. the output folder of Longranger in this example. The file `summary.csv` is required. If the file `_invocation` is not found the sample will receive a generic name in the MultiQC report (`longranger#1`), instead of `NA12878` or whatever was given by the `--id` parameter. ### File search patterns ```yaml longranger/invocation: contents: call PHASER_SVCALLER_CS( fn: _invocation max_filesize: 2048 longranger/summary: contents: longranger_version,instrument_ids,gems_detected,mean_dna_per_gem,bc_on_whitelist,bc_mean_qscore,n50_linked_reads_per_molecule fn: '*summary.csv' num_lines: 2 ``` --- ## MACS2 :::note Identifies transcription factor binding sites in ChIP-seq data. [https://macs3-project.github.io/MACS/](https://macs3-project.github.io/MACS/) ::: MACS2 _(Model-based Analysis of ChIP-Seq)_ is a tool for identifying transcript factor binding sites. MACS captures the influence of genome complexity to evaluate the significance of enriched ChIP regions. The module reads the `*_peaks.xls` results files and prints the redundancy rates and number of peaks found in the General Statistics table. Numerous additional values are parsed and saved to `multiqc_data/multiqc_macs2.txt`. ### File search patterns ```yaml macs2: fn: '*_peaks.xls' ``` --- ## MALT :::note Aligns of metagenomic reads to a database of reference sequences (such as NR, GenBank or Silva) and outputs a MEGAN RMA file. [http://ab.inf.uni-tuebingen.de/software/malt/](http://ab.inf.uni-tuebingen.de/software/malt/) ::: The MALT MultiQC module reads the header of the MALT log files and produces three MultiQC sections: - A MALT summary statistics table - A Mappability bargraph - A Taxonomic assignment success bargraph ### File search patterns ```yaml malt: contents: MaltRun - Aligns sequences using MALT (MEGAN alignment tool) num_lines: 2 ``` --- ## mapDamage :::note Tracks and quantifies damage patterns in ancient DNA sequences. [https://github.com/ginolhac/mapDamage](https://github.com/ginolhac/mapDamage) ::: This module parses the base `misincorporation` output. ### File search patterns ```yaml mapdamage: - fn: 3p*_freq.txt - fn: 5p*_freq.txt - fn: lgdistribution.txt ``` --- ## MEGAHIT :::note NGS read assembler. [https://github.com/voutcn/megahit](https://github.com/voutcn/megahit) ::: MultiQC will parse stdout/stderr logs from MEGAHIT runs. The sample name is taken from the file name (e.g. `sample1.log` will yield a sample name of `sample1`). ### File search patterns ```yaml megahit: contents: ' - MEGAHIT v' num_lines: 5 ``` --- ## MetaPhlAn :::note Profiles the composition of microbial communities from metagenomic shotgun sequencing data. [https://github.com/biobakery/MetaPhlAn](https://github.com/biobakery/MetaPhlAn) ::: The module supports outputs from MetaPhlAn, that look like the following: ```tsv k__Bacteria 2 100.0 k__Bacteria|p__Firmicutes 2|1239 44.30422 k__Bacteria|p__Bacteroidetes 2|976 34.73101 ``` A bar graph is generated that shows the relative abundance for each sample that fall into the top-10 categories for each taxa rank. The top categories are calculated by summing the relative abundances across all samples. Any species under the Additional Species column are ignored when making the graphs. The number of top categories to plot can be customized in the config file: ```yaml metaphlan: top_n: 10 ``` ### File search patterns ```yaml metaphlan: contents: "#clade_name\tNCBI_tax_id\trelative_abundance\t" fn: '*.txt' ``` --- ## Methurator :::note Estimates sequencing saturation for reduced-representation bisulfite sequencing (RRBS) data. [https://github.com/VIBTOBIlab/methurator](https://github.com/VIBTOBIlab/methurator) ::: Methurator is a Python package designed to estimate sequencing saturation for reduced-representation bisulfite sequencing (RRBS) data. The module parses the `methurator_summary.yml` file generated by the `methurator downsample` command. This file contains: - **Reads summary**: Read counts at each downsampling percentage - **CpGs summary**: CpG site counts at different coverage thresholds - **Saturation analysis**: Model fit results including asymptote and saturation estimates The module displays key metrics in the General Statistics table and creates saturation curve plots showing how CpG detection changes with sequencing depth. ### File search patterns ```yaml methurator: fn: '*methurator_summary.yml' ``` --- ## methylQA :::note Methylation sequencing data quality assessment tool. [http://methylqa.sourceforge.net/](http://methylqa.sourceforge.net/) ::: ### File search patterns ```yaml methylqa: fn: '*.report' shared: true ``` --- ## mgikit :::note Demultiplexes FASTQ files from an MGI sequencing instrument. [https://github.com/sagc-bioinformatics/mgikit](https://github.com/sagc-bioinformatics/mgikit) ::: Possible mgikit output files are: 1. **Sample stats file** ('*.L{1,2,3,4}.mgikit.sample_stats'): Sample statistics for each lane like yield, quality scores, cluster count 2. **General info file** ('*.L{1,2,3,4}.mgikit.general'): Rounded up sample stats, but also includes lane-level stats 3. **General info file** ('*.L{1,2,3,4}.mgikit.info'): Matching indexes within the data generated by a specific lane 4. **Undetermined barcodes file** ('*.L{1,2,3,4}.mgikit.undetermined_barcode'): Barcodes that did not match with any sample. 5. **Ambiguous barcodes file** ('*.L{1,2,3,4}.mgikit.ambiguous_barcode'): Barcodes that match with multiple samples. This situation can happen when setting a high mismatch threshold. Configuration options: ```yaml mgikit: # ignore undetermined and ambiguous cases in the report keep_core_samples: false # number of undetermined barcodes to be presented in the report. It takes any positive value less than or equal to the number of barcodes in the demultiplexer reports which is usually 50 undetermined_barcode_threshold: 25 # generate a brief version of the report. Ignores the reports for cluster per sample per lane. brief_report: false # number of decimal positions to be used for counts in the tables decimal_positions: 2 ``` ### File search patterns ```yaml mgikit/mgi_ambiguous_barcode: fn: '*.mgikit.ambiguous_barcode' mgikit/mgi_general_info: fn: '*.mgikit.general' mgikit/mgi_sample_reads: fn: '*.mgikit.info' mgikit/mgi_sample_stats: fn: '*.mgikit.sample_stats' mgikit/mgi_undetermined_barcode: fn: '*.mgikit.undetermined_barcode' ``` --- ## MinIONQC :::note Quality control for ONT (Oxford Nanopore) long reads. [https://github.com/roblanf/minion_qc](https://github.com/roblanf/minion_qc) ::: It uses the `sequencing_summary.txt` files produced by ONT (Oxford Nanopore Technologies) long-read base-callers to perform QC on the reads. It allows quick-and-easy comparison of data from multiple flowcells The module parses data in the `summary.yaml` MinIONQC output files. ### File search patterns ```yaml minionqc: contents: total.gigabases fn: summary.yaml ``` --- ## mirtop :::note Annotates miRNAs and isomiRs and compute general statistics in mirGFF3 format. [https://github.com/miRTop/mirtop/](https://github.com/miRTop/mirtop/) ::: This tool is dedicated to the creation and management of miRNA alignment output using the standardized GFF3 format (see [miRTop/mirGFF3](https://github.com/miRTop/mirGFF3)). A unified miRNA alignment format allows to easily compare the output of different alignment tools. Currently, mirtop can convert into mirGFF3 the outputs of commonly used pipelines, such as seqbuster, isomiR-SEA, sRNAbench, Prost! as well as BAM files. ### File search patterns ```yaml mirtop: fn: '*_mirtop_stats.log' ``` --- ## miRTrace :::note Quality control for small RNA sequencing data. [https://github.com/friedlanderlab/mirtrace](https://github.com/friedlanderlab/mirtrace) ::: miRTrace performs adapter trimming and discards the reads that fail to pass the QC filters. miRTrace specifically addresses sequencing quality, read length, sequencing depth and miRNA complexity and also identifies the presence of both miRNAs and undesirable sequences derived from tRNAs, rRNAs, or Illumina artifact sequences. miRTrace also profiles clade-specific miRNAs based on a comprehensive catalog of clade-specific miRNA families identified previously. With this information, miRTrace can detect exogenous miRNAs, which could be contamination derived, e.g. index mis-assignment on sample demultiplexing, or biologically derived, e.g. parasitic RNAs. ### File search patterns ```yaml mirtrace/contaminationbasic: fn: mirtrace-stats-contamination_basic.tsv mirtrace/length: fn: mirtrace-stats-length.tsv mirtrace/mirnacomplexity: fn: mirtrace-stats-mirna-complexity.tsv mirtrace/summary: fn: mirtrace-results.json ``` --- ## MosaiCatcher :::note Counts strand-seq reads and classifies strand states of each chromosome in each cell using a Hidden Markov Model. [https://github.com/friendsofstrandseq/mosaicatcher](https://github.com/friendsofstrandseq/mosaicatcher) ::: ### File search patterns ```yaml mosaicatcher: fn: '*.mosaicatcher_info_raw.txt' ``` --- ## Mosdepth :::note Fast BAM/CRAM depth calculation for WGS, exome, or targeted sequencing. [https://github.com/brentp/mosdepth](https://github.com/brentp/mosdepth) ::: Mosdepth can generate several output files all with a common prefix and different endings: - per-base depth (`{prefix}.per-base.bed.gz`), - mean per-window depth given a window size (`{prefix}.regions.bed.gz`, if a BED file provided with `--by`), - mean per-region given a BED file of regions (`{prefix}.regions.bed.gz`, if a window size provided with `--by`), - a distribution of proportion of bases covered at or above a given threshhold for each chromosome and genome-wide (`{prefix}.mosdepth.global.dist.txt` and `{prefix}.mosdepth.region.dist.txt`), - quantized output that merges adjacent bases as long as they fall in the same coverage bins (`{prefix}.quantized.bed.gz`), - threshold output to indicate how many bases in each region are covered at the given thresholds (`{prefix}.thresholds.bed.gz`) - summary output providing region length, coverage mean, min, and max for each region. (`{prefix}.mosdepth.summary.txt`) The MultiQC module plots coverage distributions from 2 kinds of outputs: - `{prefix}.mosdepth.region.dist.txt` - `{prefix}.mosdepth.global.dist.txt` Using "region" if exists, otherwise "global". Plotting 3 figures: - Proportion of bases in the reference genome with, at least, a given depth of coverage (cumulative coverage distribution). - Proportion of bases in the reference genome with a given depth of coverage (absolute coverage distribution). - Average coverage per contig/chromosome. Also plotting the percentage of the genome covered at a threshold in the General Stats section. The default thresholds are 1, 5, 10, 30, 50, which can be customised in the config as follows: ```yaml mosdepth_config: general_stats_coverage: - 10 - 20 - 40 - 200 - 30000 ``` You can also specify which columns would be hidden when the report loads (by default, all values are hidden except 30X): ```yaml general_stats_coverage_hidden: - 10 - 20 - 200 ``` For the per-contig coverage plot, you can include and exclude contigs based on name or pattern. For example, you could add the following to your MultiQC config file: ```yaml mosdepth_config: include_contigs: - "chr*" exclude_contigs: - "*_alt" - "*_decoy" - "*_random" - "chrUn*" - "HLA*" - "chrM" - "chrEBV" ``` Note that exclusion superseeds inclusion for the contig filters. To additionally avoid cluttering the plot, mosdepth can exclude contigs with a low relative coverage. ```yaml mosdepth_config: # Should be a fraction, e.g. 0.001 (exclude contigs with 0.1% coverage of sum of # coverages across all contigs) perchrom_fraction_cutoff: 0.001 ``` If you want to see what is being excluded, you can set `show_excluded_debug_logs` to `True`: ```yaml mosdepth_config: show_excluded_debug_logs: True ``` This will then print a debug log message (use `multiqc -v`) for each excluded contig. This is disabled by default as there can be very many in some cases. Besides the `{prefix}.mosdepth.global.dist.txt` and `{prefix}.mosdepth.region.dist.txt` files, the `{prefix}.mosdepth.summary.txt` file is used for the General Stats table. The module also plots an X/Y relative chromosome coverage per sample. By default, it finds chromosome named X/Y or chrX/chrY, but that can be customised: ```yaml mosdepth_config: # Name of the X and Y chromosomes. If not specified, MultiQC will search for # any chromosome names that look like x, y, chrx or chry (case-insensitive) xchr: myXchr ychr: myYchr ``` ### File search patterns ```yaml mosdepth/global_dist: fn: '*.mosdepth.global.dist.txt' mosdepth/region_dist: fn: '*.mosdepth.region.dist.txt' mosdepth/summary: fn: '*.mosdepth.summary.txt' ``` --- ## Motus :::note Microbial profiling through marker gene (MG)-based operational taxonomic units (mOTUs). [https://motu-tool.org/](https://motu-tool.org/) ::: The module takes as input in the stdout of `mOTUs profile`, and provides summary statistics on various steps of the pipeline. ### File search patterns ```yaml motus: contents: Reads are aligned (by BWA) to marker gene sequences in the reference database num_lines: 2 ``` --- ## mtnucratio :::note Computes mitochondrial to nuclear genome ratios in NGS datasets. [http://www.github.com/apeltzer/MTNucRatioCalculator](http://www.github.com/apeltzer/MTNucRatioCalculator) ::: ### File search patterns ```yaml mtnucratio: fn: '*mtnuc.json' ``` --- ## MultiVCFAnalyzer :::note Reads multiple VCF files into combined genotype calls, produces summary statistics and downstream formats. [https://github.com/alexherbig/MultiVCFAnalyzer](https://github.com/alexherbig/MultiVCFAnalyzer) ::: The downstream formats are useful for follow-up analyses such as phylogeny reconstruction, SNP effect analyses, population genetic analyses, etc. ### File search patterns ```yaml multivcfanalyzer: fn: MultiVCFAnalyzer.json ``` --- ## nanoq :::note Reports read quality and length from nanopore sequencing data. [https://github.com/nerdna/nanoq/](https://github.com/nerdna/nanoq/) ::: ### File search patterns ```yaml nanoq: contents: Nanoq Read Summary num_lines: 3 ``` --- ## NanoStat :::note Reports various statistics for long read dataset in FASTQ, BAM, or albacore sequencing summary format (supports NanoPack; NanoPlot, NanoComp). [https://github.com/wdecoster/nanostat/](https://github.com/wdecoster/nanostat/), [https://github.com/wdecoster/nanoplot/](https://github.com/wdecoster/nanoplot/) ::: Programs are part of the NanoPack family for summarising results of sequencing on Oxford Nanopore methods (MinION, PromethION etc.) NanoStat module for parsing statistics from Oxford Nanopore sequencing data. By default, only the Read N50 metric is shown in the General Statistics table, with all other metrics hidden. You can customize which metrics appear in the General Statistics table using the `general_stats_columns` configuration option in your MultiQC config file. For example, to show number of reads, mean read length and median quality for FASTQ data: ```yaml general_stats_columns: nanostat: columns: Number of reads_fastq: title: "# Reads" description: "Number of reads" hidden: false Mean read length_fastq: title: "Mean Length" description: "Mean read length" hidden: false Median read quality_fastq: title: "Median Quality" description: "Median read quality" hidden: false ``` Available metrics that can be added to General Statistics (append `_fastq`, `_aligned`, `_fasta` or `_seq summary` depending on the data type): * `Active channels` - Number of active channels * `Median read length` - Median read length (bp) * `Mean read length` - Mean read length (bp) * `Read length N50` - Read length N50 * `Median read quality` - Median read quality (Phred scale) * `Mean read quality` - Mean read quality (Phred scale) * `Median percent identity` - Median percent identity * `Average percent identity` - Average percent identity * `Number of reads` - Number of reads * `Total bases` - Total number of bases * `Total bases aligned` - Total number of aligned bases Each metric can be customized with the following options: * `title` - Column title * `description` - Column description * `hidden` - Whether to hide the column by default * `scale` - Color scale for the column * `format` - Number format * `min` - Minimum value for the color scale * `max` - Maximum value for the color scale * `suffix` - Suffix to add to values * `shared_key` - Share color scale with other columns ### File search patterns ```yaml nanostat: contents_re: Metrics\s+dataset\s* max_filesize: 4096 num_lines: 1 nanostat/legacy: contents_re: General summary:\s* max_filesize: 4096 num_lines: 1 ``` --- ## Nextclade :::note Viral genome alignment, clade assignment, mutation calling, and quality checks. [https://github.com/nextstrain/nextclade](https://github.com/nextstrain/nextclade) ::: Nextclade assigns input sequences to SARS-Cov-2 clades based on differences between the input sequences and [Nextstrain](https://nextstrain.org/) reference sequences. In addition, it judges the validity of the samples by performing several quality control checks on the input sequences. ### File search patterns ```yaml nextclade: contents: seqName;clade; num_lines: 1 ``` --- ## ngs-bits :::note Calculating statistics from FASTQ, BAM, and VCF. [https://github.com/imgag/ngs-bits](https://github.com/imgag/ngs-bits) ::: The ngs-bits module parses XML output generated for several tools in the ngs-bits collection: * [ReadQC](https://github.com/imgag/ngs-bits/blob/master/doc/tools/ReadQC.md) for statistics on FASTQ files, * [MappingQC](https://github.com/imgag/ngs-bits/blob/master/doc/tools/MappingQC.md) for statistics on BAM files, * [SampleGender](https://github.com/imgag/ngs-bits/blob/master/doc/tools/SampleGender.md) for gender prediction based on sequencing data. ### File search patterns ```yaml ngsbits/mappingqc: - contents: MappingQC fn: '*.qcML' num_lines: 20 ngsbits/readqc: - contents: ReadQC fn: '*.qcML' num_lines: 20 - contents: SeqPurge fn: '*.qcML' num_lines: 20 ngsbits/samplegender: - fn: '*_ngsbits_sex.tsv' ``` --- ## ngsderive :::note Forensic tool for by backwards computing library information in sequencing data. [https://github.com/stjudecloud/ngsderive](https://github.com/stjudecloud/ngsderive) ::: Results are provided as a 'best guess' — the tool does not claim 100% accuracy and results should be considered with that understanding. Please see the documentation for more information. ### File search patterns ```yaml ngsderive/encoding: contents: "File\tEvidence\tProbableEncoding" num_lines: 1 ngsderive/instrument: contents: "File\tInstrument\tConfidence\tBasis" num_lines: 1 ngsderive/junction_annotation: contents: "File\ttotal_junctions\ttotal_splice_events\tknown_junctions\tpartial_novel_junctions\t\ complete_novel_junctions\tknown_spliced_reads\tpartial_novel_spliced_reads\tcomplete_novel_spliced_reads" num_lines: 1 ngsderive/readlen: contents: "File\tEvidence\tMajorityPctDetected\tConsensusReadLength" num_lines: 1 ngsderive/strandedness: contents: "File\tTotalReads\tForwardPct\tReversePct\tPredicted" num_lines: 1 ``` --- ## Nonpareil :::note Estimates metagenomic coverage and sequence diversity. [https://github.com/lmrodriguezr/nonpareil](https://github.com/lmrodriguezr/nonpareil) ::: Nonpareil uses the redundancy of the reads in a metagenomic dataset to estimate the average coverage and predict the amount of sequences that will be required to achieve "nearly complete coverage", defined as ≥95% or ≥99% average coverage. Since Nonpareil main output has no model information, it is necessary extract the `curves` object as a `JSON` file. From version `v3.5.5` this can be done with an auxiliary `R` script, briefly: ```bash NonpareilCurves.R --json out.json model.npo ``` #### Module config options The module plots a line graph for each sample, with a tab panel to switch between only observed data, only models, or both combined (model with a dashed line). It will use the colors specified in the JSON file by `nonpareil` and, if some is missing use one from a MultiQC colour scheme (default: Paired) that can be defined with: ```yaml nonpareil: plot_colours: Paired ``` ### File search patterns ```yaml nonpareil: - contents: LRstar fn: '*.json' max_filesize: 1048576 num_lines: 50 ``` --- ## ODGI :::note Analysis and manipulation of pangenome graphs structured in the variation graph model. [https://github.com/pangenome/odgi](https://github.com/pangenome/odgi) ::: The odgi module parses [odgi stats](https://odgi.readthedocs.io/en/latest/rst/commands/odgi_stats.html) reports. It is specifically designed to parse the output of a command like: ```sh odgi stats -i input_graph.og -y ``` It is not guaranteed that output created using any other parameter combination can be parsed using this module. It solely works with report files generated by [odgi stats](https://pangenome.github.io/odgi/odgi_docs.html#_odgi_stats1) in `.yaml` format, which look like the following: ```yaml --- length: 206263 nodes: 3751 edges: 5195 paths: 13 num_weakly_connected_components: 1 weakly_connected_components: - component: id: 0 nodes: 3751 is_acyclic: "no" num_nodes_self_loops: total: 0 unique: 0 A: 57554 C: 43275 G: 41944 T: 63490 mean_links_length: - length: path: all_paths in_node_space: 1.64973 in_nucleotide_space: 7.34035 num_links_considered: 202793 num_gap_links_not_penalized: 147940 sum_of_path_node_distances: - distance: path: all_paths in_node_space: 5.53383 in_nucleotide_space: 2.1454 nodes: 202806 nucleotides: 3757597 num_penalties: 231 num_penalties_different_orientation: 0 ``` For the odgi module to discover the [odgi stats](https://odgi.readthedocs.io/en/latest/rst/commands/odgi_stats.html) reports, the file must match one of the following patterns: - "*.og.stats.yaml" - "*.og.stats.yml" - "*.odgi.stats.yaml" - "*.odgi.stats.yml" A bar graph is generated, which shows the length, number of nodes, edges and paths for each sample. Additionally, a second bar graph is generated visualizing the `in_node_space` and `in_nucleotide_space` for every sample. It is possible to add custom content to your MultiQC report including [odgi viz](https://odgi.readthedocs.io/en/latest/rst/commands/odgi_viz.html) or [odgi draw](https://odgi.readthedocs.io/en/latest/rst/commands/odgi_draw.html) PNGs. Ensure that the names of the PNGs match `*_odgi_viz_mqc.png`. ### File search patterns ```yaml odgi: - fn: '*.og.stats.yaml' - fn: '*.og.stats.yml' - fn: '*.odgi.stats.yaml' - fn: '*.odgi.stats.yml' ``` --- ## OptiType :::note Precision HLA typing from next-generation sequencing data. [https://github.com/FRED-2/OptiType](https://github.com/FRED-2/OptiType) ::: Novel HLA genotyping algorithm based on integer linear programming, capable of producing accurate 4-digit HLA genotyping predictions from NGS data by simultaneously selecting all major and minor HLA Class I alleles. ### File search patterns ```yaml optitype: contents: "\tA1\tA2\tB1\tB2\tC1\tC2\tReads\tObjective" num_lines: 1 ``` --- ## pairtools :::note Toolkit for Chromatin Conformation Capture experiments. Handles short-reads paired reference alignments, extracts 3C-specific information, and perform common tasks such as sorting, filtering, and deduplication. [https://github.com/mirnylab/pairtools](https://github.com/mirnylab/pairtools) ::: The module parses summary statistics generated by pairtools's `dedup` and `stats` tools. ### File search patterns ```yaml pairtools: contents: - "total_single_sided_mapped\t" - "cis\t" - "trans\t" - pair_types/ num_lines: 20 ``` --- ## Pangolin :::note Uses variant calls to assign SARS-CoV-2 genome sequences to global lineages. [https://github.com/cov-lineages/pangolin](https://github.com/cov-lineages/pangolin) ::: Implements the dynamic nomenclature of SARS-CoV-2 lineages, known as the Pango nomenclature. It allows a user to assign a SARS-CoV-2 genome sequence the most likely lineage (Pango lineage) to SARS-CoV-2 query sequences. ### File search patterns ```yaml pangolin: contents: pangolin_version num_lines: 1 ``` --- ## pbmarkdup :::note Takes one or multiple sequencing chips of an amplified libray as HiFi reads and marks or removes duplicates. [https://github.com/PacificBiosciences/pbmarkdup](https://github.com/PacificBiosciences/pbmarkdup) ::: The module adds the **% Unique Molecules** and **%Duplicate Reads** (hidden) to the General Statistics table. ### File search patterns ```yaml pbmarkdup: contents_re: LIBRARY +READS +UNIQUE MOLECULES +DUPLICATE READS num_lines: 5 ``` --- ## Peddy :::note Compares familial-relationships and sexes as reported in a PED file with those inferred from a VCF. [https://github.com/brentp/peddy](https://github.com/brentp/peddy) ::: It samples the VCF at about 25000 sites (plus chrX) to accurately estimate relatedness, IBS0, heterozygosity, sex and ancestry. It uses 2504 thousand genome samples as backgrounds to calibrate the relatedness calculation and to make ancestry predictions. It does this very quickly by sampling, by using C for computationally intensive parts, and parallelization. ### File search patterns ```yaml peddy/background_pca: fn: '*.background_pca.json' peddy/het_check: fn: '*.het_check.csv' peddy/ped_check: fn: '*.ped_check.csv' peddy/sex_check: fn: '*.sex_check.csv' peddy/summary_table: fn: '*.peddy.ped' ``` --- ## Percolator :::note Semi-supervised learning for peptide identification from shotgun proteomics datasets. [https://github.com/percolator/percolator](https://github.com/percolator/percolator) ::: The module assumes that the Percolator output file is named `*percolator_feature_weights.tsv`. Make sure to run it using: ``` percolator ... > samples.percolator_feature_weights.tsv ``` The module accepts one configuration option: - `group_to_feature`: A dictionary mapping group names to feature names (empty per default), e.g. in `multiqc_config.yaml`: ```yaml percolator: group_to_feature: psm_file_combined: [MS:1002255, MS:1002252] ms2pip: [ionb_min_abs_diff, iony_min_abs_diff] deeplc: [rt_diff] ``` ### File search patterns ```yaml percolator: fn: '*percolator_feature_weights.tsv' ``` --- ## phantompeakqualtools :::note Computes informative enrichment and quality measures for ChIP-seq/DNase-seq/FAIRE-seq/MNase-seq data. [https://www.encodeproject.org/software/phantompeakqualtools](https://www.encodeproject.org/software/phantompeakqualtools) ::: Used to generate three quality metrics: NSC, RSC, and PBC. The NSC (Normalized strand cross-correlation) and RSC (relative strand cross-correlation) metrics use cross-correlation of stranded read density profiles to measure enrichment independently of peak calling. The PBC (PCR bottleneck coefficient) is an approximate measure of library complexity. PBC is the ratio of (non-redundant, uniquely mappable reads)/(uniquely mappable reads). ### File search patterns ```yaml phantompeakqualtools/out: fn: '*.spp.out' ``` --- ## Picard :::note Tools for manipulating high-throughput sequencing data. [http://broadinstitute.github.io/picard/](http://broadinstitute.github.io/picard/) ::: Supported commands: - `AlignmentSummaryMetrics` - `BaseDistributionByCycle` - `CollectIlluminaBasecallingMetrics` - `CollectIlluminaLaneMetrics` - `CrosscheckFingerprints` - `ExtractIlluminaBarcodes` - `GcBiasMetrics` - `HsMetrics` - `InsertSizeMetrics` - `MarkDuplicates` - `MarkIlluminaAdapters` - `OxoGMetrics` - `QualityByCycleMetrics` - `QualityScoreDistributionMetrics` - `QualityYieldMetrics` - `RnaSeqMetrics` - `RrbsSummaryMetrics` - `ValidateSamFile` - `VariantCallingMetrics` - `WgsMetrics` #### Coverage Levels It's possible to customise the HsMetrics _"Target Bases 30X"_ coverage and WgsMetrics _"Fraction of Bases over 30X"_ that are shown in the general statistics table. This must correspond to field names in the picard report, such as `PCT_TARGET_BASES_2X` / `PCT_10X`. Any numbers not found in the reports will be ignored. The coverage levels available for HsMetrics are [typically](http://broadinstitute.github.io/picard/picard-metric-definitions.html#HsMetrics) 1, 2, 10, 20, 30, 40, 50 and 100X. The coverage levels available for WgsMetrics are [typically](http://broadinstitute.github.io/picard/picard-metric-definitions.html#CollectWgsMetrics.WgsMetrics) 1, 5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80, 90 and 100X. To customise this, add the following to your MultiQC config: ```yaml picard_config: general_stats_target_coverage: - 10 - 50 ``` #### CrosscheckFingerprints In addition to adding a table of results, a `Crosschecks All Expected` column will be added to the General Statistics. If all comparisons for a sample were `Expected`, then the value of the field will be `True` and green. If not it will be `False` and Red. You can customize the columns show in the CrosscheckFingerprints table with the config keys `CrosscheckFingerprints_table_cols` and `CrosscheckFingerprints_table_cols_hidden`. For example: ```yaml picard_config: CrosscheckFingerprints_table_cols: - RESULT - LOD_SCORE CrosscheckFingerprints_table_cols_hidden: - LEFT_LANE - RIGHT_LANE ``` The column names will be normalized, ex `LOD_SCORE -> Lod score`. Note that if `CALCULATE_TUMOR_AWARE_RESULTS` was set to true on the CLI for any of the CrosscheckFingerprints result files, then the `LOD_SCORE_TUMOR_NORMAL` and `LOD_SCORE_NORMAL_TUMOR` will be displayed. #### HsMetrics Note that the _Target Region Coverage_ plot is generated using the `PCT_TARGET_BASES_` table columns from the HsMetrics output (not immediately obvious when looking at the log files). You can customize the columns shown in the HsMetrics table with the config keys `HsMetrics_table_cols` and `HsMetrics_table_cols_hidden`. For example: ```yaml picard_config: HsMetrics_table_cols: - NEAR_BAIT_BASES - OFF_BAIT_BASES - ON_BAIT_BASES HsMetrics_table_cols_hidden: - MAX_TARGET_COVERAGE - MEAN_BAIT_COVERAGE - MEAN_TARGET_COVERAGE ``` Only values listed in `HsMetrics_table_cols` will be included in the table. Anything listed in `HsMetrics_table_cols_hidden` will be hidden by default. A similar config is available for customising the HsMetrics columns in the General Stats table: ```yaml picard_config: HsMetrics_genstats_table_cols: - NEAR_BAIT_BASES HsMetrics_genstats_table_cols_hidden: - MAX_TARGET_COVERAGE ``` #### InsertSizeMetrics By default, the insert size plot is smoothed to contain a maximum of 500 data points per sample. This is to prevent the MultiQC report from being very large with big datasets. If you would like to customise this value to get a better resolution you can set the following MultiQC config values, with the new maximum number of points: ```yaml picard_config: insertsize_smooth_points: 10000 ``` The plotted maximum insert size can be set with: ```yaml picard_config: insertsize_xmax: 10000 ``` #### MarkDuplicates If a `BAM` file contains multiple read groups, Picard MarkDuplicates generates a report with multiple metric lines, one for each "library". By default, MultiQC will sum the values for every library it finds and recompute the `PERCENT_DUPLICATION` and `ESTIMATED_LIBRARY_SIZE` fields, giving a single set of results for each `BAM` file. If instead you would prefer each library to be treated as a separate sample, you can do so by setting the following MultiQC config: ```yaml picard_config: markdups_merge_multiple_libraries: False ``` This prevents the merge and recalculation and appends the library name to the sample name. This behaviour is present in MultiQC since version 1.9. Before this, only the metrics from the first library were taken and all others were ignored. #### ValidateSamFile Search Pattern Generally, Picard adds identifiable content to the output of function calls. This is not the case for ValidateSamFile. In order to identify logs the MultiQC Picard submodule `ValidateSamFile` will search for filenames that contain 'validatesamfile' or 'ValidateSamFile'. One can customise the used search pattern by overwriting the `picard/sam_file_validation` pattern in your MultiQC config. For example: ```yaml sp: picard/sam_file_validation: fn: "*[Vv]alidate[Ss]am[Ff]ile*" ``` #### WgsMetrics The coverage histogram from Picard typically shows a normal distribution with a very long tail. To make the plot easier to view, by default the module plots the line up to 99% of the data. This typically removes the long tail and gives a more useful graph. If you would like, you can set a specific value for the maximum coverage to cut the graph at. By setting this to a very large value, you will disable the cutting (the graph will automatically limit the axis at the maximum data point). You can do this as follows: ```yaml picard_config: wgsmetrics_histogram_max_cov: 500 ``` If running with very high coverage samples or using the Picard `CAP_COVERAGE` option, the coverage histogram can become very large indeed. For eaxmple, if reporting coverages of 1 million, it will have 1 million data points per sample. That can crash the browser and take a long time to run. There are two customisation MultiQC options to help with this. Firstly, MultiQC will automatically "smooth" the histogram to a maximum of `1000` data points by binning. This should stop the browser from crashing. You can tweak how many bins are used with the following: ```yaml picard_config: wgsmetrics_histogram_smooth: 1000 ``` Change `1000` to whatever number you want. If you don't want any smoothing, set it to a very high number bigger than the number of data points you have. Secondly, if you would prefer to instead simply skip the histogram, you can set the following: ```yaml picard_config: wgsmetrics_skip_histogram: True ``` This will omit that section from the report entirely, and also skip parsing the histogram data. By specifying this option you may speed up the run time for MultiQC with these types of files significantly. #### Sample names MultiQC supports outputs from multiple runs of a Picard tool merged together into one file. In order to handle multiple sample data in on file correctly, MultiQC needed to take the sample name elsewhere rather than the file name. For this reason, MultiQC attempts to parse the command line recorded in the output header. For example, an output from the `GcBias` tool contains a header line like this: ``` # net.sf.picard.analysis.CollectGcBiasMetrics REFERENCE_SEQUENCE=/reference/genome.fa INPUT=/alignments/P0001_101/P0001_101.bam OUTPUT=P0001_101.collectGcBias.txt ... ``` MultiQC would extract the BAM file name that goes after `INPUT=` and take `P0001_101` as a sample name. If MultiQC fails to parse the command line for any reason, it will fall back to using the file name. It is also possible to force using the file names as sample names by enabling the following config option: ```yaml picard_config: s_name_filenames: true ``` ### File search patterns ```yaml picard/alignment_metrics: - contents: picard.analysis.AlignmentSummaryMetrics - contents: --algo AlignmentStat picard/basedistributionbycycle: contents: BaseDistributionByCycleMetrics picard/collectilluminabasecallingmetrics: contents: CollectIlluminaBasecallingMetrics picard/collectilluminalanemetrics: contents: CollectIlluminaLaneMetrics picard/crosscheckfingerprints: contents: CrosscheckFingerprints picard/extractilluminabarcodes: contents: ExtractIlluminaBarcodes picard/gcbias: - contents: GcBiasDetailMetrics - contents: GcBiasSummaryMetrics - contents: --algo GCBias picard/hsmetrics: - contents: HsMetrics - contents: --algo HsMetricAlgo picard/insertsize: - contents: picard.analysis.InsertSizeMetrics - contents: --algo InsertSizeMetricAlgo picard/markdups: - contents: picard.sam.MarkDuplicates - contents: picard.sam.DuplicationMetrics - contents: picard.sam.markduplicates.MarkDuplicates - contents: markduplicates.DuplicationMetrics - contents: MarkDuplicatesSpark - contents: markduplicates.GATKDuplicationMetrics - contents: --algo Dedup picard/markilluminaadapters: contents: MarkIlluminaAdapters picard/oxogmetrics: - contents: '# picard.analysis.CollectOxoGMetrics' - contents: '# CollectOxoGMetrics' - contents_re: '# CollectMultipleMetrics .*OxoGMetrics' shared: true picard/pcr_metrics: - contents: '# picard.analysis.directed.CollectTargetedPcrMetrics' - contents_re: '# CollectMultipleMetrics .*TargetedPcrMetrics' shared: true picard/quality_by_cycle: - contents: '# MeanQualityByCycle' - contents: --algo MeanQualityByCycle - contents_re: .*CollectMultipleMetrics.*MeanQualityByCycle shared: true picard/quality_score_distribution: - contents: '# QualityScoreDistribution' - contents: --algo QualDistribution - contents_re: .*CollectMultipleMetrics.*QualityScoreDistribution shared: true picard/quality_yield_metrics: - contents: '# CollectQualityYieldMetrics' - contents_re: .*CollectMultipleMetrics.*QualityYieldMetrics shared: true picard/rnaseqmetrics: - contents: '# picard.analysis.Collectrnaseqmetrics' - contents: '# picard.analysis.CollectRnaSeqMetrics' - contents: '# CollectRnaSeqMetrics' - contents_re: '# CollectMultipleMetrics .*RnaSeqMetrics' shared: true picard/rrbs_metrics: - contents: '# picard.analysis.CollectRrbsMetrics' - contents_re: '# CollectMultipleMetrics .*RrbsMetrics' shared: true picard/sam_file_validation: fn: '*[Vv]alidate[Ss]am[Ff]ile*' picard/variant_calling_metrics: contents_re: '## METRICS CLASS.*VariantCallingDetailMetrics' picard/wgs_metrics: - contents: --algo WgsMetricsAlgo - contents_re: '## METRICS CLASS.*WgsMetrics' shared: true ``` --- ## Porechop :::note Finds and removes adapters from Oxford Nanopore reads. [https://github.com/rrwick/Porechop](https://github.com/rrwick/Porechop) ::: Adapters on the ends of reads are trimmed off, and when a read has an adapter in its middle, it is treated as chimeric and chopped into separate reads. Porechop performs thorough alignments to effectively find adapters, even at low sequence identity. The module parses the log file generated by [Porechop](https://github.com/rrwick/Porechop), which is a tool for demultiplexing and processing nanopore data. The module takes summary statistics of numbers of adapters and number of reads trimmed and displays them in the General Stats table as well as barplots. ### File search patterns ```yaml porechop: contents: Looking for known adapter sets num_lines: 10 ``` --- ## Preseq :::note Estimates library complexity, showing how many additional unique reads are sequenced for increasing total read count. [http://smithlabresearch.org/software/preseq/](http://smithlabresearch.org/software/preseq/) ::: A shallow curve indicates complexity saturation. The dashed line shows a perfectly complex library where total reads = unique reads. When `preseq lc_extrap` is run with the default parameters, the extrapolation points reach 10 billion molecules making the plot difficult to interpret in most scenarios. It also includes a lot of data in the reports, which can unnecessarily inflate report file sizes. To avoid this, MultiQC trims back the x-axis until each dataset shows 80% of its maximum y-value (unique molecules). To disable this feature and show all the data, add the following to your [MultiQC configuration](../getting_started/config): ```yaml preseq: notrim: true ``` #### Using coverage instead of read counts Preseq reports its numbers as "Molecule counts". This isn't always very intuitive, and it's often easier to talk about sequencing depth in terms of coverage. You can plot the estimated coverage instead by specifying the reference genome or target size, and the read length in your [MultiQC configuration](../getting_started/config): ```yaml preseq: genome_size: 3049315783 read_length: 300 ``` These parameters make the script take every molecule count and divide it by (genome_size / read_length). MultiQC comes with effective genome size presets for Human and Mouse, so you can provide the genome build name instead, like this: `genome_size: hg38_genome`. The following values are supported: `hg19_genome`, `hg38_genome`, `mm10_genome`. When the genome and read sizes are provided, MultiQC will plot the molecule counts on the X axis ("total" data) and coverages on the Y axis ("unique" data). However, you can customize what to plot on each axis (counts or coverage), e.g.: ```yaml preseq: x_axis: counts y_axis: coverage ``` #### Plotting externally calculated read counts To mark on the plot the read counts calculated externally from BAM or fastq files, create a file with `preseq_real_counts` in the filename and place it with your analysis files. It should be space or tab delimited with 2 or 3 columns (column 1 = preseq file name, column 2 = real read count, optional column 3 = real unique read count). For example: ``` Sample_1.preseq.txt 3638261 3638011 Sample_2.preseq.txt 1592394 1592133 [...] ``` You can generate a line for such a file using samtools: ```bash echo "Sample_1.preseq.txt "$(samtools view -c -F 4 Sample_1.bam)" "$(samtools view -c -F 1028 Sample_1.bam) ``` ### File search patterns ```yaml preseq: - contents: EXPECTED_DISTINCT num_lines: 2 - contents: distinct_reads num_lines: 2 preseq/real_counts: fn: '*preseq_real_counts*' ``` --- ## PRINSEQ++ :::note C++ implementation of the prinseq-lite.pl program. Filters, reformats, and trims genomic and metagenomic reads. [https://github.com/Adrian-Cantu/PRINSEQ-plus-plus](https://github.com/Adrian-Cantu/PRINSEQ-plus-plus) ::: This module requires that PRINSEQ++ has been run with the flag `-VERBOSE 1`. It uses the log file name as the sample name. ### File search patterns ```yaml prinseqplusplus: - contents: reads removed by - num_lines: 2 ``` --- ## Prokka :::note Rapid annotation of prokaryotic genomes. [http://www.vicbioinformatics.com/software.prokka.shtml](http://www.vicbioinformatics.com/software.prokka.shtml) ::: The Prokka module accepts two configuration options: - `prokka_table`: default `False`. Show a table in the report. - `prokka_barplot`: default `True`. Show a barplot in the report. - `prokka_fn_snames`: default `False`. Use filenames for sample names (DEPRECATED - use global `use_filename_as_sample_name` instead). Sample names are generated using the first line in the prokka reports: ``` organism: Helicobacter pylori Sample1 ``` The module assumes that the first two words are the organism name and the third is the sample name. So the above will give a sample name of `Sample1`. If you prefer, you can set `config.use_filename_as_sample_name` to `True` and MultiQC will instead use the log filename as the sample name. ### File search patterns ```yaml prokka: contents: 'contigs:' num_lines: 2 ``` --- ## PURPLE :::note A purity, ploidy and copy number estimator for whole genome tumor data. [https://github.com/hartwigmedical/hmftools/](https://github.com/hartwigmedical/hmftools/) ::: PURPLE combines B-allele frequency (BAF), read depth ratios, somatic variants and structural variant breakpoints to estimate the purity and copy number profile of a tumor sample, and also predicts gender, the MSI status, tumor mutational load and burden, clonality and the whole genome duplication status. ### File search patterns ```yaml purple/purity: fn: '*.purple.purity.tsv' purple/qc: fn: '*.purple.qc' ``` --- ## Pychopper :::note Identifies, orients, trims and rescues full length Nanopore cDNA reads. Can also rescue fused reads. [https://github.com/nanoporetech/pychopper](https://github.com/nanoporetech/pychopper) ::: The module parses the pychopper stats file. Pychopper needs to be run with the `-S stats_output` option to create the file. The name of the output file defines the sample name. The stats file is a three column `tsv` file with the format `category name value`. Currently only two stats are displayed in MultiQC. Two bargraphs are created for the read classication and the strand orientation of the identified full length transcripts. Additional stats could be included on further request. The general stats table contains a value that displays the percentage of full length transcripts. This value is calculated from the cumulative length of reads where Pychopper found primers at both ends. ### File search patterns ```yaml pychopper: contents: "Classification\tRescue" num_lines: 6 ``` --- ## pycoQC :::note Computes metrics and generates interactive QC plots for Oxford Nanopore technologies sequencing data. [https://github.com/tleonardi/pycoQC](https://github.com/tleonardi/pycoQC) ::: PycoQC relies on the `sequencing_summary.txt` file generated by Albacore and Guppy, but if needed it can also generate a summary file from basecalled `fast5` files. The package supports 1D and 1D2 runs generated with MinION, GridION and PromethION devices and basecalled with Albacore 1.2.1+ or Guppy 2.1.3+. ### File search patterns ```yaml pycoqc: contents: '"pycoqc":' num_lines: 2 ``` --- ## qc3C :::note Reference-free and BAM based quality control for Hi-C data. [http://github.com/cerebis/qc3C](http://github.com/cerebis/qc3C) ::: qc3C allows researchers to assess the fraction of read-pairs within a Hi-C library that are a product of proximity ligation -- in effect the Hi-C signal strength. Using a k-mer based approach, signal strength is inferred directly from reads and therefore no reference is required. Reference based assessment is also available and can provide further details. With this information in hand, researchers are able to decide how much sequencing will be needed to achieve their experimental aims. ### File search patterns ```yaml qc3C: fn: '*.qc3C.json' ``` --- ## QoRTs :::note Toolkit for analysis, QC, and data management of RNA-Seq datasets. [http://hartleys.github.io/QoRTs/](http://hartleys.github.io/QoRTs/) ::: Aids in the detection and identification of errors, biases, and artifacts produced by paired-end high-throughput RNA-Seq technology. In addition, it can produce count data designed for use with differential expression and differential exon usage tools, as well as individual-sample and/or group-summary genome track files suitable for use with the UCSC genome browser. ### File search patterns ```yaml qorts: contents: BENCHMARK_MinutesOnSamIteration num_lines: 100 qorts/log: contents: Starting QoRTs fn: QC.*.log num_lines: 2 ``` --- ## QualiMap :::note Quality control of alignment data and its derivatives like feature counts. [http://qualimap.bioinfo.cipf.es/](http://qualimap.bioinfo.cipf.es/) ::: The module supports the Qualimap commands `BamQC` and `RNASeq`. Note that Qualimap must be run with the `-outdir` option as well as `-outformat HTML` (which is on by default). MultiQC uses files found within the `raw_data_qualimapReport` folder (as well as `genome_results.txt`). Qualimap adds lots of columns to the General Statistics table. To avoid making the table too wide and bloated, some of these are hidden by default (`Error Rate`, `M Aligned`, `M Total reads`). You can override these defaults in your MultiQC config file - for example, to show `Error Rate` by default and hide `Ins. size` by default, add the following: ```yaml table_columns_visible: QualiMap: general_error_rate: True median_insert_size: False ``` See the [relevant section of the documentation](../reports/customisation#hiding-columns) for more detail. In addition to this, it's possible to customise which coverage thresholds calculated by the Qualimap BamQC module _(default: 1, 5, 10, 30, 50)_ and which of these are hidden in the General Statistics tablewhen the report loads _(default: all hidden except 30X)_. To do this, add something like the following to your MultiQC config file: ```yaml qualimap_config: general_stats_coverage: - 10 - 20 - 40 - 200 - 30000 general_stats_coverage_hidden: - 10 - 20 - 200 ``` ### File search patterns ```yaml qualimap/bamqc/coverage: fn: coverage_histogram.txt qualimap/bamqc/gc_dist: fn: mapped_reads_gc-content_distribution.txt qualimap/bamqc/genome_fraction: fn: genome_fraction_coverage.txt qualimap/bamqc/genome_results: fn: genome_results.txt qualimap/bamqc/html: contents: 'Qualimap report: BAM QC' fn: qualimapReport.html num_lines: 10 qualimap/bamqc/insert_size: fn: insert_size_histogram.txt qualimap/rnaseq/coverage: fn: coverage_profile_along_genes_(total).txt qualimap/rnaseq/html: contents: 'Qualimap report: RNA Seq QC' fn: qualimapReport.html num_lines: 10 qualimap/rnaseq/rnaseq_results: fn: rnaseq_qc_results.txt ``` --- ## QUAST :::note Quality assessment tool for genome assemblies. [http://quast.bioinf.spbau.ru/](http://quast.bioinf.spbau.ru/) ::: The module parses the `report.tsv` files generated by QUAST and adds key metrics to the report General Statistics table. All statistics for all samples are saved to `multiqc_data/multiqc_quast.txt`. #### Configuration By default, the QUAST module is configured to work with large _de-novo_ genomes, showing thousands of contigs, mega-base pairs and other sensible defaults. If these aren't appropriate for your genomes, you can configure them as follows: ```yaml quast_config: contig_length_multiplier: 0.001 contig_length_suffix: "Kbp" total_length_multiplier: 0.000001 total_length_suffix: "Mbp" total_number_contigs_multiplier: 0.001 total_number_contigs_suffix: "K" ``` The default module values are shown above. See the [main MultiQC documentation](../getting_started/config) for more information about how to configure MultiQC. #### MetaQUAST The QUAST module will also parse output from [MetaQUAST](http://quast.sourceforge.net/metaquast) runs (`metaquast.py`). The `combined_reference/report.tsv` file is parsed, and folders `runs_per_reference` and `not_aligned` are ignored. If you want to run MultiQC against auxiliary MetaQUAST runs, you must explicitly pass these files to MultiQC: ```bash multiqc runs_per_reference/reference_1/report.tsv ``` Note that you can pass as many file paths to MultiQC as you like and use glob expansion (eg. `runs_per_reference/*/report.tsv`). ### File search patterns ```yaml quast: contents: "Assembly\t" fn: report.tsv num_lines: 2 ``` --- ## Ribo-TISH :::note Identifies translated ORFs from Ribo-seq data and reports reading frame quality metrics. [https://github.com/zhpn1024/ribotish](https://github.com/zhpn1024/ribotish) ::: Ribo-TISH is a tool for identifying translated ORFs from Ribo-seq data. This module parses the `*_qual.txt` output files to visualize reading frame quality metrics across different read lengths. The module creates one of two visualizations: 1. A stacked bar chart showing the proportion of reads in each reading frame (Frame 0, 1, 2) for read lengths 25-34nt 2. A heatmap showing the percentage distribution of read lengths within each sample ### File search patterns ```yaml ribotish/qual: fn: '*_qual.txt' num_lines: 10 ``` --- ## riboWaltz :::note Computes P-site offsets and performs quality control for ribosome profiling data. [https://github.com/LabTranslationalArchitectomics/riboWaltz](https://github.com/LabTranslationalArchitectomics/riboWaltz) ::: riboWaltz computes P-site offsets and performs quality control for ribosome profiling data. The module parses QC output files from riboWaltz and generates visualizations for: - **P-site region distribution**: Shows where P-sites map across transcript regions (5' UTR, CDS, 3' UTR). Good Ribo-seq data shows >70% CDS enrichment. - **Reading frame distribution**: Shows P-site distribution across reading frames for each transcript region. Frame 0 should be >50% in CDS but not in UTRs. - **Metaprofiles**: Shows P-site frequency around start and stop codons. Good data shows trinucleotide periodicity with Frame 0 peaks. Supported input files: - `*ribowaltz*psite_region.tsv` - P-site region distribution - `*ribowaltz*frames.tsv` - Reading frame distribution - `*ribowaltz*metaprofile_psite.tsv` - Metaprofile around start/stop codons Files must contain "ribowaltz" in the filename since headers are generic. Both tab-delimited and comma-delimited files are supported. ### File search patterns ```yaml ribowaltz/frames: contents_re: "sample[,\t]region[,\t]frame[,\t]count[,\t]scaled_count" fn: '*ribowaltz*frames.tsv' num_lines: 1 ribowaltz/metaprofile: contents_re: "sample[,\t]region[,\t]x[,\t]y" fn: '*ribowaltz*metaprofile_psite.tsv' num_lines: 1 ribowaltz/psite_region: contents_re: "sample[,\t]region[,\t]count[,\t]scaled_count" fn: '*ribowaltz*psite_region.tsv' num_lines: 1 ``` --- ## Riker :::note Fast Rust toolkit that ports key sequencing QC tools from Picard. [https://github.com/fulcrumgenomics/riker](https://github.com/fulcrumgenomics/riker) ::: [Riker](https://github.com/fulcrumgenomics/riker) is a fast Rust toolkit for sequencing QC metrics that ports many of the most widely-used tools from Picard with cleaner output and better performance. Supported subtools: - `alignment` (equivalent to Picard's `CollectAlignmentSummaryMetrics`) - `basic` (equivalent to `CollectBaseDistributionByCycle`, `MeanQualityByCycle`, and `QualityScoreDistribution`) - `gcbias` (equivalent to `CollectGcBiasMetrics`) - `hybcap` (equivalent to `CollectHsMetrics`) - `isize` (equivalent to `CollectInsertSizeMetrics`) - `wgs` (equivalent to `CollectWgsMetrics`) Riker emits plain TSV files with `sample` as the first column and snake_case column names; this module parses those files directly. Per-target and per-base coverage outputs from `hybcap` (only emitted with `--per-target-coverage`) are not parsed in this version. The `error` subtool is also not yet supported. #### Coverage thresholds Riker emits cumulative coverage fractions for `wgs` (e.g. `frac_bases_at_30x`) and `hybcap` (e.g. `frac_target_bases_30x`). The threshold shown in the General Statistics table can be customised: ```yaml riker_config: general_stats_target_coverage: - 10 - 30 ``` ### File search patterns ```yaml riker/alignment: contents_re: ^sample\b.*\bcategory\b fn: '*.alignment-metrics.txt' num_lines: 1 riker/basic_base_dist: contents_re: ^sample\b.*\bfrac_a\b fn: '*.base-distribution-by-cycle.txt' num_lines: 1 riker/basic_mean_quality: contents_re: ^sample\b.*\bmean_quality\b fn: '*.mean-quality-by-cycle.txt' num_lines: 1 riker/basic_quality_dist: contents_re: ^sample\b.*\bfrac_bases\b fn: '*.quality-score-distribution.txt' num_lines: 1 riker/gcbias_detail: contents_re: ^sample\b.*\bnormalized_coverage\b fn: '*.gcbias-detail.txt' num_lines: 1 riker/gcbias_summary: contents_re: ^sample\b.*\bgc_0_19_normcov\b fn: '*.gcbias-summary.txt' num_lines: 1 riker/hybcap_metrics: contents_re: ^sample\b.*\bbait_territory\b fn: '*.hybcap-metrics.txt' num_lines: 1 riker/isize_histogram: contents_re: ^sample\b.*\bfr_count\b fn: '*.isize-histogram.txt' num_lines: 1 riker/isize_metrics: contents_re: ^sample\b.*\bpair_orientation\b fn: '*.isize-metrics.txt' num_lines: 1 riker/wgs_coverage: contents_re: ^sample\b.*\bbases_at_or_above\b fn: '*.wgs-coverage.txt' num_lines: 1 riker/wgs_metrics: contents_re: ^sample\b.*\bgenome_territory\b fn: '*.wgs-metrics.txt' num_lines: 1 ``` --- ## RNA-SeQC :::note RNA-Seq metrics for quality control and process optimization. [https://github.com/getzlab/rnaseqc](https://github.com/getzlab/rnaseqc) ::: The module parses results generated by RNA-SeQC (not to be confused with [RSeQC](http://rseqc.sourceforge.net/), which MultiQC also supports). This module shows the Spearman correlation heatmap if both Spearman and Pearson's are found. To plot Pearson's by default instead, add the following to your MultiQC config file: ```yaml rna_seqc: default_correlation: pearson ``` ### File search patterns ```yaml rna_seqc/correlation: fn_re: corrMatrix(Pearson|Spearman)\.txt rna_seqc/coverage: fn_re: meanCoverageNorm_(high|medium|low)\.txt rna_seqc/html: contents: RNA-SeQC v fn: index.html num_lines: 200 rna_seqc/metrics_v1: contents: "Sample\tNote\t" fn: '*metrics.tsv' rna_seqc/metrics_v2: contents: High Quality Ambiguous Alignment Rate fn: '*metrics.tsv' ``` --- ## Rockhopper :::note Bacterial RNA-seq analysis: align reads to coding sequences, rRNAs, tRNAs, and miscellaneous RNAs. [https://cs.wellesley.edu/~btjaden/Rockhopper/](https://cs.wellesley.edu/~btjaden/Rockhopper/) ::: It can align on both the sense and anti-sense strand, assemble transcripts, identify transcript boundaries, discover novel transcripts such as small RNAs ### File search patterns ```yaml rockhopper: contents: Number of gene-pairs predicted to be part of the same operon fn: summary.txt max_filesize: 500000 ``` --- ## RSEM :::note Estimates gene and isoform expression levels from RNA-Seq data. [https://deweylab.github.io/RSEM/](https://deweylab.github.io/RSEM/) ::: Supported scripts: - `rsem-calculate-expression` This module search for the file `.cnt` created by RSEM into directory named `PREFIX.stat` ### File search patterns ```yaml rsem: fn: '*.cnt' ``` --- ## RSeQC :::note Evaluates high throughput RNA-seq data. [http://rseqc.sourceforge.net/](http://rseqc.sourceforge.net/) ::: The module parses results generated by RSeQC, a package that provides a number of useful modules that can comprehensively evaluate high throughput RNA-seq data. Supported scripts: - `bam_stat` - `gene_body_coverage` - `infer_experiment` - `inner_distance` - `junction_annotation` - `junction_saturation` - `read_distribution` - `read_duplication` - `read_gc` - `tin` You can choose to hide sections of RSeQC output and customise their order. To do this, add and customise the following to your MultiQC config file: ```yaml rseqc_sections: - read_distribution - tin - gene_body_coverage - inner_distance - read_gc - read_duplication - junction_annotation - junction_saturation - infer_experiment - bam_stat ``` Change the order to rearrange sections or remove to hide them from the report. Note that some scripts (for example, `junction_annotation.py`) write the logs to stderr. To make a file parable by MultiQC, redirect the stderr to a file using `2> mysample.log`. ### File search patterns ```yaml rseqc/bam_stat: contents: 'Proper-paired reads map to different chrom:' max_filesize: 500000 rseqc/gene_body_coverage: fn: '*.geneBodyCoverage.txt' rseqc/infer_experiment: - fn: '*infer_experiment.txt' - contents: Fraction of reads explained by max_filesize: 500000 rseqc/inner_distance: fn: '*.inner_distance_freq.txt' rseqc/junction_annotation: contents: 'Partial Novel Splicing Junctions:' max_filesize: 500000 rseqc/junction_saturation: fn: '*.junctionSaturation_plot.r' rseqc/read_distribution: contents: Group Total_bases Tag_count Tags/Kb max_filesize: 500000 rseqc/read_duplication_pos: fn: '*.pos.DupRate.xls' rseqc/read_gc: fn: '*.GC.xls' rseqc/tin: contents: TIN(median) fn: '*.summary.txt' num_lines: 1 ``` --- ## Salmon :::note Quantifies expression of transcripts using RNA-seq data. [https://combine-lab.github.io/salmon/](https://combine-lab.github.io/salmon/) ::: The Salmon module parses `meta_info.json`, `lib_format_counts.json` and `flenDist.txt` files, if found. :::note Note that `meta_info.json` must be within a directory called either `aux_info` or `aux` and will be ignored otherwise. ::: ### File search patterns ```yaml salmon/fld: fn: flenDist.txt salmon/lfc: fn: lib_format_counts.json salmon/meta: contents: salmon_version fn: meta_info.json max_filesize: 50000 num_lines: 10 ``` --- ## Sambamba :::note Toolkit for interacting with BAM/CRAM files. [https://lomereiter.github.io/sambamba/](https://lomereiter.github.io/sambamba/) ::: It is functionally similar to Samtools, but the source code is written in the D Language. It allows for faster performance while still being easy to use. Supported commands: - `markdup` #### markdup This module parses key phrases in the output log files to find duplicate + unique reads and then calculates duplicate rate per sample. It will work for both single and paired-end data. The absolute number of reads by type are displayed in a stacked bar plot, and duplicate rates are in the general statistics table. Duplicate rates are calculated as follows: #### Paired end > `duplicate_rate = duplicateReads / (sortedEndPairs * 2 + singleEnds - singleUnmatchedPairs) * 100` #### Single end > `duplicate_rate = duplicateReads / singleEnds * 100` If Sambamba Markdup is invoked using Snakemake, the following bare-bones rule should work fine: ``` rule markdup: input: "data/align/{sample}.bam" output: "data/markdup/{sample}.markdup.bam" log: "data/logs/{sample}.log" shell: "sambamba markdup {input} {output} > {log} 2>&1" ``` ### File search patterns ```yaml sambamba/markdup: contents: finding positions of the duplicate reads in the file num_lines: 50 ``` --- ## Samblaster :::note Marks duplicates and extracts discordant and split reads from sam files. [https://github.com/GregoryFaust/samblaster](https://github.com/GregoryFaust/samblaster) ::: ### File search patterns ```yaml samblaster: contents: 'samblaster: Version' ``` --- ## Samtools :::note Toolkit for interacting with BAM/CRAM files. [http://www.htslib.org](http://www.htslib.org) ::: Supported commands: - `ampliconclip` - `coverage` - `flagstats` - `idxstats` - `markdup` - `rmdup` - `stats` #### idxstats The `samtools idxstats` prints its results to standard out (no consistent file name) and has no header lines (no way to recognise from content of file). As such, `idxstats` result files must have the string `idxstat` somewhere in the filename. There are a few MultiQC config options that you can add to customise how the idxstats module works. A typical configuration could look as follows: ```yaml # Always include these chromosomes in the plot samtools_idxstats_always: - X - Y # Never include these chromosomes in the plot samtools_idxstats_ignore: - MT # Threshold where chromosomes are ignored in the plot. # Should be a fraction, default is 0.001 (0.1% of total) samtools_idxstats_fraction_cutoff: 0.001 # Name of the X and Y chromosomes. # If not specified, MultiQC will search for any chromosome # names that look like x, y, chrx or chry (case-insensitive search) samtools_idxstats_xchr: myXchr samtools_idxstats_ychr: myYchr ``` ### coverage You can include and exclude contigs based on name or pattern. For example, you could add the following to your MultiQC config file: ```yaml samtools_coverage: include_contigs: - "chr*" exclude_contigs: - "*_alt" - "*_decoy" - "*_random" - "chrUn*" - "HLA*" - "chrM" - "chrEBV" ``` Note that exclusion supersedes inclusion for the contig filters. If you want to see what is being excluded, you can set `show_excluded_debug_logs` to `True`: ```yaml samtools_coverage: show_excluded_debug_logs: True ``` ### General Statistics Columns You can customize which metrics from samtools modules appear in the General Statistics table. For example, to show reads mapped percentage and error rate from stats module, and add reads mapped from flagstat module: ```yaml general_stats_columns: samtools/stats: columns: reads_mapped_percent: title: "% Mapped" description: "% Mapped reads from samtools stats" hidden: false error_rate: title: "Error rate" description: "Error rate from samtools stats" hidden: false samtools/flagstat: columns: mapped_passed: title: "Flagstat Mapped" description: "Reads mapped from samtools flagstat" hidden: false ``` Each samtools submodule has its own namespace in the configuration - `samtools/ampliconclip` - `samtools/coverage` - `samtools/flagstats` - `samtools/idxstats` - `samtools/markdup` - `samtools/rmdup` - `samtools/stats` ### File search patterns ```yaml samtools/ampliconclip: contents: - 'COMMAND:' - samtools ampliconclip num_lines: 11 samtools/coverage: contents: "#rname\tstartpos\tendpos\tnumreads\tcovbases\tcoverage\tmeandepth\tmeanbaseq\t\ meanmapq" num_lines: 10 samtools/flagstat: contents: in total (QC-passed reads + QC-failed reads) samtools/idxstats: fn: '*idxstat*' samtools/markdup_json: contents: - '"COMMAND":' - samtools markdup num_lines: 10 samtools/markdup_txt: contents: - '^COMMAND:' - samtools markdup num_lines: 2 samtools/rmdup: contents: '[bam_rmdup' samtools/stats: contents: This file was produced by samtools stats ``` --- ## Sargasso :::note Separates mixed-species RNA-seq reads according to their species of origin. [http://biomedicalinformaticsgroup.github.io/Sargasso/](http://biomedicalinformaticsgroup.github.io/Sargasso/) ::: ### File search patterns ```yaml sargasso: fn: overall_filtering_summary.txt ``` --- ## Seqera Platform CLI :::note Reports statistics generated by the Seqera Platform CLI. [https://github.com/seqeralabs/tower-cli](https://github.com/seqeralabs/tower-cli) ::: Seqera Platform CLI module for MultiQC. Parses a tar-gz dump containing logs and stats from a Seqera Platform run, that is, the `runs_SmUkr43Nul49G.tar.gz` file generated by the following command: ```sh tw runs dump -id=SmUkr43Nul49G --workspace=seqeralabs/benchmarks --output=runs_SmUkr43Nul49G.tar.gz ``` Expects the dump to contain a `workflow.json` file, along with `workflow-load.json`. To allow reading the tar-gz archives, run with `ignore_images: false` in the config, e.g.: ```sh multiqc . --cl-config 'ignore_images: false' ``` Can also parse an uncompressed version of the dump, that is, a `workflow.json` file and a `workflow-load.json` sitting together in a directory. ### File search patterns ```yaml seqera_cli/json: fn: workflow.json seqera_cli/run_dump: fn: runs_*.tar.gz ``` --- ## Seqfu :::note Manipulate FASTA/FASTQ files. [https://telatin.github.io/seqfu2](https://telatin.github.io/seqfu2) ::: Supported commands: - `stats`: ### seqfu stats #### Input files `seqfu stats` can generated reports in multiple formats, see https://telatin.github.io/seqfu2/tools/stats.html. Only TSVs with headers (default `seqfu stats` output) are currently detected and parsed by MultiQC. :::note `seqfu stats` has a `--multiqc` option that generates a `_mqc.txt` file can be used with MuliQC as custom content. This is different from this module which enables additional features. ::: #### Configuration Sample names are automatically extracted from the "File" columns by default. If you only have one sample per file and prefer to use the filename as the sample name instead, you can set the global `use_filename_as_sample_name` option to `true` or list `seqfu` under it. ### File search patterns ```yaml seqfu/stats: contents: "File\t#Seq\tTotal bp\tAvg\tN50\tN75\tN90\tauN\tMin\tMax" num_lines: 1 ``` --- ## SeqKit :::note Cross-platform and ultrafast toolkit for FASTA/Q file manipulation. [https://bioinf.shenwei.me/seqkit/](https://bioinf.shenwei.me/seqkit/) ::: SeqKit is a cross-platform and ultrafast toolkit for FASTA/Q file manipulation. Supported commands: - `stats` The module parses output from `seqkit stats` which provides simple statistics of FASTA/Q files including sequence counts, total length, N50, GC content, and quality metrics for FASTQ files. #### stats The `seqkit stats` command produces tabular output with columns for file, format, type, num_seqs, sum_len, min_len, avg_len, max_len, and optionally Q1, Q2, Q3, sum_gap, N50, Q20(%), Q30(%), AvgQual, and GC(%) when run with the `--all` flag. To generate output suitable for MultiQC, run seqkit stats with the `--tabular` flag: ```bash seqkit stats --all --tabular *.fastq.gz > seqkit_stats.tsv ``` ### File search patterns ```yaml seqkit/stats: contents_re: ^file\s+format\s+type\s+num_seqs\s+sum_len num_lines: 1 ``` --- ## Sequali :::note Sequencing quality control for both long-read and short-read data. [https://github.com/rhpvorderman/sequali](https://github.com/rhpvorderman/sequali) ::: Features adapter search, overrepresented sequence analysis and duplication analysis and supports FASTQ and uBAM inputs. ### File search patterns ```yaml sequali: contents: '"sequali_version"' fn: '*.json' num_lines: 10 ``` --- ## SeqWho :::note Determines FASTQ(A) sequencing file source protocol and the species of origin, to check that the composition of the library is expected. [https://daehwankimlab.github.io/seqwho/](https://daehwankimlab.github.io/seqwho/) ::: ### File search patterns ```yaml seqwho: contents: ' "Per Base Seq": [' num_lines: 10 ``` --- ## SeqyClean :::note Filters adapters, vectors, and contaminants while quality trimming. [https://github.com/ibest/seqyclean](https://github.com/ibest/seqyclean) ::: SeqyClean is a comprehensive preprocessing software application for NGS reads, that removes noise from FastQ files to improve de-novo genome assembly and genome mapping. The module parses the `*SummaryStatistics.tsv` files that results from a SeqyClean cleaning. ### File search patterns ```yaml seqyclean: fn: '*_SummaryStatistics.tsv' ``` --- ## SexDetErrmine :::note Calculates relative coverage of X and Y chromosomes and their associated error bars from the depth of coverage at specified SNPs. [https://github.com/TCLamnidis/Sex.DetERRmine](https://github.com/TCLamnidis/Sex.DetERRmine) ::: ### File search patterns ```yaml sexdeterrmine: fn: sexdeterrmine.json ``` --- ## Sickle :::note A windowed adaptive trimming tool for FASTQ files using quality. [https://github.com/najoshi/sickle](https://github.com/najoshi/sickle) ::: The `stdout` can be captured by directing it to a file e.g. `sickle command 2> sickle_out.log` The module generates the sample names based on the filenames. ### File search patterns ```yaml sickle: contents_re: 'FastQ \w*\s?records kept: .*' num_lines: 2 ``` --- ## sincei :::note Toolkit for processing and analyzing single-cell (epi)genomics data. [https://sincei.readthedocs.io](https://sincei.readthedocs.io) ::: sincei (short for Single Cell Informatics) is a command-line toolkit for exploration of single-cell epigenomics data. It accommodates data from a wide range of single-cell protocols, such as droplet-based (10x Genomics) and plate-based protocols, gene expression (scRNA-seq) and epigenomics (scATAC, scCUTnTAG, scBS-seq). sincei can be used for quality control of these datasets directly from BAM files (read-level QC), as well as after signal aggregation (count-level). Additional functionalities include filtering, dimensionality reduction, and plotting of single-cell data. The MultiQC module for sincei parses the following text outputs: - `scFilterStats` (default output file) - `scCountQC --outMetrics` (currently the cell-level metrics are supported) sincei reports one row per cell, identified by `Cell_ID`. MultiQC parses the sample name from the part of `Cell_ID` before `::` and aggregates metrics across cells by taking the median per sample. Each row in the report tables therefore represents one sample, summarising all of its cells. ### File search patterns ```yaml sincei/scCountQC: contents: "Cell_ID\tbarcodes\tsample\tn_genes_by_counts\tlog1p_n_genes_by_counts\t\ total_counts" fn: '*.cells.tsv' sincei/scFilterStats: contents: "Cell_ID\tTotal_sampled\tFiltered\tBlacklisted\tLow_MAPQ\tMissing_Flags\t\ Excluded_Flags" num_lines: 1 ``` --- ## Skewer :::note Adapter trimming tool for NGS paired-end sequences. [https://github.com/relipmoc/skewer](https://github.com/relipmoc/skewer) ::: ### File search patterns ```yaml skewer: contents: 'maximum error ratio allowed (-r):' ``` --- ## Slamdunk :::note Tool to analyze SLAM-Seq data. [http://t-neumann.github.io/slamdunk/](http://t-neumann.github.io/slamdunk/) ::: This module should be able to parse logs from v0.2.2-dev onwards. ### File search patterns ```yaml slamdunk/PCA: contents: '# slamdunk PCA' num_lines: 1 slamdunk/rates: contents: '# slamdunk rates' num_lines: 1 slamdunk/summary: contents: '# slamdunk summary' num_lines: 1 slamdunk/tcperreadpos: contents: '# slamdunk tcperreadpos' num_lines: 1 slamdunk/tcperutrpos: contents: '# slamdunk tcperutr' num_lines: 1 slamdunk/utrrates: contents: '# slamdunk utrrates' num_lines: 1 ``` --- ## Snippy :::note Rapid haploid variant calling and core genome alignment. [https://github.com/tseemann/snippy](https://github.com/tseemann/snippy) ::: The following commands are implemented: - `snippy` - Variant type descriptive statistics. - Parses summary `prefix.txt` file that is generated. - `snippy-core` - Core genome alignment descriptive statistics. - Parses summary `prefix.txt` file that is generated. ### File search patterns ```yaml snippy/snippy: contents: snippy num_lines: 20 snippy/snippy-core: contents_re: ID\tLENGTH\tALIGNED\tUNALIGNED\tVARIANT\tHET\tMASKED\tLOWCOV num_lines: 1 ``` --- ## SnpEff :::note Annotates and predicts the effects of variants on genes (such as amino acid changes). [http://snpeff.sourceforge.net/](http://snpeff.sourceforge.net/) ::: MultiQC parses the summary `.csv` file that is generated by SnpEff. Note that you must run SnpEff with `-csvStats ` for this to be generated. See the [SnpEff](http://snpeff.sourceforge.net/SnpEff_manual.html#outputSummary) documentation for more information. ### File search patterns ```yaml snpeff: contents: SnpEff_version max_filesize: 5000000 ``` --- ## SNPsplit :::note Allele-specific alignment sorter. Determines allelic origin of reads that cover known SNP positions. [https://www.bioinformatics.babraham.ac.uk/projects/SNPsplit/](https://www.bioinformatics.babraham.ac.uk/projects/SNPsplit/) ::: Currently only the "Allele-tagging" and "Allele-sorting" reports are supported. The log files from the genome creation steps are not parsed and there are no plots/tables produced from the "SNP coverage" report. Differences between the numbers in the tagging and sorting reports are due to paired-end reads. For these, if only a single mate in a pair is assigned to a genome then it will "rescue" its mate and both will be "sorted" into that genome (even though only one of them was tagged). Conversely, if the mates in a pair are tagged as arising from different genomes, then the pair as a whole is unassignable. ### File search patterns ```yaml snpsplit/new: fn: '*SNPsplit_report.yaml' snpsplit/old: contents: 'Writing allele-flagged output file to:' num_lines: 2 ``` --- ## Somalier :::note Genotype to pedigree correspondence checks from sketches derived from BAM/CRAM or VCF. [https://github.com/brentp/somalier](https://github.com/brentp/somalier) ::: Somalier can be used to find sample swaps or duplicates in cancer projects, where there is often no jointly-called VCF across samples. It is also extremely efficient and so can be used to find all-vs-all relatedness estimates for thousands of samples. It also outputs information on sex, depth, heterozgyosity, and ancestry to be used for general QC. ### File search patterns ```yaml somalier/pairs: contents: hom_concordance fn: '*.pairs.tsv' num_lines: 5 somalier/samples: contents: '#family_id' fn: '*.samples.tsv' num_lines: 5 somalier/somalier-ancestry: fn: '*.somalier-ancestry.tsv' ``` --- ## som.py :::note Benchmarks somatic variant calls against gold standard truth datasets. [https://github.com/Illumina/hap.py/blob/master/doc/sompy.md](https://github.com/Illumina/hap.py/blob/master/doc/sompy.md) ::: ### File search patterns ```yaml sompy: contents: ',sompyversion,sompycmd' fn: '*.stats.csv' num_lines: 2 ``` --- ## SortMeRNA :::note Program for filtering, mapping and OTU-picking NGS reads in metatranscriptomic and metagenomic data. [http://bioinfo.lifl.fr/RNA/sortmerna/](http://bioinfo.lifl.fr/RNA/sortmerna/) ::: The core algorithm is based on approximate seeds and allows for fast and sensitive analyses of nucleotide sequences. The main application of SortMeRNA is filtering ribosomal RNA from metatranscriptomic data. The module parses the log files, which are created when `SortMeRNA` is run with the `--log` option. The default header in the 'General Statistics' table is '% rRNA'. Users can override this using the configuration option: ```yaml sortmerna: tab_header: "My database hits" ``` ### File search patterns ```yaml sortmerna: contents: Minimal SW score based on E-value ``` --- ## Sourmash :::note Quickly searches, compares, and analyzes genomic and metagenomic data sets. [https://github.com/sourmash-bio/sourmash](https://github.com/sourmash-bio/sourmash) ::: The module can summarise data from the following sourmash output files (descriptions from command line help output): - `sourmash compare` - create a similarity matrix comparing many samples. - `sourmash gather` - search a metagenome signature against databases. Additional information on sourmash and its outputs is available on the [sourmash documentation website](https://sourmash.readthedocs.io/en/latest/). `sourmash gather` is modelled after the Kraken module, and builds a bar graph that shows the coverage of top-5 genomes covered most by all samples. The number of top genomes can be customized in the config file: ```yaml sourmash: gather: top_n: 5 ``` ### File search patterns ```yaml sourmash/compare: fn: '*.labels.txt' sourmash/gather: contents: intersect_bp,f_orig_query,f_match,f_unique_to_query,f_unique_weighted, num_lines: 1 ``` --- ## Space Ranger :::note Tool to analyze 10x Genomics spatial transcriptomics data. [https://support.10xgenomics.com/spatial-gene-expression/software/pipelines/latest/what-is-space-ranger](https://support.10xgenomics.com/spatial-gene-expression/software/pipelines/latest/what-is-space-ranger) ::: The module parses the quality reports generated by 10x Genomics Space Ranger (tested on Cell Ranger 2.1). Space Ranger has 2 main modules: `count` and `vdj`. The module summarises the main information useful for QC, including: - sequencing metrics - mapping metrics - estimated number of spots, and reads per spot. - detected genes per spot Note that clustering results, differentially expressed genes and the images themselves are not reported. The input files are web summaries generated by Space Ranger. Expected file names are `*web_summary.html`. Sample IDs are parsed directly from the reports. If present in the original report, any warning is reported as well. ### File search patterns ```yaml spaceranger/count_html: - contents: '"command":"Space Ranger","subcommand":"count"' fn: '*.html' num_lines: 20 - contents: '"command": "Space Ranger", "subcommand": "count"' fn: '*.html' num_lines: 20 ``` --- ## Stacks :::note Analyzes restriction enzyme-based data (e.g. RAD-seq). [http://catchenlab.life.illinois.edu/stacks/](http://catchenlab.life.illinois.edu/stacks/) ::: This module is designed to only parse some of the output from the Stacks `denovo_map` pipeline. The module works with Stacks version 2.1 or greater. If you are missing some functionality, please submit an issue on the [MultiQC github page](https://github.com/MultiQC/MultiQC) ### File search patterns ```yaml stacks/gstacks: contents: BEGIN effective_coverages_per_sample fn: gstacks.log.distribs stacks/populations: contents: BEGIN missing_samples_per_loc_prefilters fn: populations.log.distribs stacks/sumstats: contents: "# Pop ID\tPrivate\tNum_Indv\tVar\tStdErr\tP\tVar" fn: '*.sumstats_summary.tsv' max_filesize: 1000000 ``` --- ## STAR :::note Universal RNA-seq aligner. [https://github.com/alexdobin/STAR](https://github.com/alexdobin/STAR) ::: This module parses summary statistics from the `Log.final.out` log files. Sample names are taken either from the filename prefix (`sampleNameLog.final.out`) when set with `--outFileNamePrefix` in STAR. If there is no filename prefix, the sample name is set as the name of the directory containing the file. In addition to this summary log file, the module parses `ReadsPerGene.out.tab` files generated with `--quantMode GeneCounts`, if found. ### File search patterns ```yaml star: fn: '*Log.final.out' star/genecounts: fn: '*ReadsPerGene.out.tab' ``` --- ## Supernova :::note De novo genome assembler of 10X Genomics linked-reads. [https://www.10xgenomics.com/](https://www.10xgenomics.com/) ::: The module parses the reports from an assembly run. As a bare minimum it requires the file `report.txt`, found in the folder `sampleID/outs/`, to function. Note! If you are anything like the author (@remiolsen), you might only have files (often renamed to, e.g. `sampleID-report.txt`) lying around due to disk space limitations and for ease of sharing with your colleagues. This module will search for `*report*.txt`. If available the stats in the report file will be superseded by the higher precision numbers found in the file `sampleID/outs/assembly/stats/summary.json`. In the same folder, this module will search for the following plots and render them: - `histogram_molecules.json` -- Inferred molecule lengths - `histogram_kmer_count.json` -- Kmer multiplicity This module has been tested using Supernova versions `1.1.4` and `1.2.0` #### Important note Due to the size of the `histogram_kmer_count.json` files, MultiQC is likely to skip these files. To be able to display these you will need to change the MultiQC configuration to allow for larger logfiles, see the MultiQC [documentation](../usage/troubleshooting#big-log-files). For instance, if you run MultiQC as part of an analysis pipeline, you can create a `multiqc_config.yaml` file in the working directory, containing the following line: ```yaml log_filesize_limit: 100000000 ``` ### File search patterns ```yaml supernova/kmers: contents: '"description": "kmer_count",' fn: histogram_kmer_count.json num_lines: 10 supernova/molecules: contents: '"description": "molecules",' fn: histogram_molecules.json num_lines: 10 supernova/report: contents: '- assembly checksum =' fn: '*report*.txt' num_lines: 100 supernova/summary: contents: '"lw_mean_mol_len":' fn: summary.json num_lines: 120 ``` --- ## Sylph-tax :::note Taxonomic profiling of metagenomic reads. [https://sylph-docs.github.io/](https://sylph-docs.github.io/), [https://sylph-docs.github.io/sylph-tax/](https://sylph-docs.github.io/sylph-tax/) ::: The module supports outputs from sylphtax, that look like the following: ```tsv clade_name relative_abundance sequence_abundance ANI (if strain-level) d__Bacteria 100.00010000000002 99.99999999999999 NA d__Bacteria|p__Bacillota 24.640800000000002 18.712699999999998 NA d__Bacteria|p__Bacillota_A 47.333499999999994 52.5969 NA ``` A bar graph is generated that shows the relative abundance for each sample that fall into the top-10 categories for each taxa rank. The top categories are calculated by summing the relative abundances across all samples. The number of top categories to plot can be customized in the config file: ```yaml sylphtax: top_n: 10 ``` ### File search patterns ```yaml sylphtax: fn: '*.sylphmpa' ``` --- ## telseq :::note Estimates telomere length from whole genome sequencing data (BAMs). [https://github.com/zd1/telseq](https://github.com/zd1/telseq) ::: Telomeres play a key role in replicative ageing and undergo age-dependent attrition in vivo. TelSeq measures average telomere length from whole genome or exome shotgun sequence data. ### File search patterns ```yaml telseq: contents: "ReadGroup\tLibrary\tSample\tTotal\tMapped\tDuplicates\tLENGTH_ESTIMATE" num_lines: 3 ``` --- ## THetA2 :::note Estimates tumour purity and clonal / subclonal copy number. [http://compbio.cs.brown.edu/projects/theta/](http://compbio.cs.brown.edu/projects/theta/) ::: The module plots the % germline and % tumour subclone for each sample. Note that each sample can have multiple maximum likelihood solutions - the MultiQC module plots proportions for the first one in the results file (`*.BEST.results`). Also note that if there are more than 5 tumour subclones, their percentages are summed. ### File search patterns ```yaml theta2: fn: '*.BEST.results' ``` --- ## Tophat :::note Splice junction RNA-Seq reads mapper for mammalian-sized genomes. [https://ccb.jhu.edu/software/tophat/](https://ccb.jhu.edu/software/tophat/) ::: ### File search patterns ```yaml tophat: fn: '*align_summary.txt' shared: true ``` --- ## Trim Galore :::note Quality and adapter trimming for next-generation sequencing data, with special handling for RRBS libraries. [https://github.com/FelixKrueger/TrimGalore](https://github.com/FelixKrueger/TrimGalore) ::: [Trim Galore](https://github.com/FelixKrueger/TrimGalore) provides consistent quality and adapter trimming for next-generation sequencing data, with special handling for Reduced Representation Bisulfite Sequencing (RRBS) and small-RNA libraries. This MultiQC module supports Trim Galore v2.0, which is a Rust rewrite of the original Perl-based v0.6 that has a new JSON output file summarising results. The earlier v0.6 versions of Trim Galore that wrapped Cutadapt are supported with reporting via the Cutadapt module. The old log format is still produced, but the Cutadapt module search pattern is configured to skip reports mentioning Trim Galore v2+. If you delete the JSON but keep the v2 text file, the sample will not be reported by either module. #### Paired-end sample grouping R1 and R2 of a paired-end sample are grouped automatically into a single row in the General Statistics and Pair Validation tables. Click the expand arrow on a grouped row to see the per-read values. The grouping is derived from the file list inside each JSON report, so it does not depend on filename patterns. To disable automatic grouping and show one row per read everywhere: ```yaml trim_galore_config: auto_group_pairs: false ``` Auto-grouping can be combined with the global [`table_sample_merge`](../reports/customisation.md#sample-grouping) config option to merge further — for example to group lanes of an already-paired sample. ### File search patterns ```yaml trim_galore: fn: '*_trimming_report.json' ``` --- ## Trimmomatic :::note Read trimming tool for Illumina NGS data. [http://www.usadellab.org/cms/?page=trimmomatic](http://www.usadellab.org/cms/?page=trimmomatic) ::: The module parses the stderr output, that can be captured by directing it to a file e.g.: ```sh trimmomatic command 2> trim_out.log ``` By default, the module generates the sample names based on the input FastQ file names in the command line used by Trimmomatic. If you prefer, you can tell the module to use the filenames as sample names instead. To do so, use the following config option: ```yaml use_filename_as_sample_name: true ``` Note: The old `trimmomatic.s_name_filenames` option is deprecated and will be removed in a future version. ### File search patterns ```yaml trimmomatic: contents_re: ^Trimmomatic ``` --- ## Truvari :::note Benchmarking, merging, and annotating structural variants. [https://github.com/ACEnglish/truvari](https://github.com/ACEnglish/truvari) ::: Supported commands: - `bench` ### File search patterns ```yaml truvari/bench: contents_re: .*truvari.* bench.* fn: log.txt num_lines: 10 ``` --- ## UMICollapse :::note Algorithms for efficiently collapsing reads with Unique Molecular Identifiers. [https://github.com/Daniel-Liu-c0deb0t/UMICollapse](https://github.com/Daniel-Liu-c0deb0t/UMICollapse) ::: Sample names are extracted from log files if possible. In logs, the command line arguments are printed, which must have both the input and output file paths. ``` umicollapse bam -i SRR19887568.sorted.bam -o SRR19887568.umi_dedup.sorted.bam Arguments [bam, -i, SRR19887568.sorted.bam, -o, SRR19887568.umi_dedup.sorted.bam] ``` `umicollapse` requires both -i and -o flags as valid file paths. Process substitution is not supported currently by umicollapse, but in case it is used for the -i flag, we fallback to the log file name. ### File search patterns ```yaml umicollapse: contents: 'UMI collapsing finished in ' num_lines: 100 ``` --- ## UMI-tools :::note Tools for dealing with Unique Molecular Identifiers (UMIs)/(RMTs) and scRNA-Seq barcodes. [https://github.com/CGATOxford/UMI-tools](https://github.com/CGATOxford/UMI-tools) ::: Currently, `dedup` and `extract` commands are supported. Sample names are extracted from log files if possible. In logs, input and output file paths are printed. However, either can be redirected from stdin/stdout: ```bash $ umi_tools extract -I input.fastq > result.fastq stdin : <_io.TextIOWrapper name='input.fastq' mode='r' encoding='UTF-8'> stdout : <_io.TextIOWrapper name='' encoding='ascii'> ``` ```bash $ cat input.fastq | umi_tools extract -S output.fastq stdin : <_io.TextIOWrapper name='' mode='r' encoding='UTF-8'> stdout : <_io.TextIOWrapper name='result.fastq' encoding='ascii'> ``` `umi_tools` requires at least one of the -I or -S options to be specified, so we can expect either one of those to be present in the log file, and we guess prioritizing the output file name. If this assumption fails, we extract the sample name from the log file name. ### File search patterns ```yaml umitools/dedup: contents: '# output generated by dedup' num_lines: 100 umitools/extract: contents: '# output generated by extract' num_lines: 100 ``` --- ## VarScan2 :::note Variant detection in massively parallel sequencing data. [http://dkoboldt.github.io/varscan/](http://dkoboldt.github.io/varscan/) ::: VarScan is a platform-independent mutation caller for targeted, exome, and whole-genome resequencing data generated on Illumina, SOLiD, Life/PGM, Roche/454, and similar instruments. VarScan can be used to detect different types of variation: - Germline variants (SNPs an dindels) in individual samples or pools of samples. - Multi-sample variants (shared or private) in multi-sample datasets (with mpileup). - Somatic mutations, LOH events, and germline variants in tumor-normal pairs. - Somatic copy number alterations (CNAs) in tumor-normal exome data. The MultiQC module can read output from `mpileup2cns`, `mpileup2snp` and `mpileup2indel` logfiles. ### File search patterns ```yaml varscan2/mpileup2cns: contents: Only variants will be reported num_lines: 10 varscan2/mpileup2indel: contents: Only indels will be reported num_lines: 10 varscan2/mpileup2snp: contents: Only SNPs will be reported num_lines: 10 ``` --- ## VCFTools :::note Program to analyse and reporting on VCF files. [https://vcftools.github.io](https://vcftools.github.io) ::: #### Important General Note - Depending on the size and density of the variant data (vcf), some of the stat files generated by vcftools can be very large. If you find that some of your input files are missing, increase the [config.log_filesize_limit](../usage/troubleshooting#big-log-files) so that the large file(s) will not be skipped by MultiQC. Note, however, that this might make MultiQC very slow! This module parses the outputs from VCFTools' various commands: #### Implemented - `relatedness2` - Plots a heatmap of pairwise sample relatedness. - Not to be confused with the similarly-named command `relatedness` - `TsTv-by-count` - Plots the transition to transversion ratio as a function of alternative allele count (using only bi-allelic SNPs). - `TsTv-by-qual` - Plots the transition to transversion ratio as a function of SNP quality threshold (using only bi-allelic SNPs). - `TsTv-summary` - Plots a bargraph of the summary counts of each type of transition and transversion SNPs. #### To do VCFTools has a number of outputs not yet supported in MultiQC which would be good to add. Please check GitHub if you'd like these added or (better still), would like to contribute! - basic stats - relatedness - freq - depth - [Everything else](https://vcftools.github.io/man_latest.html) ### File search patterns ```yaml vcftools/relatedness2: fn: '*.relatedness2' vcftools/tstv_by_count: fn: '*.TsTv.count' vcftools/tstv_by_qual: fn: '*.TsTv.qual' vcftools/tstv_summary: fn: '*.TsTv.summary' ``` --- ## VEP :::note Determines the effect of variants on genes, transcripts and protein sequences, as well as regulatory regions. [https://www.ensembl.org/info/docs/tools/vep/index.html](https://www.ensembl.org/info/docs/tools/vep/index.html) ::: MultiQC parses the Ensembl VEP summary statistics stored in either HTML or plain text format. Beside VEP's default naming convention, you can run VEP with one of the options below to use this module: - `--stats_file [OUTPUT_FILENAME]_summary.html` _(VEP's default naming convention)_ - `--stats_file [SAMPLE_NAME].vep.html` _(without the `vep` or `summary` suffix, MultiQC will ignore the HTML files)_ - `--stats_file [SAMPLE_NAME]_vep.html` - `--stats_text --stats_file [SAMPLE_NAME].vep.txt` - `--stats_text --stats_file [SAMPLE_NAME]_vep.txt` See the [VEP](https://www.ensembl.org/info/docs/tools/vep/vep_formats.html#stats) documentation for more information. ### File search patterns ```yaml vep/vep_html: contents: VEP summary fn: '*.html' max_filesize: 1000000 num_lines: 10 vep/vep_txt: contents: '[VEP run statistics]' max_filesize: 100000 num_lines: 1 ``` --- ## VerifyBAMID :::note Detects sample contamination and/or sample swaps. [https://genome.sph.umich.edu/wiki/VerifyBamID](https://genome.sph.umich.edu/wiki/VerifyBamID) ::: VerifyBamID checks whether reads match known genotypes or are contaminated as a mixture of two samples. A key step in any genetic analysis is to verify whether data being generated matches expectations. verifyBamID checks whether reads in a BAM file match previous genotypes for a specific sample. In addition, it detects possible sample mixture from population allele frequency only, which can be particularly useful when the genotype data is not available. Using a mathematical model that relates observed sequence reads to an hypothetical true genotype, verifyBamID tries to decide whether sequence reads match a particular individual or are more likely to be contaminated (including a small proportion of foreign DNA), derived from a closely related individual, or derived from a completely different individual. This module currently only imports data from the `.selfSM` output. The chipmix and freemix columns are imported into the general statistics table. A verifyBAMID section is then added, with a table containing the entire selfSM file. If no chip data was parsed, these columns will not be added to the MultiQC report. By default, the module extracts sample names from the first column of the `.selfSM` file. If you prefer to use the filename as the sample name instead, you can set the global `use_filename_as_sample_name` option: ```yaml use_filename_as_sample_name: - verifybamid - verifybamid/selfsm ``` Should you wish to remove one of these columns from the general statistics table add the below lines to the table_columns_visible section of your config file table_columns_visible: verifyBAMID: CHIPMIX: False FREEMIX: False This was designed to work with verifyBamID 1.1.3 January 2018 ### File search patterns ```yaml verifybamid/selfsm: fn: '*.selfSM' ``` --- ## VG :::note Toolkit to manipulate and analyze graphical genomes, including read alignment. [https://github.com/vgteam/vg](https://github.com/vgteam/vg) ::: The module parses the [vg stats](https://github.com/vgteam/vg/wiki/Mapping-short-reads-with-Giraffe#evaluating-with-vg-stats) reports that summarize the stats of read alignment to a graphical genome in a GAM file. `vg stats` is capable of producing many reports summarizing many aspects of graphical genomes, including specific aspects of aligned GAM files such as node coverage. This module is not meant to gather those data. Rather, this module is designed to summarize the alignment performance of GAM files produced by `vg giraffe` created from the stdout of the `vg stats` command: ```sh $ vg stats -a mapped.gam > sample-stats.txt $ cat sample-stats.txt Total alignments: 727413268 Total primary: 727413268 Total secondary: 0 Total aligned: 717826332 Total perfect: 375143620 Total gapless (softclips allowed): 714388968 Total paired: 727413268 Total properly paired: 715400510 Alignment score: mean 129.012, median 132, stdev 31.5973, max 161 (244205781 reads) Mapping quality: mean 52.8552, median 60, stdev 17.7742, max 60 (589259353 reads) Insertions: 3901467 bp in 1466045 read events Deletions: 6759252 bp in 2795331 read events Substitutions: 281648245 bp in 281648245 read events Softclips: 11480269152 bp in 252773804 read events Total time: 291465 seconds Speed: 2495.71 reads/second ``` It is not guaranteed that output created using any other parameter combination can be parsed using this module. The graphical reports are designed to mimic a samtools stats report, including: 1. A bar chart showing the breakdown of aligned, perfectly aligned, and unaligned reads. 2. A violin plot for all metrics. ### File search patterns ```yaml vg/stats: contents: - 'Total perfect:' - 'Total gapless (softclips allowed):' - 'Total time:' - 'Speed:' num_lines: 30 ``` --- ## WhatsHap :::note Phasing genomic variants using DNA reads (aka read-based phasing, or haplotype assembly). [https://whatshap.readthedocs.io/](https://whatshap.readthedocs.io/) ::: The module is currently restricted to the output from `whatshap stats --tsv`. ### File search patterns ```yaml whatshap/stats: contents: "#sample\tchromosome\tfile_name\tvariants\tphased\tunphased\tsingletons" num_lines: 1 ``` --- ## Xengsort :::note Fast xenograft read sorter based on space-efficient k-mer hashing. [https://gitlab.com/genomeinformatics/xengsort](https://gitlab.com/genomeinformatics/xengsort) ::: The module parses results generated by the `xengsort classify` command. **Note**: MultiQC parses the standard output from xengsort, hence one has to redirect command line output to a file in order to use it with the MultiQC module. Also note that the tool does not register any sample name information in the output, so MultiQC attempts to fetch the sample name from the file name by default. Example command that would help MultiQC recognize data for a sample named "SAMPLE": ```sh xengsort classify --index myindex --fastq paired.1.fq.gz --pairs paired.2.fq.gz --prefix myresults --classification count > SAMPLE.txt ``` ### File search patterns ```yaml xengsort: contents: '# Xengsort classify' num_lines: 2 ``` --- ## Xenium :::note Spatial transcriptomics platform from 10x Genomics that provides subcellular resolution. [https://www.10xgenomics.com/platforms/xenium](https://www.10xgenomics.com/platforms/xenium) ::: Xenium is a spatial transcriptomics platform from 10x Genomics that provides subcellular resolution. :::note This module provides basic quality metrics from the Xenium pipeline (total transcripts, cells detected, transcript assignment rates, and median genes per cell). For advanced visualizations including: - Transcript quality distributions by gene category - Cell and nucleus area distributions - Field-of-view quality plots - Segmentation method breakdown - Transcripts per gene distributions Install the [multiqc-xenium-extra](https://pypi.org/project/multiqc-xenium-extra/) plugin: ```bash pip install multiqc multiqc-xenium-extra ``` The plugin automatically adjusts the log filesize limit to parse large Xenium files (`.parquet` and `.h5`), so you don't need to manually configure `log_filesize_limit` in your MultiQC config when using the plugin. ::: The MultiQC module is tested with outputs from xenium-3.x, older versions of xenium output are not supported and may even cause MultiQC to crash (see https://github.com/MultiQC/MultiQC/issues/3344). ### File search patterns ```yaml xenium/experiment: fn: experiment.xenium num_lines: 50 xenium/metrics: contents: num_cells_detected fn: metrics_summary.csv num_lines: 5 ``` --- ## Xenome :::note Classifies reads from xenograft sources. [https://github.com/data61/gossamer/blob/master/docs/xenome.md](https://github.com/data61/gossamer/blob/master/docs/xenome.md) ::: The module parsed results generated by the `xenome classify` command. **Note**: MultiQC parses the standard output from xengsort, hence one has to redirect command line output to a file in order to use it with the MultiQC module. Also note that the tool does not register any sample name information in the output, so MultiQC attempts to fetch the sample name from the file name by default. Example command that would help MultiQC recognize data for a sample named "SAMPLE": ```sh xenome classify -P idx --pairs -i in_1.fastq -i in_2.fastq > SAMPLE.txt ``` ### File search patterns ```yaml xenome: contents: "B\tG\tH\tM\tcount\tpercent\tclass" num_lines: 2 ``` --- ## Supported Tools MultiQC currently has modules to support 181 bioinformatics tools, listed below. Click the tool name to go to the MultiQC documentation for that tool. :::tip[Missing something?] If you would like another tool to to be supported, please [open an issue](https://github.com/MultiQC/MultiQC/issues/new?labels=module%3A+new&template=module-request.yml). :::