How to use Docker

There are two approaches for using YAMP with Docker: either by pulling or building the Docker image (which requires an extra independent step that should be performed once on each machine you will use to run YAMP, see next Section), or by asking Nextflow to fetch the image for you.

Please note that this tutorial refers to the Example we used in the How to run YAMP tutorial and that you need to have Docker installed.

Pull or build the image

To use the software made available through the Docker container, you could either pull the pre-built image from DockerHub, using the following command (suggested):

docker pull alesssia/yampdocker

or build a local image using the file Dokerfile in the yampdocker folder. To build a local image, first access the yampdocker folder and then run the following command (be careful to add the dot!):

docker build -t yampdocker .

Done, now it is time to run YAMP with Docker!

Run YAMP with Docker

If you pulled or built the Docker image, you can use it by adding the -with-docker option followed by the image name (alesssia/yampdocker, if pulled, or yampdocker, if built), that is, with the following command, which assumes a pulled image:

nextflow run YAMP.nf --reads1 R1 --reads2 R2 --prefix mysample --outdir outputdir --mode MODE -with-docker alesssia/yampdocker

where R1 and R2 represent the path to the raw data (two compressed FASTQ file), mysample is a prefix that will be used to label all the resulting files, outputdir is the directory where the results will be stored, and MODE is any of the following: < QC, characterisation, complete >.

So, to run YAMP with Docker on the example presented in the How to run YAMP) tutorial, one should run (again assuming a pulled image):

nextflow run YAMP.nf --reads1 ./data/ERR011089_1.fastq.gz --reads2 ./data/ERR011089_1.fastq.gz --prefix Meta_HIT_ERR011089 --outdir ./data --mode complete -with-docker alesssia/yampdocker 

If you decided to let Nextflow fetch the image for you, it is even simpler: don't do anything and just add the location of the Docker container (docker://alesssia/yampdocker) as parameters for -with-docker, that is, run the following command:

nextflow run YAMP.nf --reads1 R1 --reads2 R2 --prefix mysample --outdir outputdir --mode MODE -with-docker docker://alesssia/yampdocker

Alternatively, you can set the following parameters into the nextflow.config file:

docker.enabled = true
process.container = 'alesssia/yampdocker:latest'

Simple, isn't it?

A word of caution

Nextflow is not included in the Docker image and should be installed independently as explained here.

In fact, Nextflow orchestrates, in a transparent fashion, the flow of the pipeline by wrapping and executing each step using the docker run command. Thus, Nextflow lies outside the container, that is responsible for instantiating.

You can find more information about Docker containers and Nextflow here.

Docker image and Singularity

Since Singularity v2.3, it is possible to create a Singularity container from a Docker image. However, with Nextflow it is even simpler, because you don't need to build a Singularity container at all, as explained in the How to use Singularity tutorial.

Troubleshooting

If you get this error:

Command error:
WARNING: Your kernel does not support swap limit capabilities or the cgroup is not mounted. Memory limited without swap.
touch: cannot touch ‘.command.trace’: Permission denied

please add docker.runOptions = '-u $(id -u):$(id -g)' in the nextflow.config file (thanks to wangdatou200 for pointing this out here.