Docker
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 users, or users that don't want to set up all the dependencies themselves, Docker is the way to go.
Docker Image for the interactive Nipype Tutorial
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 miykael/nipype_tutorial. This docker image sets up a Linux environment on your system, with functioning Python, Nipype, FSL, ANTs and SPM12 software package, some example data, and all the tutorial notebooks to learn Nipype. Alternatively, you can also build your own docker image from Dockerfile or create a different Dockerfile using Neurodocker.
Install Docker
Before you can do anything, you first need to install Docker on your system. The installation process differs per system. Luckily, the docker homepage has nice instructions for...
- Ubuntu or Debian
- Windows 7/8/9/10 or Windows 10Pro
- OS X (from El Capitan 10.11 on) or OS X (before El Capitan 10.11).
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.
Pulling the Docker image
You can download various Docker images, but for this tutorial, we will suggest miykael/nipype_tutorial
:
docker pull miykael/nipype_tutorial:latest
Once it's done you can check available images on your system:
docker images
How to run the Docker image
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 commands look similar.
The suggested Docker image, miykael/nipype_tutorial, already contains all tutorial notebooks and data used in the tutorial, so the simplest way to run container is:
docker run -it --rm -p 8888:8888 miykael/nipype_tutorial jupyter notebook
However, if you want to use your version of notebooks, safe notebook outputs locally or use you local data, you can also mount your local directories, e.g.:
docker run -it --rm -v /path/to/nipype_tutorial/:/home/neuro/nipype_tutorial -v /path/to/data/:/data -v /path/to/output/:/output -p 8888:8888 miykael/nipype_tutorial jupyter notebook
But what do those flags mean?
- The
-it
flag tells docker that it should open an interactive container instance. - The
--rm
flag tells docker that the container should automatically be removed after we close docker. - The
-p
flag specifies which port we want to make available for docker. - The
-v
flag tells docker which folders should be mount to make them accessible inside the container. Here:/path/to/nipype_tutorial
is your local directory where you downloaded Nipype Tutorial repository./path/to/data/
is a directory where you have datasetds000114
, and/path/to/output
can be an empty directory that will be used for output. The second part of the-v
flag (here:/home/neuro/nipype_tutorial
,/data
or/output
) specifies under which path the mounted folders can be found inside the container. Important: To use thetutorial
,data
andoutput
folder, you first need to create them on your system! miykael/nipype_tutorial
tells docker which image you want to run.jupyter notebook
tells that you want to run directly the jupyter notebook command within the container. Alternatively, you can also usejupyter-lab
,bash
oripython
.
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.
Run a docker image on Linux or Mac
Running a docker image on a Linux or Mac OS is very simple. Make sure that the folders tutorial
, data
, and 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:
http://localhost:8888/?token=0312c1ef3b61d7a44ff5346d3d150c23249a548850e13868
Run a docker image on Windows
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 address of your docker machine. For this, use the command:
docker-machine ip
In my case, this returned
192.168.99.100
-
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
Please replace
username
with the name of the current user on your system. Pay attention that the folder paths in the docker terminal are not a backslash (\
) as we usually have in Windows. Also,C:\
needs to be specified as/c/
. -
Now, we can open run the container with the command from above:
docker run -it --rm -v /c/Users/username/path/to/nipype_tutorial/:/home/neuro/nipype_tutorial -v /c/Users/username/path/to/data/:/data -v /c/Users/username/path/to/output/:/output -p 8888:8888 miykael/nipype_tutorial
-
Once the docker image is downloaded, it will show you an URL that looks something like this:
http://localhost:8888/?token=0312c1ef3b61d7a44ff5346d3d150c23249a548850e13868
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. Afterward, your URL should look something like this:http://192.168.99.100:8888/?token=0312c1ef3b61d7a44ff5346d3d150c23249a548850e13868
Copy this link into your webbrowser and you're good to go!
Docker tips and tricks
Access Docker Container with bash
or ipython
You don't have to open a jupyter notebook when you run miykael/nipype_tutorial
. You can also access the docker container directly with bash
or ipython
by adding it to the end of your command, i.e.:
docker run -it --rm -v /path/to/nipype_tutorial/:/home/neuro/nipype_tutorial -v /path/to/data/:/data -v /path/to/output/:/output -p 8888:8888 miykael/nipype_tutorial bash
This also works with other software commands, such as bet
etc.
Stop Docker Container
To stop a running docker container, either close the docker terminal or select the terminal and use the Ctrl-C
shortcut multiple times.
List all installed docker images
To see a list of all installed docker images use:
docker images
Delete a specific docker image
To delete a specific docker image, first use the docker images
command to list all installed containers and then use the IMAGE ID
and the rmi
instruction to delete the container:
docker rmi -f 7d9495d03763
Export and Import a docker image
If you don't want to depend on an internet connection, you can also export an already downloaded docker image and then later on import it on another PC. To do so, use the following two commands:
# Export docker image miykael/nipype_tutorial
docker save -o nipype_tutorial.tar miykael/nipype_tutorial
# Import docker image on another PC
docker load --input nipype_tutorial.tar
It might be possible that you run into administrator privileges issues because you ran your docker command with sudo
. This means that other 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
from:
https://miykael.github.io/nipype_tutorial/notebooks/introduction_docker.html
Change default vm settings
The default Virtual Box VM does not provide enough resources to give a good experience when building Yocto images. We recommend you create a new VM with at least 2 CPUs and 4GB of memory.
-
Run Docker Quickstart Terminal and then run the following commands in that terminal.
-
Remove the default vm
docker-machine rm default
-
Re-create the default vm
- Choose the number of cpus with --virtualbox-cpu-count. For this example we'll use two.
- Choose the amount of RAM: --virtualbox-memory. This is also based on the host hardware. However, choose at least 4GB.
- Choose the amount of disk space: --virtualbox-disk-size. It is recommended that this be at least 50GB since building generates a lot* of output. In this example we'll choose 50GB.
- Create vm with new settings
docker-machine create -d virtualbox --virtualbox-cpu-count=2 --virtualbox-memory=4096 --virtualbox-disk-size=50000 default
-
Restart docker
docker-machine stop exit
https://github.com/crops/docker-win-mac-docs/wiki/Windows-Instructions-(Docker-Toolbox)