Quickstart

Generate a container

Use the command neurodocker generate to generate containers. In the examples below, we generate containers with Nipype, Jupyter Notebook, and ANTs.

Please see the Examples page for more.

Docker

Run the following code snippet to generate a Dockerfile. This is a file that defines how to build a Docker image.

(This requires having Docker installed)

neurodocker generate docker --pkg-manager apt \
    --base-image neurodebian:buster \
    --ants version=2.3.4 \
    --miniconda version=latest conda_install="nipype notebook" \
    --user nonroot

You should see a block of text appear in the console. This is the Dockerfile generated by Neurodocker. Instructions in the Dockerfile are ordered in the same way as the arguments in the command-line. To build a Docker image with this, save the output to a file in an empty directory, and build with docker build:

mkdir docker-example
cd docker-example
neurodocker generate docker --pkg-manager apt \
    --base-image neurodebian:buster \
    --ants version=2.3.4 \
    --miniconda version=latest conda_install="nipype notebook" \
    --user nonroot > Dockerfile
docker build --tag nipype-ants .

Then, you can start a Jupyter Notebook with the following command. This will mount the current working directory to work within the container, so any files you create in this directory are saved. If we had not mounted this directory, all of the files created in /work would be gone after the container was stopped.

docker run --rm -it --workdir /work --volume $PWD:/work --publish 8888:8888 \
    nipype-ants jupyter-notebook --ip 0.0.0.0 --port 8888

Feel free to create a new notebook and import nipype.

Singularity

The only difference between this command and the one above is neurodocker generate singularity versus neurodocker generate docker. This will be the case when generating the majority of containers. The code block below generates a Singularity definition file. This file can be used to create a Singularity container.

(This requires having Singularity installed.

neurodocker generate singularity --pkg-manager apt \
    --base-image neurodebian:buster \
    --ants version=2.3.4 \
    --miniconda version=latest conda_install="nipype notebook" \
    --user nonroot

You should see a block of text appear in the console. This is the Singularity definition. To build the Singularity image, create a new directory, save this output to a file, and use sudo singularity build. Note that this requires superuser privileges. You will not be able to run this on a shared computing environment, like a high performance cluster.

mkdir singularity-example
cd singularity-example
neurodocker generate singularity --pkg-manager apt \
    --base-image neurodebian:buster \
    --ants version=2.3.4 \
    --miniconda version=latest conda_install="nipype notebook" \
    --user nonroot > Singularity
sudo singularity build nipype-ants.sif Singularity

This will create a new file nipype-ants.sif in this directory. This is the Singularity container. You can move this file around like any other file – even share it with all of your friends.

To run Jupyter Notebook, use the following:

singularity run --bind $PWD:/work --pwd /work nipype-ants.sif jupyter-notebook

Feel free to create a new notebook and import nipype.

Minify a Docker container

Neurodocker enables you to minify Docker containers for a set of commands. This will remove files not used by these commands and will dramatically reduce the size of the Docker image.

See neurodocker minify --help for more information.

Note

Neurodocker must be installed with pip to minify containers.

pip install neurodocker[minify]

In the example below, we minify one of the official Python Docker images for certain commands. This will remove all of the files in /usr/local/ that are not used by these commands.

ReproZip is used to determine the files used by the commands.

docker run --rm -itd --name to-minify python:3.9-slim bash
neurodocker minify \
  --container to-minify \
  --dir /usr/local \
  "python -c 'a = 1 + 1; print(a)'" \
  "python -c 'import os'"

You will be given a list of all of the files that will be deleted. Review this list of files before proceeding.

docker export to-minify | docker import - minified-python

Now if you run docker images, the image minified-python will be listed.

Warning

Environment variables are lost when saving the minified image as a new image. If certain environment variables are required in the minified image, users should create a new Dockerfile that uses the minified image as a base image and then sets environment variables.

The commands that were run during minification will (read: should) succeed:

docker run --rm minified-python python -c "a = 1 + 1; print(a)"
docker run --rm minified-python python -c "import os"

But commands not run during minification are not guaranteed to succeed. The following commands, for example, result in errors.

docker run --rm minified-python python -c 'import math'
docker run --rm minified-python python -c 'import pathlib'
docker run --rm minified-python pip --help