Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

Create custom containers for neuroimaging

Project description

Neurodocker

build status docker pulls python versions

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

Installation

Use the Neurodocker Docker image (recommended):

$ docker run --rm kaczmarj/neurodocker:0.5.0 --help

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

software argument description
AFNI version* latest
method binaries (default), source. Install pre-compiled binaries or build form source.
install_path Installation path. Default /opt/afni-{version}.
install_r If true, install R.
install_r_pkgs If true, install R and AFNI's R packages.
install_python2 If true, install Python 2.
install_python3 If true, install Python 3.
ANTs version* 2.3.1, 2.3.0, 2.2.0, 2.1.0, 2.0.3, or 2.0.0. If method=source, version can be a git commit hash or branch.
method binaries (default), source.
install_path Installation path. Default /opt/ants-{version}.
cmake_opts If method=source, options for cmake.
make_opts If method=source, options for make.
Convert3D version* 1.0.0 or nightly.
method binaries (default)
install_path Installation path. Default /opt/convert3d-{version}.
dcm2niix version* latest, git commit hash or branch.
method source (default)
install_path Installation path. Default /opt/dcm2niix-{version}.
cmake_opts If method=source, options for cmake.
make_opts If method=source, options for make.
FreeSurfer version* 6.0.0-min
method binaries (default)
install_path Installation path. Default /opt/freesurfer-{version}.
exclude_paths Sequence of space-separated path(s) to exclude when inflating the tarball.
license_path Relative path to license file. If provided, this file will be copied into the Docker image. Must be within the build context.
FSL** version* 5.0.11, 5.0.10, 5.0.9, 5.0.8
method binaries (default)
install_path Installation path. Default /opt/fsl-{version}.
exclude_paths Sequence of space-separated path(s) to exclude when inflating the tarball.
Matlab Compiler Runtime version* 2018a, 2012-17[a-b], 2010a
method binaries (default)
install_path Installation path. Default /opt/matlabmcr-{version}.
MINC version* 1.9.15
method binaries (default)
install_path Installation path. Default /opt/minc-{version}.
Miniconda version latest (default), all other hosted versions.
install_path Installation path. Default /opt/miniconda-{version}.
create_env Name of conda environment to create.
use_env Name of previously installed environment.
conda_install Packages to install with conda. E.g., conda_install="python=3.6 numpy traits"
pip_install Packages to install with pip.
activate If true (default), activate this environment in container entrypoint.
MRtrix3 version* 3.0
method binaries (default)
install_path Installation path. Default /opt/mrtrix3-{version}.
NeuroDebian os_codename* Codename of the operating system (e.g., stretch, zesty).
server* Server to download NeuroDebian packages from. Choose the one closest to you. See neurodocker generate docker --help for the full list of servers.
full If true (default), use non-free sources. If false, use libre sources.
PETPVC version* 1.2.2, 1.2.1, 1.2.0-b, 1.2.0-a, 1.1.0, 1.0.0
method binaries (default)
install_path Installation path. Default /opt/petpvc-{version}.
SPM12 version* r7219, r6914, r6685, r6472, r6225
install_path Installation path. Default /opt/spm12-{version}.
Note: Matlab Compiler Runtime is installed when SPM12 is installed.
VNC passwd* Choose a password for this VNC server.
start_at_runtime If true, start the VNC server at container runtime. False by default.
geometry The geometry of the VNC session (e.g., 1920x1080).

* 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 kaczmarj/neurodocker:0.5.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 kaczmarj/neurodocker:0.5.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 kaczmarj/neurodocker:0.5.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.

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.85 GB, and the "minified" image is 365 MB.

# 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

# Output a ReproZip pack file in the current directory with the files
# necessary to run antsMotionCorr.
$ cmd="antsMotionCorr -d 3 -a /home/func.nii.gz -o /home/func_avg.nii.gz"
$ neurodocker reprozip trace ants-container "$cmd"
# Create a Docker container with the contents of ReproZip's trace.
$ reprounzip docker setup neurodocker-reprozip.rpz test

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 a strange behaviour for cython inside the container
    • Solution: use "--install apt_opts=--quiet "
    • more information: examples

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
neurodocker-0.5.0-py3-none-any.whl (59.1 kB) Copy SHA256 hash SHA256 Wheel py3

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page