First go at documenting use of docker containers.

Needs testing.

doc/ipynb/tutorial-docker-container.ipynb

@@ -0,0 +1,243 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Run fidimag inside a Docker Container"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup Docker"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Install Docker, follow instructions at https://www.docker.com/products/docker\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup fidimag docker container with Jupyter Notebook\n",
+    "\n",
+    "Pull the `fidimag notebook` container:\n",
+    "\n",
+    "```\n",
+    "docker pull fidimag\n",
+    "    ```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Start Notebook on container"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```\n",
+    "docker run -p 30000:8888 fidimag/notebook\n",
+    "```\n",
+    "\n",
+    "This command starts a [Jupyter Notebook](http://jupyter.org) in which [fidimag]() can be used. The Jupyter notebook inside the container is listening on port 8888.\n",
+    "\n",
+    "The parameter `-p 30000:8888` says that the port 8888 inside the container is exposed on the host system as port 30000. \n",
+    "\n",
+    "On a Linux host machine, you can connect to `http://localhost:30000` to see the notebook. \n",
+    "\n",
+    "On a Mac, you need to find out the right IP address to which to connect. The information is provided by \n",
+    "```\n",
+    "docker-machine ip\n",
+    "```\n",
+    "For example, if `docker-machine ip` returns `192.168.99.100`, then the right URL to paste into the browser on the host system is `http://192.168.99.100/30000`.\n",
+    "\n",
+    "[How does this work on Windows? Pull requests welcome.]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Detach the docker image (to run in the background)\n",
+    "\n",
+    "You can add the `-d` switch to the `docker run` command to *detach* the process:\n",
+    "```\n",
+    "docker run -d -p 30000:8888 fidimag/notebook\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Show active Docker containers\n",
+    "```docker ps``` lists all running containers.\n",
+    "\n",
+    "To only show the `id`s, we can use ```docker ps -q```\n",
+    "\n",
+    "To only show the containers that was last started, we can use the `-l` flag:\n",
+    "``` docker ps -l```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Stop a docker container\n",
+    "\n",
+    "To stop the last container started, we can use the ```docker stop ID``` command, where we need to find the `ID` first. We can do this using ```docker ps -l -q```. Putting the commands together, we have \n",
+    "```\n",
+    "docker stop $(docker ps -l -q)\n",
+    "```\n",
+    "to stop the last container we started."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Explore the docker container / run Fidimag from (I)Python\n",
+    "\n",
+    "We can start the docker container with the `-ti` switch, and we can provide `bash` as the command to execute:\n",
+    "```\n",
+    "docker run -ti fidimag/notebook bash\n",
+    "```\n",
+    "\n",
+    "A bash prompt appears (and we are now inside the container):\n",
+    "```\n",
+    "jovyan@4df962d27520:~/work$\n",
+    "```\n",
+    "\n",
+    "and can start Python inside the container, and import fidimag:\n",
+    "\n",
+    "```\n",
+    "jovyan@4df962d27520:~/work$ python\n",
+    "Python 3.5.1 |Continuum Analytics, Inc.| (default, Jun 15 2016, 15:32:45) \n",
+    "[GCC 4.4.7 20120313 (Red Hat 4.4.7-1)] on linux\n",
+    "Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n",
+    ">>> import  fidimag\n",
+    "```\n",
+    "\n",
+    "We could also start IPython:\n",
+    "```\n",
+    "jovyan@4df962d27520:~/work$ ipython\n",
+    "Python 3.5.1 |Continuum Analytics, Inc.| (default, Jun 15 2016, 15:32:45) \n",
+    "Type \"copyright\", \"credits\" or \"license\" for more information.\n",
+    "\n",
+    "IPython 4.2.0 -- An enhanced Interactive Python.\n",
+    "?         -> Introduction and overview of IPython's features.\n",
+    "%quickref -> Quick reference.\n",
+    "help      -> Python's own help system.\n",
+    "object?   -> Details about 'object', use 'object??' for extra details.\n",
+    "\n",
+    "In [1]: \n",
+    "```\n",
+    "\n",
+    "[The switch `-t` stands for `Allocate a pseudo-TTY` and `-i` for `Keep STDIN open even if not attached`.]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Mount the local file system to exchange files and data with container"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Often, we may have a fidimag Python script `run.py` we want to execute in our current working directory in the host machine. We want output files from that command to be written to the same working directory on the host machine. \n",
+    "\n",
+    "We can use the container like this to achieve that:\n",
+    "\n",
+    "```\n",
+    "docker run -v `pwd`:/io -ti fidimag/notebook python hello.py```\n",
+    "\n",
+    "The ```-v `pwd`:/io``` tells the docker container to take the current working directory on the host (``` `pwd` ```) and mount it to the path `/io` on the container. The container is set up so that the default working directory is `/io`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here is an example file `run.py` that reads\n",
+    "```\n",
+    "import fidimag   # to proof we can import it\n",
+    "print(\"Hello from the container\")\n",
+    "# and write to a file\n",
+    "open(\"data.txt\", \"w\").write(\"Data from the container.\\n\")\n",
+    "```\n",
+    "\n",
+    "This can be executed with\n",
+    "```\n",
+    "   docker run -v `pwd`:/io -ti fidimag/notebook python hello.py\n",
+    "```\n",
+    "and will create a data file `data.txt` that is visible from the host's working directory.\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Explore Jupyter notebook examples with the Docker container"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```\n",
+    "git clone https://github.com/computationalmodelling/fidimag.git\n",
+    "cd fidimag/doc/ipynb/\n",
+    "docker run -v `pwd`:/io -p 30000:8888 -d fidimag/notebook\n",
+    "```\n",
+    "\n",
+    "            "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Use smaller docker containers\n",
+    "Two alternative docker containers are available that provide only Fidimag, but not the Jupyter Notebook, nor scipy. They are available under the names `fidimag/minimal-py2` and `fidimag/minimal-py3`. Use these names instead of `fidimag/notebook` in the examples above.\n",
+    "\n",
+    "The `fidimag/minimal-py2` version uses Python2, the `fidimag/minimal-py3` version uses Python 3."
+   ]
+  }
+ ],
+ "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.5.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}