Get started

Wave is versatile and you can leverage it in your Nextflow pipelines in several ways. The following guides describe how to quickly get started with Seqera Containers and Nextflow, Nextflow and Wave integration, and the Wave CLI.

Nextflow and Seqera Containers

You can provision containers that include Conda packages through Seqera Containers and use them directly in your Nextflow pipelines.

Prerequisites

• You have either Docker Desktop or Podman installed locally.
• You have Nextflow 23.10.x or newer installed locally.
• Use Singularity 4.x or newer to run the Singularity containers.

In this guide, you'll request a containerized Conda package from Seqera Containers.

Request a Conda package as a Seqera Container

1. Open Seqera Containers in a browser.
2. In the search box, enter samtools.
3. In the search results, select Add in the bioconda::samtools result, and then Get Container to initiate the container build.
4. From the Fetching container modal, copy the the durable container image URI that Seqera Containers provides.
5. Optional: Select View build details to watch Seqera Containers build the requested container in real time.

Create a Nextflow pipeline that uses the container

Nextflow can use the container that Seqera Containers built in the previous section. Use the container URI from Seqera Containers in the container directive.

1. In a terminal window, create a new directory for the Nextflow pipeline.

2. Create a nextflow.config file with the following contents:

   docker {
     enabled = true
   }

3. Create a main.nf file with the following contents:

   process SAMTOOLS {
     container '<container_uri>'
     debug true
     """
     samtools --version-only
     """
   }
   workflow {
     SAMTOOLS()
   }

   Substitute <container_uri> for the container URI that you received from Seqera Containers in the previous section. e.g.

   • community.wave.seqera.io/library/samtools:1.20--b5dfbd93de237464 for linux/amd64.
   • community.wave.seqera.io/library/samtools:1.20--497854c5df637867 for linux/arm64.

Run the Nextflow pipeline

To confirm that the samtools command is available from your pipeline, run the following command:

nextflow run main.nf

The output from a successful execution is displayed in the following example:

 N E X T F L O W   ~  version 24.04.4

Launching `samtools.nf` [furious_carlsson] DSL2 - revision: 04817f962f

executor >  local (1)
[2f/d2ccc7] process > SAMTOOLS [100%] 1 of 1 ✔
1.20+htslib-1.20

Nextflow

You can provision containers with Wave directly from your Nextflow pipelines.

Prerequisites

• You have an account with a container registry, such as DockerHub, and an access token that provides write access to your container repository.
• You have a Seqera Cloud or Platform account, to store your container registry credentials for Wave to use.
• You have either Docker Desktop or Podman installed locally.
• You have Nextflow 23.10.x or newer installed locally.

In this guide, you'll build a container from a Nextflow module and freeze that package in your private container repository.

Create your Seqera access token

1. Log in to Seqera.

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. In a terminal window, assign your access token to the TOWER_ACCESS_TOKEN environment variable:

   export TOWER_ACCESS_TOKEN=<token_token>

Add your container registry credentials to Seqera

When freezing a container to the build repository that you specify, Wave uses Seqera to obtain your registry access credentials. If you use Docker as your container registry, complete the following steps:

To create your access token in Docker Hub:

1. Log in to Docker Hub.
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 menu, then select Generate.
5. Copy and save the generated access token (this is only displayed once).

To add your 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.

Seqera supports other container registries, such as GitHub and Quay.io.

Create a Nextflow pipeline that uses Wave

Nextflow can use Wave to seamlessly build a container directly from a Dockerfile in your pipeline.

1. In a terminal window, create a new directory for the Nextflow pipeline.

2. Create a nextflow.config file with the following contents:

   docker {
     enabled = true
   }
   
   wave {
     build.repository = '<repo_uri>'
     wave.freeze = true
   }
   
   tower {
     accessToken = "$TOWER_ACCESS_TOKEN"
   }

   The <repo_uri> must be substituted with your private container repository.

3. Create a wave.nf file with the following contents:

   include { HELLO } from './modules/gamma'
   
   workflow {
     HELLO()
   }

4. Create a directory for the module:

   mkdir -p modules/gamma

5. Create the modules/gamma/main.nf file for the module:

   process HELLO {
     debug true
     
     """
     cowsay Hello!
     """
   }

6. Create the modules/gamma/Dockerfile file for the module:

   FROM alpine
   
   RUN apk update && apk add bash cowsay \
     --update-cache \
     --repository https://alpine.global.ssl.fastly.net/alpine/edge/community \
     --repository https://alpine.global.ssl.fastly.net/alpine/edge/main \
     --repository https://dl-3.alpinelinux.org/alpine/edge/testing
   
   RUN echo hello

Run the Nextflow pipeline

To run the pipeline, and initiate the Wave container build, enter the following command:

nextflow run wave.nf -with-wave

The output from a successful execution is displayed in the following example:

Launching `wave.nf` [naughty_wiles] DSL2 - revision: 3756d705d9

executor >  local (1)
[c1/6d7d9d] HELLO | 1 of 1 ✔
 ________
< Hello! >
 --------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Wave CLI

With the Wave CLI, you can provision containers for later use in your Nextflow pipelines.

Prerequisites

For this guide, you must satisfy the following prerequisites:

• You have an account with a container registry, such as DockerHub, and an access token that provides write access to your container repository.
• You have a Seqera Cloud or Platform account, to store your container registry credentials for Wave to use.
• You have either Docker Desktop or Podman installed locally.
• You have Nextflow 23.10.x or newer installed locally.
• You have the Wave CLI installed locally.

In this guide, you'll build a container from a Conda package and freeze that package in your private container repository. By freezing the container, you ensure that you can always use it in your Nextflow pipelines.

Create your Seqera access token

1. Log in to Seqera.

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. In a terminal window, assign your access token to the TOWER_ACCESS_TOKEN environment variable:

   export TOWER_ACCESS_TOKEN=<token_token>

Add your container registry credentials to Seqera

When freezing a container to the build repository that you specify, Wave uses Seqera to obtain your registry access credentials. If you use Docker as your container registry, completing the following steps:

To create your access token in Docker Hub:

1. Log in to Docker Hub.
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 menu, then select Generate.
5. Copy and save the generated access token (this is only displayed once).

To add your 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.

Seqera supports other container registries, such as GitHub and Quay.io.

Create and freeze a container

Wave lets you build a container from any conda package or set of conda packages that you specify. In this section, you'll use Wave to build a container that includes the faker conda package.

In the same terminal window from the previous section, run the Wave CLI to build and freeze a container with the faker conda package to the repository that you specify. Specify the URI for the repository for which you added an access token to Seqera, so that Wave can push the built container.

wave --conda-package 'faker' --freeze --build-repo <repo_uri> --await

Example output:

docker.io/example-user/repo:faker--2aa7a4d826a76301

After the container build completes, Seqera emails you a build status report, including the build logs for the container.

Create a Nextflow pipeline that uses the container

Nextflow can use the container that Wave froze to the build repository that you provided in the previous section. The Wave CLI outputs the URI for the container image and the image tag. Use these values in the container directive.

1. In a terminal window, create a new directory for the Nextflow pipeline.

2. Create a nextflow.config file with the following contents:

   docker {
     enabled = true
   }
   
   tower {
     accessToken = "$TOWER_ACCESS_TOKEN"
   }

3. Create a main.nf file with the following contents:

   process FAKER {
     container 'docker.io/example-user/repo:faker--2aa7a4d826a76301'
     debug true
   
     """
     faker address
     """
   }
   
   workflow {
     FAKER()
   }

Run the Nextflow pipeline

To confirm that the faker command is available from your pipeline, run the following command:

nextflow run main.nf

The output from a successful execution is displayed in the following example:

Launching `./main.nf` [happy_leavitt] DSL2 - revision: 03b4e42ba3

executor >  local (1)
[1d/120069] FAKER | 1 of 1 ✔
1287 Eric Grove
Reneechester, AK 75644

Next steps

• Explore additional Wave CLI use cases.
• Review the available Nextflow configuration options for Wave.