Neurodocker

Neurodocker is a command-line program that generates custom Dockerfiles and Singularity recipes for neuroimaging and minifies existing containers.

• Examples:
  • Examples gallery
  • Canonical examples
    • Docker
    • Singularity
  • Minimize existing Docker image
  • Example of minimizing Docker image for FreeSurfer recon-all
• Known issues

Installation

Use the Neurodocker Docker image (recommended):

docker run --rm repronim/neurodocker:0.7.0 --help

The Docker images were recently moved to repronim/neurodocker from kaczmarj/neurodocker.

Note: Do not use the -t/--tty flag with docker run or non-printable characters will be a part of the output (see moby/moby#8513 (comment)).

This project can also be installed with pip:

pip install neurodocker
neurodocker --help

If the pip install command above gives a permissions error, install as a non-root user:

pip install --user neurodocker

Note: it is not yet possible to minimize Docker containers using the Neurodocker Docker image.

Supported software

* required argument. ** FSL is non-free. If you are considering commercial use of FSL, please consult the relevant license.

Generate Dockerfile

usage: neurodocker generate docker [-h] [-b BASE] [-p {apt,yum}]
                                   [--add-to-entrypoint ADD_TO_ENTRYPOINT]
                                   [--copy COPY [COPY ...]]
                                   [--install INSTALL [INSTALL ...]]
                                   [--entrypoint ENTRYPOINT]
                                   [-e ENV [ENV ...]] [-r RUN]
                                   [--run-bash RUN_BASH] [-u USER]
                                   [-w WORKDIR] [-f FILE] [-o OUTPUT]
                                   [--no-print] [--afni  [...]]
                                   [--ants  [...]] [--convert3d  [...]]
                                   [--dcm2niix  [...]] [--freesurfer  [...]]
                                   [--fsl  [...]] [--matlabmcr  [...]]
                                   [--minc  [...]] [--miniconda  [...]]
                                   [--mrtrix3 [[...]]] [--neurodebian  [...]]
                                   [--petpvc  [...]] [--spm12  [...]]
                                   [--vnc  [...]] [--add ADD [ADD ...]]
                                   [--arg ARG [ARG ...]] [--cmd CMD [CMD ...]]
                                   [--expose EXPOSE [EXPOSE ...]]
                                   [--label LABEL [LABEL ...]]
                                   [--volume VOLUME [VOLUME ...]]

optional arguments:
  -h, --help            show this help message and exit
  -b BASE, --base BASE  Base Docker image. E.g., debian:stretch
  -p {apt,yum}, --pkg-manager {apt,yum}
                        Linux package manager.
  --add-to-entrypoint ADD_TO_ENTRYPOINT
                        Add a command to the file /neurodocker/startup.sh,
                        which is the container's default entrypoint.
  --copy COPY [COPY ...]
                        Copy files into container. Use format <src>... <dest>
  --install INSTALL [INSTALL ...]
                        Install system packages with apt-get or yum, depending
                        on the package manager specified.
  --entrypoint ENTRYPOINT
                        Set the container's entrypoint (Docker) / append to
                        runscript (Singularity)
  -e ENV [ENV ...], --env ENV [ENV ...]
                        Set environment variable(s). Use the format KEY=VALUE
  -r RUN, --run RUN     Run a command when building container
  --run-bash RUN_BASH   Run a command in bash
  -u USER, --user USER  Switch current user (creates user if necessary)
  -w WORKDIR, --workdir WORKDIR
                        Set working directory
  -f FILE, --file FILE  Generate file from JSON. Overrides other `generate`
                        arguments
  -o OUTPUT, --output OUTPUT
                        If specified, save Dockerfile to file with this name.
  --no-print            Do not print the generated file
  --add ADD [ADD ...]   Dockerfile ADD instruction. Use format <src>... <dest>
  --arg ARG [ARG ...]   Dockerfile ARG instruction. Use format
                        KEY[=DEFAULT_VALUE] ...
  --cmd CMD [CMD ...]   Dockerfile CMD instruction.
  --expose EXPOSE [EXPOSE ...]
                        Dockerfile EXPOSE instruction.
  --label LABEL [LABEL ...]
                        Dockerfile LABEL instruction.
  --volume VOLUME [VOLUME ...]
                        Dockerfile VOLUME instruction.

Generate Singularity recipe

usage: neurodocker generate singularity [-h] [-b BASE] [-p {yum,apt}]
                                        [--add-to-entrypoint ADD_TO_ENTRYPOINT]
                                        [--copy COPY [COPY ...]]
                                        [--install INSTALL [INSTALL ...]]
                                        [--entrypoint ENTRYPOINT]
                                        [-e ENV [ENV ...]] [-r RUN]
                                        [--run-bash RUN_BASH] [-u USER]
                                        [-w WORKDIR] [-f FILE] [-o OUTPUT]
                                        [--no-print] [--afni  [...]]
                                        [--ants  [...]] [--convert3d  [...]]
                                        [--dcm2niix  [...]]
                                        [--freesurfer  [...]] [--fsl  [...]]
                                        [--matlabmcr  [...]] [--minc  [...]]
                                        [--miniconda  [...]]
                                        [--mrtrix3 [[...]]]
                                        [--neurodebian  [...]]
                                        [--petpvc  [...]] [--spm12  [...]]
                                        [--vnc  [...]]

optional arguments:
  -h, --help            show this help message and exit
  -b BASE, --base BASE  Base Docker image. E.g., debian:stretch
  -p {apt,yum}, --pkg-manager {apt,yum}
                        Linux package manager.
  --add-to-entrypoint ADD_TO_ENTRYPOINT
                        Add a command to the file /neurodocker/startup.sh,
                        which is the container's default entrypoint.
  --copy COPY [COPY ...]
                        Copy files into container. Use format <src>... <dest>
  --install INSTALL [INSTALL ...]
                        Install system packages with apt-get or yum, depending
                        on the package manager specified.
  --entrypoint ENTRYPOINT
                        Set the container's entrypoint (Docker) / append to
                        runscript (Singularity)
  -e ENV [ENV ...], --env ENV [ENV ...]
                        Set environment variable(s). Use the format KEY=VALUE
  -r RUN, --run RUN     Run a command when building container
  --run-bash RUN_BASH   Run a command in bash
  -u USER, --user USER  Switch current user (creates user if necessary)
  -w WORKDIR, --workdir WORKDIR
                        Set working directory
  -f FILE, --file FILE  Generate file from JSON. Overrides other `generate`
                        arguments
  -o OUTPUT, --output OUTPUT
                        If specified, save Dockerfile to file with this name.
  --no-print            Do not print the generated file

Examples

Please see the examples directory.

Canonical examples

The canonical examples install ANTs version 2.3.1 on Debian 9 (Stretch).

Note: Do not use the -t/--tty flag with docker run or non-printable characters will be a part of the output (see moby/moby#8513 (comment)).

Docker

docker run --rm repronim/neurodocker:0.7.0 generate docker \
    --base debian:stretch --pkg-manager apt --ants version=2.3.1

# Build image by piping Dockerfile to `docker build`
docker run --rm repronim/neurodocker:0.7.0 generate docker \
    --base debian:stretch --pkg-manager apt --ants version=2.3.1 | docker build -

Singularity

Install ANTs on Debian 9 (Stretch).

docker run --rm repronim/neurodocker:0.7.0 generate singularity \
    --base debian:stretch --pkg-manager apt --ants version=2.3.1

Minimize existing Docker image

Neurodocker must be pip installed for container minimization. The docker Python package must also be installed.

In the following example, a Docker image is built with ANTs version 2.3.1 and a functional scan. The image is minified for running antsMotionCorr. The original ANTs Docker image is 1.97 GB, and the "minified" image is 293 MB. The only directory that is pruned is /opt, which includes the ANTs installation. This means that important directories like /usr and /bin are untouched, and the container can still be used interactively.

# Create a Docker image with ANTs, and download a functional scan.
download_cmd="curl -sSL -o /home/func.nii.gz http://psydata.ovgu.de/studyforrest/phase2/sub-01/ses-movie/func/sub-01_ses-movie_task-movie_run-1_bold.nii.gz"
neurodocker generate docker -b centos:7 -p yum --ants version=2.3.1 --run="$download_cmd" | docker build -t ants:2.3.1 -

# Run the container in the background. The option --security-opt=seccomp:unconfined is
# important. Without this, the trace will not be able to run in the container.
docker run --rm -itd --name ants-container --security-opt=seccomp:unconfined ants:2.3.1

# Find all of the files under `/opt` that are not used by the command(s), and queue
# those files for deletion.
cmd="antsMotionCorr -d 3 -a /home/func.nii.gz -o /home/func_avg.nii.gz"
neurodocker-minify --container ants-container --dirs-to-prune /opt --commands "$cmd"
# Read through the list of files that will be deleted, and respond with the keyboard.
# Then, create a new Docker image using the pruned container.
docker export ants-container | docker import - ants:2.3.1-min-motioncorr

# View a summary of the Docker images.
docker images
# REPOSITORY          TAG                    IMAGE ID            CREATED              SIZE
# ants                2.3.1-min-motioncorr   6436f58e965c        About a minute ago   293MB
# ants                2.3.1                  b56f5e9d1805        17 minutes ago       1.97GB
# centos              7                      5e35e350aded        4 months ago         203MB

Known issues

• Using the -t/--tty option in docker run produces non-printable characters in the generated Dockerfile or Singularity recipe (see moby/moby#8513 (comment)).
  • Solution: do not use the -t/--tty flag, unless using the container interactively.
• Attempting to rebuild into an existing Singularity image may raise an error.
  • Solution: remove the existing image or build a new image file.
• The default apt --install option --no-install-recommends (that aims at minimizing container sizes) can cause unexpected behavior.
  • Solution: use --install apt_opts="--quiet"
  • Please see the examples for more information.
• FreeSurfer cannot find my license file.
  • Solution: get a free license from FreeSurfer's website, and copy it into the container. To build the Docker image, please use the form docker build . instead of docker build - < Dockerfile. The latter form will not copy files into the image.
  • Please see the examples for more information.

Developer installation

Clone the repository and install in editable mode.

git clone https://github.com/ReproNim/neurodocker
cd neurodocker
python -m pip install --no-cache-dir --editable .[all]

Before committing changes, initialize pre-commit with pre-commit install. This will format code with each commit to keep the style consistent. Neurodocker uses black for formatting.