Repository files navigation

jupyterhub-deploy-docker provides a referencedeployment ofJupyterHub, amulti-userJupyter Notebook environment, on asingle host usingDocker.

Possibleuse 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.

This deployment isNOT intended for a production environment.It is a reference implementation that does not meet traditionalrequirements in terms of availability, scalability, or security.

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

Key components of this reference deployment are:

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

• Authenticator: UsesNative Authenticator to authenticate users.Any user will be allowed to sign up.

• Spawner: UsesDockerSpawnerto 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.

This deployment uses Docker, viaDocker Compose, for all the things.

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

This deployment usesJupyterHub Native Authenticator to authenticate users.

1. An singleadmin user will be enabled by default. Any user will be allowed to sign up.

1. Usedocker compose to buildthe JupyterHub Docker image:

   docker compose build

You can configure JupyterHub to spawn Notebook servers from any Docker image, aslong as the image'sENTRYPOINT and/orCMD 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 theDOCKER_NOTEBOOK_IMAGE environment variable to the desired container image.

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 the 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 thequay.io/jupyter/base-notebookNotebook image, which is built from thebase-notebookDocker stacks.

You can pull the image using the following command:

docker pull quay.io/jupyter/base-notebook:latest

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 athttp://localhost:8000.

To bring down the JupyterHub container:

docker compose down

Usedocker logs <container>. For example, to view the logs of thejupyterhub container

docker logs jupyterhub

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 fromjupyterhub_config.py, whichreads the Notebook image name from theDOCKER_NOTEBOOK_IMAGE environmentvariable:

# DockerSpawner setting in jupyterhub_config.pyc.DockerSpawner.image=os.environ['DOCKER_NOTEBOOK_IMAGE']

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.

There are multiple ways toBack up 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        quay.io/jupyter/minimal-notebook jupyter-jtyberg    7b48a0b33389        quay.io/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/worklocal rwtrue rprivate}]

We can back up 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 \  quay.io/jupyter/minimal-notebook \  tar cvf /backups/jtyberg-backup.tar /notebooks

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