Running fMRIPrep via Docker containers

For every new version of fMRIPrep that is released, a corresponding Docker image is generated. The Docker image becomes a container when the execution engine loads the image and adds an extra layer that makes it runnable. In order to run fMRIPrep Docker images, the Docker Engine must be installed (see Docker (recommended for PC/laptop and commercial Cloud)).

If you used fMRIPrep via Docker in the past, you might need to pull down a more recent version of the image:

$ docker pull poldracklab/fmriprep:<latest-version>

You can run fMRIPrep interacting directly with the Docker Engine via the docker run command line, or you can use a lightweight wrapper we created for convenience.

Running fMRIPrep with the fmriprep-docker wrapper

Before starting, make sure you have the wrapper installed. When you run fmriprep-docker, it will generate a Docker command line for you, print it out for reporting purposes, and then execute it without further action needed, e.g.:

$ fmriprep-docker /path/to/data/dir /path/to/output/dir participant
RUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \
    -v /path/to_output/dir:/out poldracklab/fmriprep:1.0.0 \
    /data /out participant
...

fmriprep-docker accepts all of the typical options for fMRIPrep (see Usage Notes), automatically translating directories into Docker mount points.

We have published a step-by-step tutorial illustrating how to run fmriprep-docker. This tutorial also provides valuable troubleshooting insights and advice on what to do after fMRIPrep has run.

Running fMRIPrep directly interacting with the Docker Engine

If you need a finer control over the container execution, or you feel comfortable with the Docker Engine, avoiding the extra software layer of the wrapper might be a good decision.

Accessing filesystems in the host within the container. Containers are confined in a sandbox, so they can’t access the host in any ways unless you explicitly prescribe acceptable accesses to the host. The Docker Engine provides mounting filesystems into the container with the -v argument and the following syntax: -v some/path/in/host:/absolute/path/within/container:ro, where the trailing :ro specifies that the mount is read-only. The mount permissions modifiers can be omitted, which means the mount will have read-write permissions. In general, you’ll want to at least provide two mount-points: one set in read-only mode for the input data and one read/write to store the outputs. Potentially, you’ll want to provide one or two more mount-points: one for the working directory, in case you need to debug some issue or reuse pre-cached results; and a TemplateFlow folder to preempt the download of your favorite templates in every run.

Running containers as a user. By default, Docker will run the container as root. Some share systems my limit this feature and only allow running containers as a user. When the container is run as root, files written out to filesystems mounted from the host will have the user id 1000 by default. In other words, you’ll need to be able to run as root in the host to change permissions or manage these files. Alternatively, running as a user allows preempting these permissions issues. It is possible to run as a user with the -u argument. In general, we will want to use the same user ID as the running user in the host to ensure the ownership of files written during the container execution. Therefore, you will generally run the container with -u $( id -u ).

You may also invoke docker directly:

$ docker run -ti --rm \
    -v path/to/data:/data:ro \
    -v path/to/output:/out \
    poldracklab/fmriprep:<latest-version> \
    /data /out/out \
    participant

For example:

$ docker run -ti --rm \
    -v $HOME/ds005:/data:ro \
    -v $HOME/ds005/derivatives:/out \
    -v $HOME/tmp/ds005-workdir:/work \
    poldracklab/fmriprep:<latest-version> \
    /data /out/fmriprep-<latest-version> \
    participant \
    -w /work

Once the Docker Engine arguments are written, the remainder of the command line follows the Usage Notes. In other words, the first section of the command line is all equivalent to the fmriprep executable in a bare-metal installation:

$ docker run -ti --rm \                      | These lines
    -v $HOME/ds005:/data:ro \                | are equivalent
    -v $HOME/ds005/derivatives:/out \        | to the fmriprep
    -v $HOME/tmp/ds005-workdir:/work \       | executable.
    poldracklab/fmriprep:<latest-version> \  |
    \
    /data /out/fmriprep-<latest-version> \   | These lines
    participant \                            | correspond to
    -w /work                                 | fmriprep arguments.