Docker-Instructions.rst

Install Docker

Docker enables you to create "containers" which provide consistent environments in which to run your code. This way, you can run the software you write on different machines (e.g. your laptop vs the computing cluster) without having to spend too much time worrying about adapting it.

We're going to just be using some very basic features of Docker, so if you'd like to learn more refer to this page.

Windows 10

Detailed installation instructions are available here. For our purposes, you can simply:

1. Download the installer.

2. Double click on the installer and follow the prompts (keeping all options as defaults is fine).

3. Open a shell (e.g. cmd.exe) and trying running the test example:

   docker run hello-world
   

Windows 7 and Windows 8

Detailed installation instructions are available here. Be warned, however, that some people at IHME with older Lenovo laptops have had trouble getting them to work.

Mac OSX

Detailed installation instructions are available here. For our purposes, you can simply:

1. Download the installer.

2. Double click on the installer and drag Docker.app into your Applications folder.

3. Double click on Docker.app to start Docker.

4. Open a shell (e.g. terminal.app) and trying running the test example:

   docker run hello-world
   

Unix/Linux

¯\_(ツ)_/¯

Install Anaconda

Anaconda is a software package for Python (and R and sometimes C...) that handles the installation of common Python packages for you, making it easier to create and manage portable environments. We'll be using it inside of Docker to ensure that everyone is running under the same environment. See this page for more on how Docker and Anaconda fit together.

1. Get the latest Anaconda for Python 3 image:

   docker pull continuumio/anaconda3
   

2. Test that your installation worked:

   docker run continuumio/anaconda3 /opt/conda/bin/conda info
   

Running Jupyter Notebooks via Docker

1. You can fire up a notebook using the following command:

   docker run -it -p 8888:8888 -v ~/repos/ihme-python-course/:/home/ihme-python-course/ continuumio/anaconda3 /opt/conda/bin/jupyter notebook --ip='*' --no-browser --notebook-dir=/home/ihme-python-course/
   

   What do all of these arguments mean?

   Argument	Value	Description
   -it		Run the Docker container interactively
   -p	8888:8888	Map the 8888 port of the Docker container to the local port so that you can connect to it via your web browser
   -v	~/repos/ihme-python-course/:/home/ihme-python-course/	Maps <host directory>:<container directory> so that the repo you've downloaded is visible to the container
   continuumio/anaconda3		The name of the Docker container to be run
   /opt/conda/bin/jupyter		The program to execute inside of the container (Jupyter)
   notebook		This tells Jupyter to start a Notebook server
   --ip	'*'	Configures Jupyter to respond to any user that can connect to the container
   --no-browser		Prevents Jupyter from trying to automatically launch a web browser, since the Docker container does not have one
   --notebook-dir	/home/ihme-python-course/	Sets the root directory for the Jupyter server to the same one mapped under -v

   If you've followed all of the directions above exactly, you shouldn't need to edit any of these right now. If you've saved into a non-standard location, you may need to change the first part of your -v argument.

   There are many more options you can specify. See the corresponding Docker and Jupyter documentation.

2. Navigate to localhost:8888 in your web browser. You should see a listing of the files and directories inside this repo.