ingo-m / neurodocker

Generate custom Docker images and minimize existing containers

Neurodocker

Neurodocker is a Python project that generates custom Dockerfiles for neuroimaging and minifies existing Docker images (using ReproZip). The package can be used from the command-line or within a Python script. The command-line interface generates Dockerfiles and minifies Docker images, but interaction with the Docker Engine is left to the various docker commands. Within a Python script, however, Neurodocker can generate Dockerfiles, build Docker images, run commands within resulting containers (using the docker Python package), and minify Docker images. The project is used for regression testing of Nipype interfaces.

Examples:

• Generate Dockerfile
• Generate Dockerfile (full)
• Minimize existing Docker image
• Example of minimizing Docker image for FreeSurfer recon-all

Note to users

This software is still in the early stages of development. If you come across an issue or a way to improve Neurodocker, please submit an issue or a pull request.

Installation

Use the Neurodocker Docker image:

docker run --rm kaczmarj/neurodocker:v0.3.1 --help

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

Supported Software

Valid options for each software package are the keyword arguments for the class that installs that package. These classes live in neurodocker.interfaces. The default installation behavior for every software package (except Miniconda) is to install by downloading and un-compressing the binaries.

software	argument	description
AFNI	version*	Either 17.2.02 or latest.
	install_r	If true, install R and AFNI R packages. False by default.
	install_python2	If true, install Python 2.
	install_python3	If true, install Python 3.
ANTs	version*	2.2.0, 2.1.0, 2.0.3, or 2.0.0
	use_binaries	If true (default), use pre-compiled binaries. If false, build from source.
	git_hash	Git hash to checkout to before building from source (only used if use_binaries is false).
Convert3D	version*	"1.0.0" or "nightly".
dcm2niix	version*	"latest", "master", git commit hash, or git tag.
FreeSurfer	version*	Any version for which binaries are provided.
	license_path	Relative path to license file. If provided, this file will be copied into the Docker image. Must be within the build context.
	min	If true, install a version of FreeSurfer minimized for recon-all. See freesurfer/freesurfer#70. False by default.
FSL**	version*	Any version for which binaries are provided.
	eddy_5011	If true, use pre-release version of FSL eddy v5.0.11
	eddy_5011_cuda	6.5, 7.0, 7.5, 8.0; only valid if using eddy pre-release
	use_binaries	If true (default), use pre-compiled binaries. Building from source is not available now but might be added in the future.
	use_installer	If true, use FSL's Python installer. Only valid on CentOS images.
MINC	version*	1.9.15
Miniconda	env_name*	Name of this conda environment.
	yaml_file	Environment specification file. Can be path on host or URL.
	conda_install	Packages to install with conda. e.g., conda_install="python=3.6 numpy traits"
	pip_install	Packages to install with pip.
	conda_opts	Command-line options to pass to conda create. e.g., conda_opts="-c vida-nyu"
	pip_opts	Command-line options to pass to pip install.
	activate	If true (default), activate this environment in container entrypoint.
	miniconda_version	Version of Miniconda. Latest by default.
MRtrix3	use_binaries	If true (default), use pre-compiled binaries. If false, build from source.
	git_hash	Git hash to checkout to before building from source (only used if use_binaries is false).
NeuroDebian	os_codename*	Codename of the operating system (e.g., stretch, zesty).
	download_server*	Server to download NeuroDebian packages from. Choose the one closest to you. See neurodocker generate --help for the full list of servers.
	pkgs	Packages to download from NeuroDebian.
	full	If true (default), use non-free sources. If false, use libre sources.
PETPVC	version*	1.2.0-b, 1.2.0-a, 1.1.0, 1.0.0
SPM	version*	12 (earlier versions will be supported in the future).
	matlab_version*	R2017a (other MCR versions will be supported once earlier SPM versions are supported).

* required argument.

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

Examples

Please see the examples directory.

Canonical example

Generate a Dockerfile which will install ANTs on Ubuntu 17.04. The result can be piped to docker build to build the Docker image.

docker run --rm kaczmarj/neurodocker:v0.3.2 generate -b ubuntu:17.04 -p apt --ants version=2.2.0

docker run --rm kaczmarj/neurodocker:v0.3.2 generate -b ubuntu:17.04 -p apt --ants version=2.2.0 | docker build -

Minimize existing Docker image

The Neurodocker Python package will have to be installed for container minimization:

pip install --no-cache-dir https://github.com/kaczmarj/neurodocker/tarball/master

In the following example, a Docker image is built with ANTs version 2.2.0 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="RUN 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 -b centos:7 -p yum --ants version=2.2.0 --instruction="$download_cmd" | docker build -t ants:2.2.0 -

# Run the container.
docker run --rm -it --name ants-reprozip-container --security-opt=seccomp:unconfined ants:2.2.0

# (in a new terminal window)
# Output a ReproZip pack file in ~/neurodocker-reprozip-output with the files
# necessary to run antsMotionCorr.
# See https://github.com/stnava/ANTs/blob/master/Scripts/antsMotionCorrExample
cmd="antsMotionCorr -d 3 -a /home/func.nii.gz -o /home/func_avg.nii.gz"
neurodocker reprozip-trace ants-reprozip-container "$cmd"

reprounzip docker setup neurodocker-reprozip.rpz test