Wave CLI

You can provision containers for later use in your Nextflow pipelines with the Wave CLI.

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 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 you close 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. Select Access permissions > Read-only, 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. Select Add. The new credential will be 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