Technical Overview |Prerequisites |Authenticator setup |Build the JupyterHub Docker image |Spawner: Prepare the Jupyter Notebook Image |Run JupyterHub |Behind the scenes |FAQ

jupyterhub-deploy-docker

jupyterhub-deploy-docker provides a referencedeployment of JupyterHub, amulti-user Jupyter Notebook environment, on asingle host using Docker.

Possible use cases include:

• Creating a JupyterHub demo environment that you can spin up relativelyquickly.
• Providing a multi-user Jupyter Notebook environment for small classes,teams, or departments.

Disclaimer

This deployment is NOT intended for a production environment.It is a reference implementation that does not meet traditionalrequirements in terms of availability nor scalability.

If you are looking for a more robust solution to host JupyterHub, oryou require scaling beyond a single host, please check out theexcellent zero-to-jupyterhub-k8sproject.

Technical Overview

Key components of this reference deployment are:

• Host: Runs the JupyterHub componentsin a Docker container on the host.

• Authenticator: Uses OAuthenticatorand GitHub OAuth toauthenticate users.

• Spawner:Uses DockerSpawnerto spawn single-user Jupyter Notebook servers in separate Dockercontainers on the same host.

• Persistence of Hub data: Persists JupyterHub data in a Dockervolume on the host.

• Persistence of user notebook directories: Persists user notebookdirectories in Docker volumes on the host.

Prerequisites

Docker

This deployment uses Docker, via Docker Compose, for all the things.Docker Engine 1.12.0 or higher isrequired.

1. Use Docker's installation instructionsto set up Docker for your environment.

2. To verify your docker installation, whether running docker as a localinstallation or using docker-machine,enter these commands:

   docker version
   docker ps

HTTPS and SSL/TLS certificate

This deployment configures JupyterHub to use HTTPS. You must provide acertificate and key file in the JupyterHub configuration. To configure:

1. Obtain the domain name that you wish to use for JupyterHub, forexample, myfavoritesite.com or jupiterplanet.org.

2. If you do not have an existing certificate and key, you can:

   • obtain one from Let's Encrypt usingthe certbot client,
   • use the helper script in this repo's letsencrypt example, or
   • create a self-signed certificate.

3. Copy the certificate and key files to adirectory named secrets in this repository's root directory. These will beadded to the JupyterHub Docker image at build time. For example, create asecrets directory in the root of this repo and copy the certificate andkey files (jupyterhub.crt and jupyterhub.key) to this directory:

   mkdir -p secrets
   cp jupyterhub.crt jupyterhub.key secrets/

Authenticator setup

This deployment uses GitHub OAuth to authenticate users.

It requires that you create and register a GitHub OAuth applicationby filling out a form on the GitHub site:

In this form, you will specify the OAuth application's callback URL inthis format: https://<myhost.mydomain>/hub/oauth_callback.

After you submit the GitHub form, GitHub registers your OAuth application andassigns a unique Client ID and Client Secret. The Client Secret should bekept private.

At JupyterHub's runtime, you must pass the GitHub OAuth Client ID, ClientSecret and OAuth callback url. You can do this by either:

• setting the GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, andOAUTH_CALLBACK_URL environment variables when you run theJupyterHub container, or

• add them to an oauth.env file in the secrets directory of this repository.You may need to create both the secrets directory and the oauth.env file.For example, add the following lines in the oauth.env file:

  oauth.env file

  GITHUB_CLIENT_ID=<github_client_id>
  GITHUB_CLIENT_SECRET=<github_client_secret>
  OAUTH_CALLBACK_URL=https://<myhost.mydomain>/hub/oauth_callback
  

  Note: The oauth.env file is a special file that Docker Compose usesto lookup environment variables. If you choose to place the GitHubOAuth application settings in this file, you should make sure that thefile remains private (be careful to not commit the oauth.env file withthese secrets to source control).

Build the JupyterHub Docker image

Finish configuring JupyterHub and then build the hub's Docker image. (We'llbuild the Jupyter Notebook image in the next section.)

1. Configure userlist: Create a userlist file of authorized JupyterHubusers. The list should contain GitHub usernames, and this file shoulddesignate at least one admin user. For instance, the example file belowcontains three users, jtyberg, jenny, and guido, and one designatedadministrator, jtyberg:

   userlist file

   jtyberg admin
   jenny
   guido
   

   The admin user will have the ability to add more users through JupyterHub'sadmin console.

2. Use docker-compose to buildthe JupyterHub Docker image on the active Docker machine host by runningthe make build command:

   make build

Spawner: Prepare the Jupyter Notebook Image

You can configure JupyterHub to spawn Notebook servers from any Docker image, aslong as the image's ENTRYPOINT and/or CMD starts a single-user instance ofJupyter Notebook server that is compatible with JupyterHub.

To specify which Notebook image to spawn for users, you set the value of the
DOCKER_NOTEBOOK_IMAGE environment variable to the desired container image.You can set this variable in the .env file, or alternatively, you canoverride the value in this file by setting DOCKER_NOTEBOOK_IMAGE in theenvironment where you launch JupyterHub.

Whether you build a custom Notebook image or pull an image from a public orprivate Docker registry, the image must reside on the host.

If the Notebook image does not exist on host, Docker will attempt to pull theimage the first time a user attempts to start his or her server. In such cases,JupyterHub may timeout if the image being pulled is large, so it is better topull the image to the host before running JupyterHub.

This deployment defaults to thejupyter/scipy-notebookNotebook image, which is built from the scipy-notebookDocker stacks. (Note that the Dockerstacks *-notebook images tagged 2d878db5cbff include thestart-singleuser.sh script required to start a single-user instance of theNotebook server that is compatible with JupyterHub).

You can pull the image using the following command:

make notebook_image

Run JupyterHub

Run the JupyterHub container on the host.

To run the JupyterHub container in detached mode:

docker-compose up -d

Once the container is running, you should be able to access the JupyterHub console at

file

https://myhost.mydomain

To bring down the JupyterHub container:

docker-compose down

Behind the scenes

make build does a few things behind the scenes, to set up the environment for JupyterHub:

Create a JupyterHub Data Volume

Create a Docker volume to persist JupyterHub data. This volume will reside on the host machine. Using a volume allows user lists, cookies, etc., to persist across JupyterHub container restarts.

docker volume create --name jupyterhub-data

Create a Docker Network

Create a Docker network for inter-container communication. The benefits of using a Docker network are:

• container isolation - only the containers on the network can access one another
• name resolution - Docker daemon runs an embedded DNS server to provide automatic service discovery for containers connected to user-defined networks. This allows us to access containers on the same network by name.

Here we create a Docker network named jupyterhub-network. Later, we will configure the JupyterHub and single-user Jupyter Notebook containers to run attached to this network.

docker network create jupyterhub-network

FAQ

How can I view the logs for JupyterHub or users' Notebook servers?

Use docker logs <container>. For example, to view the logs of the jupyterhub container

docker logs jupyterhub

How do I specify the Notebook server image to spawn for users?

In this deployment, JupyterHub uses DockerSpawner to spawn single-userNotebook servers. You set the desired Notebook server image in aDOCKER_NOTEBOOK_IMAGE environment variable.

JupyterHub reads the Notebook image name from jupyterhub_config.py, whichreads the Notebook image name from the DOCKER_NOTEBOOK_IMAGE environmentvariable:

# DockerSpawner setting in jupyterhub_config.py
c.DockerSpawner.container_image = os.environ['DOCKER_NOTEBOOK_IMAGE']

By default, theDOCKER_NOTEBOOK_IMAGE environment variable is set in the.env file.

file

# Setting in the .env file
DOCKER_NOTEBOOK_IMAGE=jupyter/scipy-notebook:2d878db5cbff

To use a different notebook server image, you can either change the desiredcontainer image value in the .env file, or you can override itby setting the DOCKER_NOTEBOOK_IMAGE variable to a different Notebookimage in the environment where you launch JupyterHub. For example, thefollowing setting would be used to spawn single-user pyspark notebook servers:

export DOCKER_NOTEBOOK_IMAGE=jupyterhub/pyspark-notebook:2d878db5cbff

docker-compose up -d

If I change the name of the Notebook server image to spawn, do I need to restart JupyterHub?

Yes. JupyterHub reads its configuration which includes the container imagename for DockerSpawner. JupyterHub uses this configuration to determine theNotebook server image to spawn during startup.

If you change DockerSpawner's name of the Docker image to spawn, you willneed to restart the JupyterHub container for changes to occur.

In this reference deployment, cookies are persisted to a Docker volume on theHub's host. Restarting JupyterHub might cause a temporary blip in userservice as the JupyterHub container restarts. Users will not have to loginagain to their individual notebook servers. However, users may need torefresh their browser to re-establish connections to the running Notebookkernels.

How can I backup a user's notebook directory?

There are multiple ways to backup and restore data in Docker containers.

Suppose you have the following running containers:

docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Names}}"

    CONTAINER ID        IMAGE                    NAMES
    bc02dd6bb91b        jupyter/minimal-notebook jupyter-jtyberg
    7b48a0b33389        jupyterhub               jupyterhub

In this deployment, the user's notebook directories (/home/jovyan/work) are backed by Docker volumes.

docker inspect -f '{{ .Mounts }}' jupyter-jtyberg

    [{jtyberg /var/lib/docker/volumes/jtyberg/_data /home/jovyan/work local rw true rprivate}]

We can backup the user's notebook directory by running a separate container that mounts the user's volume and creates a tarball of the directory.

docker run --rm \
  -u root \
  -v /tmp:/backups \
  -v jtyberg:/notebooks \
  jupyter/minimal-notebook \
  tar cvf /backups/jtyberg-backup.tar /notebooks

The above command creates a tarball in the /tmp directory on the host.