Skip to content

Commit 8dad5e5

Browse files
miykaelmiykael
committed
ENH: add docker notebook
1 parent 8d26e8d commit 8dad5e5

File tree

3 files changed

+188
-0
lines changed

3 files changed

+188
-0
lines changed

‎notebooks/introduction_docker.ipynb

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {
6+
"deletable": true,
7+
"editable": true
8+
},
9+
"source": [
10+
"<center><img src=\"../static/images/logoDocker.png\" width=500></center>\n",
11+
"\n",
12+
"# Docker\n",
13+
"\n",
14+
"[Docker](https://www.docker.com) 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.\n",
15+
"\n",
16+
"<font color='red'>Important:</font> **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 [Installation Section](resources_installation.ipynb) of this tutorial. But for Windows user, or users that don't want to setup all the dependencies themselves, Docker is the way to go."
17+
]
18+
},
19+
{
20+
"cell_type": "markdown",
21+
"metadata": {},
22+
"source": [
23+
"# Docker Image for the interactive Nipype Tutorial\n",
24+
"\n",
25+
"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_course](https://github.com/miykael/nipype_course). 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."
26+
]
27+
},
28+
{
29+
"cell_type": "markdown",
30+
"metadata": {},
31+
"source": [
32+
"# Install Docker\n",
33+
"\n",
34+
"Before you can do anything, you first need to install [Docker](https://www.docker.com) on your system. The installation process differes per system. Luckily, the docker homepage has nice instructions for...\n",
35+
"\n",
36+
" - [Ubuntu](https://docs.docker.com/engine/installation/linux/ubuntu/) or [Debian](https://docs.docker.com/engine/installation/linux/debian/)\n",
37+
" - [Windows 7/8/9/10](https://docs.docker.com/toolbox/toolbox_install_windows/) or [Windows 10Pro](https://docs.docker.com/docker-for-windows/install/)\n",
38+
" - [OS X (from El Capitan 10.11 on)](https://docs.docker.com/docker-for-mac/install/) or [OS X (before El Capitan 10.11)](https://docs.docker.com/toolbox/toolbox_install_mac/).\n",
39+
"\n",
40+
"Once Docker is installed, open up the docker terminal and test it works with the command:\n",
41+
"\n",
42+
" docker run hello-world\n",
43+
"\n",
44+
"**Note:** Mac and Linux users might need to use ``sudo`` to run ``docker`` commands."
45+
]
46+
},
47+
{
48+
"cell_type": "markdown",
49+
"metadata": {},
50+
"source": [
51+
"# How to run ``miykael/nipype_course``\n",
52+
"\n",
53+
"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 Course image. The exact implementation is a bit different for Windows user, but the general command looks as follows:\n",
54+
"\n",
55+
" docker run -ti --rm -p 8888:8888 -v /home/username/results:/output miykael/nipype_course\n",
56+
"\n",
57+
"But what do those flags mean?\n",
58+
"\n",
59+
"- The ``-ti`` flag tells docker that it should open an interactive container instance.\n",
60+
"- The ``--rm`` flag tells docker that the container should automatically be removed after we close docker.\n",
61+
"- The ``-p`` flag specifies which port we want to make available for docker.\n",
62+
"- The ``-v`` flag tells docker which folder (here: ``/home/username/results`` it should mount to make it accesible inside the container. The second part of the ``-v`` flag (here: ``/output``) specifies under which path the mounted folder can be found inside the container. This means that we can use the folder ``/output`` inside the tutorial to save data outside the docker container under ``/home/username/results``. **Important**: To use the ``results`` folder, you first need to create it on your system!\n",
63+
"- The last argument ``miykael/nipype_course`` tells docker that we want to run this docker image.\n",
64+
"\n",
65+
"To run a docker image, docker will look for the specified image on [Docker Hub](https://hub.docker.com/r/miykael/nipype_course/). If the docker image was already download to your system, it will be directly opened. Otherwise, it first needs to download all containers, which might take some time. \n",
66+
"\n",
67+
"\n",
68+
"## Run a docker image on Linux or Mac\n",
69+
"\n",
70+
"Running a docker image on a Linux or Mac OS is very simple. Make sure that you've created a results folder on your system (e.g. ``mkdir -p /home/username/results``). Then just open a new terminal and use the command from above:\n",
71+
"\n",
72+
" docker run -ti --rm -p 8888:8888 -v /home/username/results:/output miykael/nipype_course\n",
73+
"\n",
74+
"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:\n",
75+
"\n",
76+
" http://localhost:8888/?token=0312c1ef3b61d7a44ff5346d3d150c23249a548850e13868\n",
77+
"\n",
78+
"\n",
79+
"## Run a docker image on Windows\n",
80+
"\n",
81+
"Running a docker image on Windows is a bit trickier than on Ubuntu. Assuming you've installed the DockerToolbox, open the Docker Quickstart Terminal (encircled in red).\n",
82+
"\n",
83+
"<center><img src=\"../static/images/docker_terminal.png\" width=600></center>\n",
84+
"\n",
85+
"Once the docker terminal is ready (when you see the whale), we can execute the following steps (see also figure):\n",
86+
"\n",
87+
"1. We need to check the IP adress of your docker machine. For this, use the command: \n",
88+
"\n",
89+
" ``docker-machine ip``\n",
90+
"\n",
91+
" In my case, this returned ``192.168.99.100``\n",
92+
"\n",
93+
"2. 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:\n",
94+
"\n",
95+
" ``mkdir -p /c/Users/username/results``\n",
96+
"\n",
97+
" 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 backslash (``\\``) as we usually have in Windows. Also, ``C:\\`` needs to be specified as ``/c/``.\n",
98+
"\n",
99+
"3. Now, we can open run the container with the command from above:\n",
100+
"\n",
101+
" ``docker run -ti --rm -p 8888:8888 -v /c/Users/username/outputs:/output miykael/nipype_course``\n",
102+
"\n",
103+
"4. Once the docker image is downloaded, it will show you an URL that looks something like this:\n",
104+
"\n",
105+
" ``http://localhost:8888/?token=0312c1ef3b61d7a44ff5346d3d150c23249a548850e13868``\n",
106+
" \n",
107+
" 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:\n",
108+
"\n",
109+
" ``http://192.168.99.100:8888/?token=0312c1ef3b61d7a44ff5346d3d150c23249a548850e13868``\n",
110+
"\n",
111+
" Copy this link into your webbrowser and you're good to go!"
112+
]
113+
},
114+
{
115+
"cell_type": "markdown",
116+
"metadata": {},
117+
"source": [
118+
"# Docker tips and tricks\n",
119+
"\n",
120+
"\n",
121+
"## Access Docker Container with ``bash`` or ``ipython``\n",
122+
"\n",
123+
"You don't have to open a jupyter notebook when you run ``miykael/nipype_course``. You can also access the docker container directly with ``bash`` or ``ipython`` by adding it to the end of your command, i.e.:\n",
124+
"\n",
125+
" docker run -ti --rm -v /home/username/results:/output miykael/nipype_course bash\n",
126+
"\n",
127+
"This also works with other software commands, such as ``bet`` etc.\n",
128+
"\n",
129+
"\n",
130+
"## Stop Docker Container\n",
131+
"\n",
132+
"To stop a running docker container, either close the docker terminal or select the terminal and uste the ``Ctrl-C`` shortcut multiple times.\n",
133+
"\n",
134+
"\n",
135+
"## List all installed docker images\n",
136+
"\n",
137+
"To see a list of all installed docker images use:\n",
138+
"\n",
139+
" docker images\n",
140+
"\n",
141+
"\n",
142+
"## Delete a specific docker image\n",
143+
"\n",
144+
"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:\n",
145+
"\n",
146+
" docker rmi -f 7d9495d03763\n",
147+
"\n",
148+
"\n",
149+
"## Export and Import a docker image\n",
150+
"\n",
151+
"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:\n",
152+
"\n",
153+
"\n",
154+
" # Export docker image miykael/nipype_course\n",
155+
" docker save -o nipype_course.tar miykael/nipype_course\n",
156+
"\n",
157+
" # Import docker image on another PC\n",
158+
" docker load --input nipype_course.tar\n",
159+
" \n",
160+
"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_course.tar``. To avoid this, just change the rights of ``nipype_course.tar`` with the command:\n",
161+
"\n",
162+
" sudo chmod 777 nipype_course.tar"
163+
]
164+
}
165+
],
166+
"metadata": {
167+
"anaconda-cloud": {},
168+
"kernelspec": {
169+
"display_name": "Python [default]",
170+
"language": "python",
171+
"name": "python2"
172+
},
173+
"language_info": {
174+
"codemirror_mode": {
175+
"name": "ipython",
176+
"version": 2
177+
},
178+
"file_extension": ".py",
179+
"mimetype": "text/x-python",
180+
"name": "python",
181+
"nbconvert_exporter": "python",
182+
"pygments_lexer": "ipython2",
183+
"version": "2.7.13"
184+
}
185+
},
186+
"nbformat": 4,
187+
"nbformat_minor": 0
188+
}

‎static/images/docker_terminal.png

39.3 KB
Loading

‎static/images/logoDocker.png

13.3 KB
Loading

0 commit comments

Comments
 (0)