{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "

\n", "PSY 381D Brain Connectivity, Spring 2019\n", "\n", "\n", "\"title\n", "\n", "

\n", "\n", "\n", "

Docker and Docker Image

\n", "\n", "

January 28, 2019

\n", "\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**Docker** is a software tool that lets you run a collection of software packages and libraries, known as a Docker image, as if you are running a virtual machine (a computer inside your computer). A **Docker image** is self-contained, so you do not have to do any complicated installation processes (except Docker)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Getting Docker on your computer\n", "
\n", "\n", "First, your computer has to have **Docker** installed, if it has not been installed already. If your computer is relatively new, then you can download and install **Docker for Windows** or **Docker for Mac**. The link for downloading, as well as the documentation for installation are available at:\n", "\n", " * [Docker for Windows](https://docs.docker.com/docker-for-windows/install/)\n", " * [Docker for Mac](https://docs.docker.com/docker-for-mac/install/)\n", "\n", "If your computer is somewhat old (like mine), then I recommend installing **Docker Toolbox** instead. The download link and the documentation are available at:\n", "\n", " * [Docker Toolbox for Windows](https://docs.docker.com/toolbox/toolbox_install_windows/)\n", " * [Docker Toolbox for Mac](https://docs.docker.com/toolbox/toolbox_install_mac/)\n", "\n", "Once Docker is installed on your computer, ***you can run docker commands on a bash-style shell (i.e., Linux-style terminal)***, most likely via the Command Prompt (Windows) or the Terminal (Mac). See the corresponding documentation from the links above. To test the installation, run the following command:\n", "```\n", "docker run hello-world\n", "```\n", "If Docker is correctly installed on your computer, you should see a message:\n", "```\n", "\n", "Hello from Docker!\n", "This message shows that your installation appears to be working correctly.\n", "\n", "To generate this message, Docker took the following steps:\n", " 1. The Docker client contacted the Docker daemon.\n", " 2. The Docker daemon pulled the \"hello-world\" image from the Docker Hub.\n", " (amd64)\n", " 3. The Docker daemon created a new container from that image which runs the\n", " executable that produces the output you are currently reading.\n", " 4. The Docker daemon streamed that output to the Docker client, which sent it\n", " to your terminal.\n", "\n", "...\n", "```\n", "\n", "*If you are a Linux user, then the installation of Docker is more complicated, and varies depending on your distribution. I recommend consulting the [Docker website](https://docs.docker.com/install/) for more details.*" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Getting the Docker image\n", "
\n", "\n", "Now that Docker is installed on your computer, you are ready to download a **Docker image**. A Docker image is a bundle of software packages and libraries. Thanks to Docker, installing these software tools and libraries is a breeze! There are two Docker images available for this course:\n", " * **`sathayas/python-network-bundle`** (1.0GB): Docker image containing Python 3 and libraries associated with network data processing. \n", " * **`sathayas/python-fsl-bundle`** (12.5GB): Docker image with the contents of `sathayas/python-network-bundle`, plus brain imaging data analysis libraries and FSL (brain image analysis software package).\n", " \n", "At first, ***I highly recommend starting with `sathayas/python-network-bundle`.*** To install a Docker image, simply run the following command:\n", "```\n", "docker pull [Docker image name]\n", "```\n", "where `[Docker image name]` is one of the two Docker images listed above. To verify if the Docker image has been correctly downloaded, run the following command:\n", "```\n", "docker images\n", "```\n", "Then you should see an output like this:\n", "```\n", "REPOSITORY TAG IMAGE ID CREATED SIZE\n", "sathayas/python-network-bundle latest a2adf624dee0 9 hours ago 1.07GB\n", "```\n", "\n", "Just FYI, this docker image `sathayas/python-analytics-bundle` contains the following:\n", "* Python 3.7 and the following libraries:\n", " * Numpy\n", " * Scipy\n", " * Matplotlib\n", " * Pandas\n", " * IPython\n", " * Jupyter\n", " * Scikit-learn\n", " * networkX\n", " * Python-Louvain\n", " * Graphviz\n", "* Graphviz -- a network visualization software package\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Running the Docker image\n", "
\n", "\n", "\n", "To run the Python Docker image, run the command:\n", "```\n", "docker run -it --rm -p 8888:8888 [Docker image name]\n", "```\n", "And this should change the prompt on your terminal to a prompt of an Ubuntu virtual machine (a popular distribution of Linux). From here, you can start IPython (an interactive Python shell) by the command **`ipython`**, which invokes an IPython session:\n", "```\n", "root@6cb65af29966:/tmp# ipython\n", "Python 3.6.7 (default, Oct 22 2018, 11:32:17) \n", "Type 'copyright', 'credits' or 'license' for more information\n", "IPython 7.2.0 -- An enhanced Interactive Python. Type '?' for help.\n", "\n", "In [1]: \n", "\n", "```\n", "You can copy and paste a Python code from a Python editor on your computer. *One downside of running a Docker image is that you cannot generate any graphical outputs to be displayed on the screen.* If you want to generate graphical outputs, you need to run **Jupyter notebook**.\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Running Jupyter notebook\n", "
\n", "\n", "\n", "**Jupyter notebook** lets you edit and run Python codes embedded in a notebook document via your web browser. You can display images and plots generated by Python inside your browser. To start Jupyter notebook, you can run the command **`jnb`** at the command prompt for the Ubuntu Docker container (container = an instance of a running Docker image) your terminal. This command is a shorthand notation (i.e., alias) for the command:\n", "```\n", "jupyter notebook --ip 0.0.0.0 --no-browser --allow-root\n", "```\n", "Then you will see a message on your terminal like this one:\n", "```\n", "...\n", " To access the notebook, open this file in a browser:\n", " file:///root/.local/share/jupyter/runtime/nbserver-10-open.html\n", " Or copy and paste one of these URLs:\n", " http://(ff3070aa4710 or 127.0.0.1):8888/?token=713283a6a2ec82df89844332699c31e3567910a6274a9e14\n", "```\n", "Then open your favorite web browser on your computer, and set the URL to either:\n", "* `http://192.168.99.100:8888/?token=713283a6a2ec82df89844332699c31e3567910a6274a9e14`\n", "* `http://localhost:8888/?token=713283a6a2ec82df89844332699c31e3567910a6274a9e14`\n", "\n", "The important thing to note here is that the string\n", "```\n", "?token=713283a6a2ec82df89844332699c31e3567910a6274a9e14\n", "``` \n", "needs to be copied from the terminal to you web browser. This string identifies which session of Jupyter notebook is displayed on your web browser.\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Mounting a folder\n", "
\n", "\n", "\n", "When you run a Docker image (referred as a **Docker container**) on your computer, the resulting Docker container runs as if it is independent of your local computer. This means that it has its own separate directories and files, that are not visible from your local computer.\n", "\n", "However, you can share a folder on your local computer with a Docker container. This is done by using the **`-v`** parameter on `docker run` command. Here is an example of how you can map a Jupyter notebook folder on your computer (e.g., one you cloned from GitHub) to the Jupyter notebook folder inside this particular Docker image:\n", "\n", "```\n", "docker run -it --rm -p 8888:8888 \\\n", "-v [Path to Notes folder]:/tmp/Notes:z \\\n", "[Docker image name]\n", "```\n", "\n", "Here, the folder indicated by **`[Path to Notes folder]`** is mapped to **`/tmp/Notes`** directory inside the Docker container. So you will be able to view, edit, create, and save documents to this directory inside a Docker container and such changes are preserved in the `Notes` folder on your local computer.\n", "\n", "It is possible to mount multiple folders to a Docker image. For example,\n", "```\n", "docker run -it --rm -p 8888:8888 \\\n", "-v [Path to Notes folder]:/tmp/Notes:z \\\n", "-v [Path to Codes folder]:/tmp/Codes:z \\\n", "-v [Path to Data folder]:/tmp/Data:z \\\n", "[Docker image name]\n", "```\n", "\n", "This way, the directories for notes, codes, and data are mounted to the Docker image virtual machine and are available under the `/tmp` directory." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.5" } }, "nbformat": 4, "nbformat_minor": 2 }