DOCSEARCHbyAlgolia
Submit Docs

DockerSpawner

repository·main·Indexed 20 days ago

https://github.com/jupyterhub/dockerspawner

A custom spawner for JupyterHub that enables the management and launching of single-user notebook servers within Docker containers or Docker Swarm services. The package provides DockerSpawner for standalone containers, SwarmSpawner for Docker Swarm mode services, and SystemUserSpawner for servers corresponding to existing system users. It supports custom Docker image selection via options_form, internal SSL encryption, and integration with GitHub OAuth.

Tokens
10.5K
Snippets
41
Records
58
Agent score
69%

What's inside dockerspawner

  1. Overview of DockerSpawner spawner types

    main

    DockerSpawner enables JupyterHub to spawn single-user notebook servers within Docker containers. Depending on your infrastructure and deployment needs, you can choose from three primary spawner types:

    • DockerSpawner: The standard option that takes an authenticated user and spawns a notebook server in a dedicated Docker container.
    • SwarmSpawner: Used for orchestrating notebook servers as services within a Docker Swarm mode cluster.
    • SystemUserSpawner: Spawns notebook servers that correspond to existing system users.

  2. Understand the types of spawners in dockerspawner

    main

    The dockerspawner package provides three distinct spawner types depending on your deployment architecture:

    • DockerSpawner: The standard spawner that takes an authenticated user and spawns a notebook server in a standalone Docker container.
    • SwarmSpawner: Launches single-user notebook servers as Docker Swarm mode services.
    • SystemUserSpawner: Spawns single-user notebook servers that correspond to existing system users.

  3. Use SystemUserSpawner for local system user management

    main
    The SystemUserSpawner class is used when you want to spawn single-user servers as local system users on the host machine rather than in isolated containers. This is typically used in simpler deployments where the JupyterHub process and the user processes share the same operating system environment.

  4. Use DockerSpawner to spawn JupyterHub single-user servers in Docker containers

    main

    The DockerSpawner class is the primary interface for spawning JupyterHub single-user servers as individual Docker containers. It is highly configurable via JupyterHub configuration, allowing you to define container images, network settings, volume mounts, and environment variables. When used, JupyterHub will communicate with the Docker daemon to pull images and manage the lifecycle of the containers.

    # Example conceptual usage in jupyterhub_config.py
c.DockerSpawner.image = 'jupyter/base-notebook:latest'

  5. Use SwarmSpawner to spawn JupyterHub single-user servers in Docker Swarm services

    main
    The SwarmSpawner class is designed for environments running Docker Swarm. Instead of managing individual containers directly via the Docker daemon, it leverages Docker Swarm's orchestration capabilities to deploy single-user servers as services across a Swarm cluster. This is suitable for scaling JupyterHub deployments across multiple nodes.

  6. Choose the appropriate spawner type

    main

    The dockerspawner package provides three main spawner types depending on your deployment architecture:

    • DockerSpawner: The recommended choice for most users. It spawns single-user notebook servers as individual Docker containers on the fly.
    • SwarmSpawner: Used when running JupyterHub in Docker Swarm mode. It launches notebook servers as Swarm services rather than individual containers, allowing notebook containers to be distributed across multiple servers in a Swarm cluster.
    • SystemUserSpawner: Used when notebook servers must correspond to existing system users. This is ideal if you want containers to access existing host user home directories or if you use external services (like nbgrader) that rely on specific Unix user ownership and permissions.

  7. Production requirements for JupyterHub in Docker

    main

    The simple example provided in this repository is intended for testing only. For a real-world deployment, you should implement the following:

    • Persistence: Mount a volume or use a database to store the Hub state.
    • User Data: Mount volumes for user storage to prevent data loss when containers are shut down.
    • Authentication: Replace the dummy authenticator with a real authentication provider.
    • Proxy Isolation: Run the proxy in a separate container so that reloading the Hub configuration does not disrupt active user sessions.

    For a complete implementation of these requirements, refer to jupyterhub-deploy-docker.

  8. Requirements for building a custom JupyterHub user image

    main

    If you are building your own Docker image to be used as a single-user server in JupyterHub, the image must satisfy these four requirements:

    1. Python version: Must have Python >= 3.6.
    2. JupyterHub compatibility: The version of jupyterhub installed in the image must match the version of JupyterHub running your Hub deployment.
    3. Jupyter package: Must have the Jupyter notebook package installed.
    4. Startup command: The image's CMD must launch jupyterhub-singleuser or jupyter-labhub. Alternatively, you can use the c.Spawner.cmd configuration in JupyterHub to specify the launch command.

  9. Allow users to select custom Docker images via an options_form

    main

    You can allow users to choose their own environment (e.g., a specific Docker image) during the login process by implementing an options_form. This requires three specific steps in your Spawner configuration:

    1. Enable an options_form: Provide either a raw HTML snippet or a callable that accepts the Spawner instance and returns an HTML form. Ensure you use Bootstrap classes like form-control for proper styling.
    2. Implement Spawner.options_from_form(formdata): This method must transform the incoming formdata (which is always a dictionary of lists of strings, e.g., {"image": ["my-image-name"]}) into the internal dictionary structure your Spawner expects.
    3. Implement Spawner.load_user_options(options): This method takes the dictionary returned by options_from_form and applies those settings to the Spawner instance (for example, by setting self.image).
    # To run the provided example in this directory:
jupyterhub

  11. Deploy JupyterHub with internal SSL using Docker Compose

    main

    This example demonstrates how to deploy JupyterHub with total internal encryption using the internal_ssl configuration introduced in JupyterHub 1.0.

    DockerSpawner supports this by implementing the .move_certs method, which handles the necessary certificate movement for internal communication between JupyterHub and the spawned containers. This specific setup uses configurable-http-proxy and provides a docker-compose configuration to automate the deployment.

    Note: This setup uses a dummy authenticator, allowing you to log in with any username and password.

    # 1. Create the required network and volumes
docker network create jupyterhub
docker volume create jupyterhub-ssl
docker volume create jupyterhub-data

# 2. Build and start the deployment
docker compose build
docker compose up