006_environments_2_docker.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "source": [
    "<a href=\"https://colab.research.google.com/github/rzl-ds/gu511/blob/master/006_environments_2_docker.ipynb\" target=\"_parent\">\n",
    "    <img src=\"https://colab.research.google.com/assets/colab-badge.svg\"/>\n",
    "</a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# environment management: `docker`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## why stop at `python`?\n",
    "\n",
    "in the previous lecture, we talked about how we could manage our `python` environment (the collected behavior of the `python` language as defined in particular files on our computer) by creating *virtual* environments with the `anaconda` environment management tool. this is something I do on *every* project for which I write `python` code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "`python` didn't *invent* environment management, though -- similar arrangements have been around for a long time in a log of different languages.\n",
    "\n",
    "`java`, for example, runs in one large virtual environment (the \"java virtual machine\", or `jvm` for short) that can (must!) be installed on any computer and defines the `java` environment on that computer in a way that is portable from one OS to the next."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "this doesn't fix *everything*, though. there's still a lot of interdependency between the code you write and the other applications running on your computer (that large collection of installed software that makes up your application's environment). what if I have more than one programming language? what if my application includes a service (like `postgres` or `elasticsearch`)?\n",
    "\n",
    "if a sysad updates some basic `linux` package or library that your code depends on, you may still run into problems. it would be nice if we could pin *all* of it, somehow..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "at a certain point, developers of the world started asking this bigger question: if we're going to these lengths to make sure our `python` or `java` environments (our language-specific *runtime* environments) are consistent, what's to stop us from virtualizing everything our applications need?\n",
    "\n",
    "why *not* pin the code, the runtime environment, the environment variables, the binaries in `/usr/bin`, the libraries in `/usr/lib`, the configurations in `/etc`, ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "over time, developers have coalesced to a particular tool for doing exactly that:\n",
    "\n",
    "<div align=\"center\"><img width=\"500px\" src=\"https://www.docker.com/sites/default/files/social/docker_facebook_share.png\"></div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "tangent: jails and user-level operating system virtualization were actually around loooooong before `docker`. this is a classic case of an old tool being \"rediscovered\" when solving a new-ish problem"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## `docker`\n",
    "\n",
    "[`docker`](https://docs.docker.com/get-started/) is software which allows you to create **`containers`**: independent virtual environments running as isolated processes on your computer.\n",
    "\n",
    "in other words, `containers` are frozen environments containing all of the files (of any kind, not just related to `python`) and configuration variables that are required for your application to work. they are pinned to certain versions and you can repeatedly \"create\" them on any system which has `docker` installed regardless of what that system looks like"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "> Containers are an abstraction at the app layer that packages code and dependencies together. Multiple containers can run on the same machine and share the OS kernel with other containers, each running as isolated processes in user space\n",
    "\n",
    "<div align=\"center\"><img src=\"https://www.docker.com/sites/default/files/d8/2018-11/docker-containerized-appliction-blue-border_2.png\" width=\"600px\"></div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "to parse that diagram a bit, top to bottom:\n",
    "\n",
    "we all have computers with **hardware** / **infrastructure**. the phrase **infrastructure** is used because there may be virtualized hardware (e.g. `ec2`) rather than physical hardware (our laptops)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "sitting on top of that hardware is the **operating system**. we have been flippant about the word \"operating system\" so far, suggesting it was `mac`, `windows`, `linux`, `linux:ubuntu`, etc. here I mean the \"kernel\" layer, the code that manages the interaction with the hardware.\n",
    "\n",
    "much of what you think of as the \"`linux` environment\" is actually the software (libraries and binaries) you use rather than the low-level operating system itself."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "the binaries and libraries that you are used to working with (in `ubuntu` e.g.) are considered part of an **application**, not part of the operating system."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "**`docker`** is itself a software application that runs (like all applications do) on top of the operating system.\n",
    "\n",
    "it builds and manages **`containers`**, packaged and frozen collections of files, binaries, libraries, *etc.* which define a runnable application"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "note that the binaries and libraries -- all the non-`python` dependencies of your application, e.g. -- don't have to be the same as the ones installed on the computer you are using. this is one of the fundamental reasons we are going through this hassle, to allow us to start on any computer anywhere and reliably reproduce the **environment** in which we have developed and test our application."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### `docker` is **like** `conda`\n",
    "\n",
    "`docker` is **like** `conda` in that we could use `conda` to manage multiple different `python` environments, and in those environments we had controlled, guaranteed code behavior.\n",
    "\n",
    "we can use `docker` to create and run code in  multiple different application environments (pretty much just `linux`, but several flavors, and as many versions or slight variations as you'd like). if our application requires special `nvidia` libraries to support deep neural net calculations, we add that to the container. if that library is a different version or doesn't even exist on the host, no worries."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### `docker` is **unlike** `conda`\n",
    "\n",
    "`docker` is also **unlike** `conda` in many ways, but for our purposes the most important is how it functions from a user's perspective.\n",
    "\n",
    "with `conda`, we were working in a terminal and we `activate`d our environment. we were then \"in\" that `python` environment and we could run `python` code as needed. we could switch \"in\" and \"out\" of that environment with a command. `conda` changes your current terminal session.\n",
    "\n",
    "`docker` is different: `docker` creates a *new, separate process* (a `container`). `docker` does not change anything about your current terminal session, or your current (host) operating system or environment."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "by way of a perhaps strange analogy:\n",
    "\n",
    "+ `conda` takes our existing `bash` process and modifies it slightly such that the way `python` commands and code are executed is different. this is like redecorating your single room apartment -- it's still the one room, but now your experience of it is different\n",
    "+ `docker` creates a new process that is running on our machine but is completely different than our base experience and possibly not even reachable from our base experience. this is like building an extension on your house, or a guest house: the new rooms can be whatever you want and don't change anything about the room you started in"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "you can think of that `container` as being much like any other operating system, and the model of interacting with it is similar to how we interact with remote computers over `ssh`\n",
    "\n",
    "+ to access it you may need to explicitly \"log in\"\n",
    "+ being \"inside\" that container basically means having access to a terminal prompt where you may execute commands\n",
    "+ while \"inside\" it would look and feel like an entire `ubuntu` application environment\n",
    "+ from that \"inside\" prompt, commands you run are being executed inside the virtual environment, not the host operating system in which this all started"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "**<div align=\"center\">that's a lot. PAUSE FOR ZOOM BREAK</div>**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## walkthrough\n",
    "\n",
    "enough of the high-level discussion, though -- let's dive in and get some experience"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### installing `docker`\n",
    "\n",
    "let's start by installing `docker` on our `ec2` instances"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "**<div align=\"center\">mini exercise: everyone installs `docker` on their `ec2`</div>**\n",
    "\n",
    "full instructions here: https://docs.docker.com/install/linux/docker-ce/ubuntu/#install-docker-ce. steps:\n",
    "\n",
    "```sh\n",
    "sudo apt-get remove docker docker-engine docker.io containerd runc\n",
    "\n",
    "sudo apt-get update\n",
    "\n",
    "sudo apt-get install apt-transport-https gnupg-agent\n",
    "\n",
    "curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -\n",
    "sudo apt-key fingerprint 0EBFCD88\n",
    "\n",
    "sudo add-apt-repository \\\n",
    "   \"deb [arch=amd64] https://download.docker.com/linux/ubuntu \\\n",
    "   $(lsb_release -cs) \\\n",
    "   stable\"\n",
    "\n",
    "sudo apt-get update\n",
    "sudo apt-get install docker-ce\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### test that it worked\n",
    "\n",
    "try running\n",
    "\n",
    "```sh\n",
    "# docker only runs as sudo by default\n",
    "sudo docker run hello-world\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "you should get something like\n",
    "\n",
    "```sh\n",
    "Unable to find image 'hello-world:latest' locally\n",
    "latest: Pulling from library/hello-world\n",
    "d1725b59e92d: Pull complete\n",
    "Digest: sha256:0add3ace90ecb4adbf7777e9aacf18357296e799f81cabc9fde470971e499788\n",
    "Status: Downloaded newer image for hello-world:latest\n",
    "\n",
    "Hello from Docker!\n",
    "This message shows that your installation appears to be working correctly.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "in addition, `docker` gives us a helpful rundown of exactly what just happened:\n",
    "\n",
    "```sh\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",
    "To try something more ambitious, you can run an Ubuntu container with:\n",
    " $ docker run -it ubuntu bash\n",
    "\n",
    "Share images, automate workflows, and more with a free Docker ID:\n",
    " https://hub.docker.com/\n",
    "\n",
    "For more examples and ideas, visit:\n",
    " https://docs.docker.com/get-started/\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### `images` and `containers`\n",
    "\n",
    "that help message contained a lot of new words, but the two most important from `docker`s perspective are `image` and `container`. these are the fundamental \"things\" that `docker` cares about."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "per the `docker` docs (that's fun), an **`image`** is\n",
    "\n",
    "> an executable package that includes everything needed to run an application--the code, a runtime, libraries, environment variables, and configuration files.\n",
    "\n",
    "under the hood, this is basically a `tar`-ball of all the files that are required for your program to run. it is as if we started up a brand new computer with *only* the low-level operating system files, installed only the libraries and packages we needed, and then created a snapshot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "an `image` is a collection of the files we should use to define the environment in which an application runs, and a **`container`** is a single instance of that `image` being built and run on top of a real operating system. from the docs again:\n",
    "\n",
    "> A container is a runtime instance of an image -- what the image becomes in memory when executed (that is, an image with state, or a user process)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "the high-level plan for any `docker` application is to take an `image` which defines the applications with environment and we use it to build a `container` that **does something** (tbd), and does it in a consistent, reproducible way.\n",
    "\n",
    "let's look at examples of those two pieces"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "#### example `image`\n",
    "\n",
    "when we ran `sudo docker run hello-world`, the second thing `docker` said it did was it `pull`ed the `image` from [DockerHub](https://hub.docker.com/). a lot of the language and behavior in `docker` world copies the language of `git`.\n",
    "\n",
    "*what do you think DockerHub is*?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "much like `github` is a remote service we can all use to share `git` repositories, `DockerHub` is a remote service we can all use to share `image`s. we download those images using `pull`. try the following:\n",
    "\n",
    "```sh\n",
    "sudo docker pull ubuntu:latest\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "```\n",
    "latest: Pulling from library/ubuntu\n",
    "5667fdb72017: Pull complete\n",
    "d83811f270d5: Pull complete\n",
    "ee671aafb583: Pull complete\n",
    "7fc152dfb3a6: Pull complete\n",
    "Digest: sha256:b88f8848e9a1a4e4558ba7cfc4acc5879e1d0e7ac06401409062ad2627e6fb58\n",
    "Status: Downloaded newer image for ubuntu:latest\n",
    "docker.io/library/ubuntu:latest\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "this command pulls down various files which collectively define a single `image` called `ubuntu:latest`. the first piece (`ubuntu`) is a **repository** name, and you can find that particular repository [on DockerHub](https://hub.docker.com/r/library/ubuntu/).\n",
    "\n",
    "as with `git`, repositories can be local (I created it on my computer) or shared (someone uploaded a local repository to `DockerHub`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "the second piece (`latest`) is a **tag**, and it acts much like a tag or commit `sha` does in `git` world. within the `ubuntu` repository there are [different tag values](https://hub.docker.com/r/library/ubuntu/tags/) (for different versions, for example).\n",
    "\n",
    "the `latest` tag is a special tag which is defined for every repository and points to the most recently created image in that repository."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "we can verify that we now have a new `ubuntu` `docker` `image` by running\n",
    "\n",
    "```sh\n",
    "sudo docker image ls\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "```\n",
    "REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE\n",
    "ubuntu              latest              2ca708c1c9cc        2 weeks ago         64.2MB\n",
    "hello-world         latest              fce289e99eb9        9 months ago        1.84kB\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "#### example `container`\n",
    "\n",
    "remember, the point of an `image` is to define the files and environment of an application, and actually running that application requires building a `container`, a running instance of that `image`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "way back when we ran `sudo docker run hello-world` we were told by `docker` that we should try running a command:\n",
    "\n",
    "```sh\n",
    "# don't run until you know what this does\n",
    "sudo docker run -it ubuntu bash\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "the `docker run` command takes an `image` (identified by `repository[:tag]`, here `ubuntu`), builds a container based on that `image`, and runs *some* command.\n",
    "\n",
    "you can pass the command you'd like to run as an argument to `docker run`, or most `images` will have a default command that runs when you provide none. here we want to run `bash` inside our `container`.\n",
    "\n",
    "the two flags are working together to give you an interactive terminal for that `bash` process we start:\n",
    "\n",
    "+ `-i` / `--interactive`: run in *interactive* mode (let me as a user interact with the command running inside that `container`)\n",
    "+ `-t` / `--tty`: allocate a pseudo-TTY (a terminal)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "**<div align=\"center\">mini exercise: `run` an `ubuntu` `docker` `container`</div>**\n",
    "\n",
    "check your regular `ec2` instance's OS version by printing the contents of a release file:\n",
    "\n",
    "```sh\n",
    "cat /etc/lsb-release\n",
    "```\n",
    "\n",
    "now create an `ubuntu` `docker` `image` with\n",
    "\n",
    "```sh\n",
    "sudo docker run -it ubuntu bash\n",
    "```\n",
    "\n",
    "your prompt should change. try the following commands at this new prompt:\n",
    "\n",
    "```sh\n",
    "cat /etc/lsb-release\n",
    "hostname\n",
    "ls -alh\n",
    "exit\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "by default, `docker` does not get rid of used `container`s. you can force it to do so by providing the flag `--rm` to remove the container when it finishes, and that is somewhat common.\n",
    "\n",
    "you can see the container you just created with either\n",
    "\n",
    "```sh\n",
    "sudo docker container ls --all\n",
    "```\n",
    "\n",
    "or\n",
    "\n",
    "```sh\n",
    "sudo docker ps --all\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "**<div align=\"center\">mini exercise: clean up those containers</div>**\n",
    "\n",
    "we don't need those containers any more and they *do* take up space -- let's get rid of them.\n",
    "\n",
    "run\n",
    "\n",
    "```sh\n",
    "sudo docker container ls --all\n",
    "```\n",
    "\n",
    "to get the values of the `CONTAINER ID` or `NAMES` columns. then\n",
    "\n",
    "```sh\n",
    "sudo docker container rm [YOUR CONTAINER ID OR NAMES VALUES HERE]\n",
    "```\n",
    "\n",
    "verify they are gone by again running\n",
    "\n",
    "```sh\n",
    "sudo docker container ls --all\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "**<div align=\"center\">mini exercise: `run` an `ubuntu` `docker` `container` that cleans up after itself</div>**\n",
    "\n",
    "we're going to do exactly what we did above, but now add the `--rm` flag -- then we will verify that the container is removed when we're done with it.\n",
    "\n",
    "check that no containers are left on our machine:\n",
    "\n",
    "```sh\n",
    "sudo docker container ls --all\n",
    "```\n",
    "\n",
    "then create an `ubuntu` container running the `bash` command, but with the `--rm` flag set\n",
    "\n",
    "```sh\n",
    "sudo docker run -it --rm ubuntu bash\n",
    "```\n",
    "\n",
    "do anything you want inside, but eventually `exit`. then check the container list again:\n",
    "\n",
    "```sh\n",
    "sudo docker container ls --all\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### summary\n",
    "\n",
    "with the above tools we already know how we could take any shared `docker` `image` out on `DockerHub` and create a local container:\n",
    "\n",
    "1. get the `repository` and possibly `tag` name we want\n",
    "    1. example: [the tensorflow docker image](https://hub.docker.com/r/tensorflow/tensorflow/) has `repository = tensorflow/tensorflow` and many `tag` values, including `1.11.0-gpu-py3`\n",
    "1. use that info to run `sudo docker image pull repository[:tag]`\n",
    "1. use that downloaded `image` to create a `container` with `sudo docker run repository[:tag]`\n",
    "    1. note: `docker run` for an `image` that doesn't exist will check dockerhub for that image by default"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "**<div align=\"center\">that's a lot. PAUSE FOR ZOOM BREAK</div>**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### creating specialized `image`s\n",
    "\n",
    "I said you could build `image`s locally, but I've only shown how we go and get these `image`s from `DockerHub`. in practice, that's important for every `docker` `image` I build -- it's the starting point of all of them, at least.\n",
    "\n",
    "`docker` knows how to build `image`s by following a series of special commands written in a plain text file called a `Dockerfile`. this `Dockerfile` is effectively a \"recipe\" for how `docker` can go from an initial basic `image` to your customized `image`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "the official [`docker` docs](https://docs.docker.com/get-started/part2/#define-a-container-with-dockerfile) offer an example application with `Dockerfile`, and I've modified it to reflect some of the magic we already built in `tacoworld`. I've put it on `github` [here](https://github.com/RZachLamberty/docker_tacoworld_app). let's get it on our `ec2` instances using `git`:\n",
    "\n",
    "```sh\n",
    "git clone https://github.com/RZachLamberty/docker_tacoworld_app.git\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "the app itself is very simple (so simple, in fact, it breaks several of the rules I taught you just a lecture or two ago):\n",
    "\n",
    "```python\n",
    "import os\n",
    "import socket\n",
    "\n",
    "# why not?\n",
    "import pandas as pd\n",
    "\n",
    "print(f\"\"\"\n",
    "HELLO {os.getenv(\"NAME\", \"world\")}\n",
    "my name is {socket.gethostname()}\n",
    "these are the results of the tacoworld (tm) model\n",
    "----------------------\n",
    "\n",
    "I, Zach Lamberty, want tacos more than *anyone*, especially more than Eamon!\n",
    "I, Eamon Lamberty, want tacos, so it's good there are enough to share!\n",
    "\"\"\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "running it on my local laptop via `python app.py` gives:\n",
    "\n",
    "```\n",
    "HELLO world\n",
    "my name is Zachs-MacBook-Pro.local\n",
    "these are the results of the tacoworld (tm) model\n",
    "----------------------\n",
    "\n",
    "I, Zach Lamberty, want tacos more than *anyone*, especially more than Eamon!\n",
    "I, Eamon Lamberty, want tacos, so it's good there are enough to share!\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "one of my tacolaborators has a `windows` computer, but they want to be able to run my deep neural print model as well, so I have decided to make it portable using `docker`. I need to create a `docker` `image` to share with them, and I can do that with a `Dockerfile`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "here's the `Dockerfile`:\n",
    "\n",
    "```Dockerfile\n",
    "# Use an official Python runtime as a parent image\n",
    "FROM python:3.8-slim\n",
    "\n",
    "# Set the working directory to /app\n",
    "WORKDIR /app\n",
    "\n",
    "# Copy the current directory contents into the container at /app\n",
    "COPY . /app\n",
    "\n",
    "# Install any needed packages specified in requirements.txt\n",
    "RUN pip install --trusted-host pypi.python.org -r requirements.txt\n",
    "\n",
    "# Make port 80 available to the world outside this container\n",
    "EXPOSE 80\n",
    "\n",
    "# Define environment variable\n",
    "ENV NAME World\n",
    "\n",
    "# Run app.py when the container launches\n",
    "CMD [\"python\", \"app.py\"]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "let's go through this one line at a time:\n",
    "\n",
    "```Dockerfile\n",
    "# Use an official Python runtime as a parent image\n",
    "FROM python:3.8-slim\n",
    "```\n",
    "\n",
    "the `FROM` command tells `docker` that this `image` is built on top of a different one (here, `python:3.8-slim`). the majority of `Dockerfile`s you will encounter start like this, and the resulting `image` is like an onion -- it's built on top of a smaller `image`, which itself was built on top of a smaller `image`, which ...\n",
    "\n",
    "this image is often called the `parent` image. there is a way to build an `image` without a `parent` (called a `base` `image`) but we won't cover that right now"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "```Dockerfile\n",
    "# Set the working directory to /app\n",
    "WORKDIR /app\n",
    "```\n",
    "\n",
    "when you are operating on the command line in your `ec2` instance you have a working directory, and commands are executed relative to that. here we do the same but \"inside\" our linux environment as it is being built. we use the `docker` command `WORKDIR` to do this.\n",
    "\n",
    "here we change the working directory of the following `docker` commands to be `/app` *inside our container*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "```Dockerfile\n",
    "# Copy the current directory contents into the container at /app\n",
    "COPY . /app\n",
    "```\n",
    "\n",
    "the `docker` `COPY` command can be used to copy files I have on my host (here, on our `ec2` instance) into our `image` -- this is the main way you add files to an `image`, by copying them into it. here we instruct `docker` to copy our files (`Dockerfile`, `app.py`, `README.md`, and `requirements.txt`) into the `/app` directory.\n",
    "\n",
    "now our `image` will have a file `/app/app.py`, for example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "```Dockerfile\n",
    "# Install any needed packages specified in requirements.txt\n",
    "RUN pip install --trusted-host pypi.python.org -r requirements.txt\n",
    "```\n",
    "\n",
    "the `RUN` command allows us to specify that part of the building of this `image` should be to run some command. that command has to be defined inside that `image` by the time we try to `RUN` it, and that is not always the case!\n",
    "\n",
    "here, `pip` is installed for us in our `parent` `image` `python:3.8-slim`, so we are free to use it already. we install the one package listed in `requirements.txt` (`pandas`) this way."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "```\n",
    "# Make port 80 available to the world outside this container\n",
    "EXPOSE 80\n",
    "```\n",
    "\n",
    "the `EXPOSE` command is used to **expose** resources inside the container to the outside world. here we are suggesting that it is possible for you on your base `ec2` image to \"connect\" something (tbd) to the running container's port 80.\n",
    "\n",
    "if you wanted to run some service that receives requests via `http` (like `jupyter`, e.g., on port `8888`) inside your container, and then be able to access it from your `ec2` instance, you would `EXPOSE 8888`, and then figure out how to send requests to that port (tbd later)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "```Dockerfile\n",
    "# Define environment variable\n",
    "ENV NAME World\n",
    "```\n",
    "\n",
    "`docker` allows us to set environment variables within the `image` and subsequent `containers` with the `ENV` command. here we suggest that any new `container` should have an environment variable `$NAME` equal to \"`World`\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "```Dockerfile\n",
    "# Run app.py when the container launches\n",
    "CMD [\"python\", \"app.py\"]\n",
    "```\n",
    "\n",
    "finally, the `CMD` command can be used to suggest what command should be run when a new `container` is created (assuming the user doesn't suggest one of their own). here we tell `docker` to build an `image` which is expecting to run `python app.py` (the items in the list get joined together with spaces between them) on startup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "altogether, again:\n",
    "\n",
    "```Dockerfile\n",
    "# Use an official Python runtime as a parent image\n",
    "FROM python:3.8-slim\n",
    "\n",
    "# Set the working directory to /app\n",
    "WORKDIR /app\n",
    "\n",
    "# Copy the current directory contents into the container at /app\n",
    "COPY . /app\n",
    "\n",
    "# Install any needed packages specified in requirements.txt\n",
    "RUN pip install --trusted-host pypi.python.org -r requirements.txt\n",
    "\n",
    "# Make port 80 available to the world outside this container\n",
    "EXPOSE 80\n",
    "\n",
    "# Define environment variable\n",
    "ENV NAME World\n",
    "\n",
    "# Run app.py when the container launches\n",
    "CMD [\"python\", \"app.py\"]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "we tell `docker` to `build` the `image` from this `Dockerfile` using the `docker build` command. along the way, we name the `image` with the `-t` flag and give it a value in the `repository[:tag]` format.\n",
    "\n",
    "let's create a new `image` named `tacoworld:docker_demo`\n",
    "\n",
    "```sh\n",
    "sudo docker build -t tacoworld:docker_demo .\n",
    "```\n",
    "\n",
    "*note*: the `.` is important!! that tells `docker` what the *context* of this `build` is: the local working directory / files it should be looking at to build the `image`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "you will see a long printout like this:\n",
    "\n",
    "```\n",
    "Sending build context to Docker daemon  80.38kB\n",
    "Step 1/7 : FROM python:3.8-slim\n",
    "3.8-slim: Pulling from library/python\n",
    "d121f8d1c412: Pull complete \n",
    "ca572574cc82: Pull complete \n",
    "38ead5def216: Pull complete \n",
    "d66d8ce1705e: Pull complete \n",
    "922f4bd7bc61: Pull complete \n",
    "Digest: sha256:0944c626f71b2f44ed45c13761f3cb97d75566261ade2b2d34f6ce2987dacbcb\n",
    "Status: Downloaded newer image for python:3.8-slim\n",
    " ---> 62297c9f4e5c\n",
    "Step 2/7 : WORKDIR /app\n",
    " ---> Running in 48f585c36b3b\n",
    "Removing intermediate container 48f585c36b3b\n",
    " ---> f345411c943e\n",
    "Step 3/7 : COPY . /app\n",
    "s ---> 3ff49ccda267\n",
    "Step 4/7 : RUN pip install --trusted-host pypi.python.org -r requirements.txt\n",
    " ---> Running in e8294cc32e0e\n",
    "udo docker image ls --Collecting pandas\n",
    "  Downloading pandas-1.1.2-cp38-cp38-manylinux1_x86_64.whl (10.4 MB)\n",
    "allCollecting numpy>=1.15.4\n",
    "  Downloading numpy-1.19.2-cp38-cp38-manylinux2010_x86_64.whl (14.5 MB)\n",
    "Collecting pytz>=2017.2\n",
    "  Downloading pytz-2020.1-py2.py3-none-any.whl (510 kB)\n",
    "Collecting python-dateutil>=2.7.3\n",
    "  Downloading python_dateutil-2.8.1-py2.py3-none-any.whl (227 kB)\n",
    "Collecting six>=1.5\n",
    "  Downloading six-1.15.0-py2.py3-none-any.whl (10 kB)\n",
    "Installing collected packages: numpy, pytz, six, python-dateutil, pandas\n",
    "\n",
    "Successfully installed numpy-1.19.2 pandas-1.1.2 python-dateutil-2.8.1 pytz-2020.1 six-1.15.0\n",
    "Removing intermediate container e8294cc32e0e\n",
    " ---> 2789cc540105\n",
    "Step 5/7 : EXPOSE 80\n",
    " ---> Running in ce14e3c5e597\n",
    "Removing intermediate container ce14e3c5e597\n",
    " ---> ca5e96e674f4\n",
    "Step 6/7 : ENV NAME World\n",
    " ---> Running in 780f50f9ade5\n",
    "Removing intermediate container 780f50f9ade5\n",
    " ---> 2ef01705504e\n",
    "Step 7/7 : CMD [\"python\", \"app.py\"]\n",
    " ---> Running in 288edf90bb0b\n",
    "Removing intermediate container 288edf90bb0b\n",
    " ---> 9afd35ac54b7\n",
    "Successfully built 9afd35ac54b7\n",
    "Successfully tagged tacoworld:docker_demo\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "note the presence of a bunch of lines like\n",
    "\n",
    "```\n",
    "---> f345411c943e\n",
    "```\n",
    "\n",
    "after each command. `docker` is building our desired image by stepping through the `Dockerfile` command by command. the result of each command is then **cached** as a layer -- `docker` will now remember that if we *start* with the image `python:3.8-slim` and then the first command we run is `WORKDIR /app`, it has already built something that looks like that and doesn't have to rebuild it from scratch."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "check out the `image` list again:\n",
    "\n",
    "```sh\n",
    "sudo docker image ls --all\n",
    "```\n",
    "\n",
    "this list will now contain the `hello-world`, `python`, `ubuntu`, and `tacoworld` images we have explicitly `run`, as well as many `<none>` images.\n",
    "\n",
    "these `<none>` images are the **cached** layers -- images that were built on the way to having the final `tacoworld` image. if you check the lines `---> f345411c943e` in your output, they will be the values in the `IMAGE ID` column"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "I should also verify that I have the ability to run this code as built. I can do that using the image name I just gave my image (`tacoworld:docker_demo`):\n",
    "\n",
    "```sh\n",
    "sudo docker run --rm tacoworld:docker_demo\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "```\n",
    "HELLO World\n",
    "my name is 921e4f8c18dd\n",
    "these are the results of the tacoworld (tm) model\n",
    "----------------------\n",
    "\n",
    "I, Zach Lamberty, want tacos more than *anyone*, especially more than Eamon!\n",
    "I, Eamon Lamberty, want tacos, so it's good there are enough to share!\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "so to recap:\n",
    "\n",
    "1. I created a `Dockerfile` that specified how to go from a parent image to my complete, working application\n",
    "1. in the `Dockerfile` directory I used `docker build` to create an `image` based on that `Dockerfile` \"recipe\"\n",
    "1. I used `docker run` to turn that `image` I created into a working `container`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "I could share this with my be-`windows`ed coworker in two ways:\n",
    "\n",
    "1. I give them the *files* via `github` and tell them the commands to run (e.g. those in the `README.md`) to build their own local `image`\n",
    "1. I could `docker push` the `image` to `dockerhub` and they could `docker pull` that image locally (no need to build)\n",
    "\n",
    "what are the advantages and disadvantages of those two approaches? when might I explicitly need to use one or the other?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "**<div align=\"center\">PAUSE FOR ZOOM BREAK</div>**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## okay but really *WHY*\n",
    "\n",
    "perhaps this seemed like a lot of effort to go through to get a simple `python` application that *already worked* to start working *in a different place*, and you'd be right. we have definitely gone way out of our way if our goal was to just get our application working *somewhere*.\n",
    "\n",
    "so why did we do it?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### repeatable, reliable delivery"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "what we bought with that extra effort was the ability to have our application work *anywhere* `docker` is installed, reliably, repeatably. I don't need to know what versions of any software are installed on my coworker's laptop (they don't need *any* of it installed, actually), they just need to have `docker` and be able to execute `docker run tacoworld:docker_demo` to run my model."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "this is **already** a great reason. across all the data science projects I've worked on, one of the most difficult portions is *delivery*: handing off something to someone else that they can actually run. `docker` greatly simplifies the delivery process (provided the client has and can use `docker`, which is becoming extremely common)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### leverage work others have already done for us"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "in addition to that, a large segment of the software development community is already using `docker` to deliver their projects -- this means that fairly often someone has already built a `docker` image with that-hot-new-thing-you-want-to-use-but-can't-install properly installed and configure, and all you have to know is how to run `docker pull`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "for example\n",
    "\n",
    "+ [tensorflow](https://hub.docker.com/r/tensorflow/tensorflow/)\n",
    "+ [pytorch](https://hub.docker.com/r/pytorch/pytorch/)\n",
    "+ [mxnet](https://hub.docker.com/r/mxnet/)\n",
    "+ [jupyter](https://hub.docker.com/u/jupyter/)\n",
    "+ pretty much every programming language\n",
    "+ pretty much [every single modern database technology](https://learn.g2crowd.com/best-docker-containers-repository)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### scalability and management\n",
    "\n",
    "this happens in an engineering layer that might be a little bit beyond your day to day work as a data scientist, but the way that applications and models are deployed is also increasingly dominated by `docker`. tools on all three cloud platforms (amazon `ecs`, google `kubernetes` engine, azure container or kubernetes service) help automate the process of deploying up-to-date versions of `docker` containers and scaling them up and down with demand"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "<div align=\"center\"><img src=\"https://thinkr.fr/wp-content/uploads/back-to-the-future-docker.jpg\" width=\"800px\"></div>\n",
    "\n",
    "# END OF LECTURE\n",
    "\n",
    "next lecture: [`REST` apps and web scraping](007_web_scraping.ipynb)"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "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.7.3"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}