Docker is an open-source project that automates the deployment of applications inside software containers. Those containers wrap up a piece of software in a complete filesystem that contains everything it needs to run: code, system tools, software libraries, such as Python, FSL, AFNI, SPM, FreeSurfer, ANTs, etc. This guarantees that it will always run the same, regardless of the environment it is running in.
Important: You don't need Docker to run Nipype on your system. For Mac and Linux users, it probably is much simpler to install Nipype directly on your system. For more information on how to do this see the Nipype website. But for Windows user, or users that don't want to setup all the dependencies themselves, Docker is the way to go.
If you want to run this Nipype Tutorial with the example dataset locally on your own system, you need to use the docker image, provided under satra/nih-workshop-2017. This docker image sets up a Linux environment on your system, with functioning Python, Nipype, FSL, AFNI, ANTs and SPM12 software package, some example data and all the tutorial notebooks to learn Nipype. Alternatively, you can also create your own docker image with Neurodocker.
Before you can do anything, you first need to install Docker on your system. The installation process differes per system. Luckily, the docker homepage has nice instructions for...
Once Docker is installed, open up the docker terminal and test it works with the command:
docker run hello-world
Note: Linux users might need to use
sudo to run
docker commands or follow post-installation steps.
After installing docker on your system and making sure that the
hello-world example was running, we are good to go to start the Nipype Tutorial image. The exact implementation is a bit different for Windows user, but the general command looks as follows:
docker run -it --rm -v /path/to/nipype_tutorial/:/opt/tutorial -v /path/to/data/:/data -v /path/to/output/:/output -p 8888:8888 satra/nih-workshop-2017:latest jupyter notebook
But what do those flags mean?
-tiflag tells docker that it should open an interactive container instance.
--rmflag tells docker that the container should automatically be removed after we close docker.
-pflag specifies which port we want to make available for docker.
-vflag tells docker which folders should be mount to make them accesible inside the container. Here:
/path/to/nipype_tutorialis your local directory where you downloaded Nipype Tutorial repository.
/path/to/data/is a directory where you have dataset
/path/to/outputcan be an empty directory that will be used for output. The second part of the
/output) specifies under which path the mounted folders can be found inside the container. Important: To use the
outputfolder, you first need to create them on your system!
satra/nih-workshop-2017:latesttells docker which image you want to run.
jupyter notebooktells that you want to run directly the jupyter notebook command within the container. Alternatively, you can also use
Note that when you run this docker image without any more specification, than it will prompt you a URL link in your terminal that you will need to copy paste into your browser to get to the notebooks.
Running a docker image on a Linux or Mac OS is very simple. Make sure that the folders
output exist. Then just open a new terminal and use the command from above. Once the docker image is downloaded, open the shown URL link in your browser and you are good to go. The URL will look something like:
Running a docker image on Windows is a bit trickier than on Ubuntu. Assuming you've installed the DockerToolbox, open the Docker Quickstart Terminal. Once the docker terminal is ready (when you see the whale), execute the following steps (see also figure):
We need to check the IP adress of your docker machine. For this, use the command:
In my case, this returned
If you haven't already created a new folder to store your container output into, do so. You can create the folder either in the explorer as usual or do it with the command
mkdir -p in the docker console. For example like this:
mkdir -p /c/Users/username/output
username with the name of the current user on your system. Pay attention that the folder paths in the docker terminal are not backslash (
\) as we usually have in Windows. Also,
C:\ needs to be specified as
Now, we can open run the container with the command from above:
docker run -it --rm -v /c/Users/username/path/to/nipype_tutorial/:/opt/tutorial -v /c/Users/username/path/to/data/:/data -v /c/Users/username/path/to/output/:/output -p 8888:8888 satra/nih-workshop-2017:latest
Once the docker image is downloaded, it will show you an URL that looks something like this:
This URL will not work on a Windows system. To make it work, you need to replace the string
localhost with the IP address of your docker machine, that we acquired under step 1. Afterwards, your URL should look something like this:
Copy this link into your webbrowser and you're good to go!
You don't have to open a jupyter notebook when you run
satra/nih-workshop-2017. You can also access the docker container directly with
ipython by adding it to the end of your command, i.e.:
docker run -it --rm -v /path/to/nipype_tutorial/:/opt/tutorial -v /path/to/data/:/data -v /path/to/output/:/output -p 8888:8888 satra/nih-workshop-2017:latest bash
This also works with other software commands, such as
To stop a running docker container, either close the docker terminal or select the terminal and uste the
Ctrl-C shortcut multiple times.
To see a list of all installed docker images use:
To delete a specific docker image, first use the
docker images command to list all installed containers and than use the
IMAGE ID and the
rmi instruction to delete the container:
docker rmi -f 7d9495d03763
If you don't want to depend on a internet connection, you can also export an already downloaded docker image and than later on import it on another PC. To do so, use the following two commands:
# Export docker image satra/nih-workshop-2017 docker save -o nipype_tutorial.tar satra/nih-workshop-2017 # Import docker image on another PC docker load --input nipype_tutorial.tar
It might be possible that you run into administrator privileges isssues because you ran your docker command with
sudo. This means that òther users don't have access rights to
nipype_tutorial.tar. To avoid this, just change the rights of
nipype_tutorial.tar with the command:
sudo chmod 777 nipype_tutorial.tar