Running a Jupyter Notebook Server Using Docker

Posted on Wed 04 October 2017 in Jupyter Notebook

Run a Jupyter Notebook Server Using Docker

Project Jupyter maintains a set of Docker images defining a suite of Jupyter Notebook servers provisioned for a variety of tasks. The definitions for these images can be found at the GitHub repository jupyter/docker-stacks.

This repo provides eight notebook images starting with a base-notebook image.

  1. base-notebook
  2. minimal-notebook
  3. scipy-notebook
  4. r-notebook
  5. tensorflow-notebook
  6. datascience-notebook
  7. pyspark-notebook
  8. all-spark-notebook

All subsequent images depend on the base-notebook as shown in this diagram:

Each image has a folder in GitHub jupyter/docker-stacks and an equivalent repository hosted under the jupyter user namespace on Docker Hub.

Recommended Best Practice for Running a Jupyter Notebook Server with Docker

We recommend the following command as a best practice for running a Jupyter Notebook Server, here with the jupyter/scipy-notebook image:

$ docker run -d --name jupyter -p 8888:8888 -v `pwd`:/home/jovyan jupyter/scipy-notebook

This command makes us of docker run a command which instructs the Docker daemon to run a new container defined by the image jupyter/scipy-notebook. We also use four flags to define how we will run the image.

The -d flag stands for 'detached' but we can also think of it as 'daemon'. This flag instructs Docker to run the container as a detached process in the background.

The --name flag instructs Docker to give the container a specific name. In this case, we are telling Docker to name the container jupyter. Note that container names must be unique. This means that if you have a stopped container with the name jupyter you will not be able to start another container with the same name until you remove the stopped container.

The -p flag instructs Docker to attach a port on the container to a specifc port on host system. The syntax is -p <host_port>:<container_port>. You will only be able to attach a single process to a give port on the host system. A common error seen is in trying to attach an container to a port on which another container is running.

The -v flag attaches a two-way link to a volume between the container and your host system. This flag follows a similar pattern where the syntax is -v <home_dir>:<container_dir>.

Note that we are making use of bash’s inline execution functionality via two backticks. Executing pwd prints your working directory (your current location). Running this in backticks substitutes your working directory in place. If your working directory was /Users/joshuacook/src/ then running

docker run -v `pwd`:/home/jovyan jupyter/scipy-notebook

is equivalent to running

docker run -v /Users/joshuacook/src:/home/jovyan jupyter/scipy-notebook