Prerequisites | Installation | Configuration | Building the Docker images | Contributing | License | Getting help
DockerSpawner enables JupyterHub to spawn single user notebook servers in Docker containers.
JupyterHub 0.7 or above is required, which also means Python 3.3 or above.
Install dockerspawner to the system:
pip install dockerspawnerThree basic types of spawners are available for dockerspawner:
-
DockerSpawner: useful if you would like to spawn single user notebook servers on the fly. It will take an authenticated user and spawn a notebook server in a Docker container for the user.
-
SwarmSpawner: same behavior as DockerSpawner, but launches single user notebook servers as Docker Swarm mode services instead of as individual containers. This allows for running JupyerHub in a swarm so that notebook containers can be run on any of multiple servers.
-
SystemUserSpawner: useful if you would like to spawn single user notebook servers that correspond to the system's users.
In most cases, we recommend using DockerSpawner. Use cases where you may wish to use SystemUserSpawner are:
- You are using docker just for environment management, but are running on a system where the users already have accounts and files they should be able to access from within the container. For example, you wish to use the system users and user home directories that already exist on a system.
- You are using an external service, such as nbgrader, that relies on distinct unix user ownership and permissions.
If neither of those cases applies, DockerSpawner is probably the right choice.
Tell JupyterHub to use DockerSpawner by adding the following line to
your jupyterhub_config.py:
c.JupyterHub.spawner_class = 'dockerspawner.DockerSpawner'There is a complete example in examples/oauth for using GitHub OAuth to authenticate users, and spawn containers with docker.
Tell JupyterHub to use SwarmSpawner by adding the following line to
your jupyterhub_config.py:
c.JupyterHub.spawner_class = 'dockerspawner.SwarmSpawner'You need to make sure that the JupyterHub process is launched on a Swarm manager
node, since its node needs to have permission to launch new Swarm services. It also
needs to have the docker socket mounted (like DockerSpawner) to communicate out of its
own container with the host's docker server. You can accomplish this in your
docker-compose.yml with the following settings:
jupyterhub:
image: jupyterhub/jupyterhub
# This is necessary to prevent the singleton hub from using its service number as its hostname
hostname: jupyterhub
# Permit communication with the host's docker server
volumes:
- "/var/run/docker.sock:/var/run/docker.sock"
# Ensure Hub and Notebook servers are on the same network
networks:
- jupyterhub_network
environment:
DOCKER_NETWORK_NAME: jupyterhub_network
# Ensure that we execute on a Swarm manager
deploy:
replicas: 1
placement:
constraints:
- node.role == managerYou'll also need to ensure that the JupyterHub service and the launched single-user services all run on the same Swarm overlay network. You can create one easily using:
docker network create --driver overlay jupyterhub_network
Then use this network in your jupyterhub_config.py like the following example:
network_name = os.environ['DOCKER_NETWORK_NAME']
c.SwarmSpawner.network_name = network_name
c.SwarmSpawner.extra_host_config = {'network_mode': network_name}Unless otherwise noted, SwarmSpawner supports the same configuration options as DockerSpawner.
If you want to spawn notebook servers for users that correspond to system users,
you can use the SystemUserSpawner instead. Add the following to your
jupyterhub_config.py:
c.JupyterHub.spawner_class = 'dockerspawner.SystemUserSpawner'The SystemUserSpawner will also need to know where the user home directories
are on the host. By default, it expects them to be in /home/<username>, but if
you want to change this, you'll need to further modify the
jupyterhub_config.py. For example, the following will look for a user's home
directory on the host system at /volumes/user/<username>:
c.SystemUserSpawner.host_homedir_format_string = '/volumes/user/{username}'For a full example of how SystemUserSpawner is used, see the
compmodels-jupyterhub
repository (this additionally runs the JupyterHub server within a docker
container, and authenticates users using GitHub OAuth).
Note: This is the older Docker Swarm, which makes a swarm look like a single docker instance. For the newer Docker Swarm Mode, see SwarmSpawner. This used to be supported by cassinyio, but this repository has been deprecated.
Both DockerSpawner and SystemUserSpawner are compatible with
Docker Swarm when multiple system
nodes will be used in a cluster for JupyterHub. Simply add 0.0.0.0
to your jupyterhub_config.py file as the host_ip:
c.DockerSpawner.host_ip = "0.0.0.0"This will configure DockerSpawner and SystemUserSpawner to get
the container IP address and port number using the docker port
command.
With DockerSpawner, the user's home directory
is not persistent by default, so some configuration is required to do so unless
the directory is to be used with temporary or demonstration JupyterHub
deployments.
The simplest version of persistence to the host filesystem is to isolate users in the filesystem, but leave everything owned by the same 'actual' user with DockerSpawner. That is, using docker mounts to isolate user files, not ownership or permissions on the host.
Volume mapping for DockerSpawner in jupyterhub_config.py
is required configuration for persistence. To map volumes from
the host file/directory to the container (referred to as guest)
file/directory mount point, set the c.DockerSpawner.volumes to specify
the guest mount point (bind) for the volume.
If you use {username} in either the host or guest file/directory path,
username substitution will be done and {username} will be replaced with
the current user's name.
(Note: The jupyter/docker-stacks notebook images run the Notebook server as user
jovyan and set the user's notebook directory to /home/jovyan/work.)
# Explicitly set notebook directory because we'll be mounting a host volume to
# it. Most jupyter/docker-stacks *-notebook images run the Notebook server as
# user `jovyan`, and set the notebook directory to `/home/jovyan/work`.
# We follow the same convention.
notebook_dir = os.environ.get('DOCKER_NOTEBOOK_DIR') or '/home/jovyan/work'
c.DockerSpawner.notebook_dir = notebook_dir
# Mount the real user's Docker volume on the host to the notebook user's
# notebook directory in the container
c.DockerSpawner.volumes = { 'jupyterhub-user-{username}': notebook_dir }The jupyterhub-deploy-docker repo
contains a reference deployment that persists the notebook directory;
see its jupyterhub_config.py
for an example configuration.
See Docker documentation on data volumes for more information on data persistence.
If you have jupyterhub >= 0.7, you can set a memory limit for each user's container easily.
c.Spawner.mem_limit = '2G'
The value can either be an integer (bytes) or a string with a 'K', 'M', 'G' or 'T' prefix.
By default, DockerSpawner uses the jupyterhub/singleuser image
with the appropriate tag that pins the right version of JupyterHub.
Any of the existing Jupyter docker stacks
can be used with JupyterHub, provided that the version of JupyterHub in the image matches,
and are encouraged as the image of choice. Make sure to pick a tag!
c.DockerSpawner.image = 'jupyter/scipy-notebook:8f56e3c47fec'The docker-stacks are moving targets with always changing versions.
Since you need to make sure that JupyterHub in the image is compatible with JupyterHub,
always include the :hash tag part when specifying the image.
You can also build your own image. The only requirements for an image to be used with JupyterHub:
- it has Python >= 3.4
- it has JupyterHub
- it has the Jupyter
notebookpackage - CMD launches jupyterhub-singleuser OR the
c.Spawner.cmdconfiguration is used to do this.
For just about any starting image, you can make it work with JupyterHub by installing the appropriate JupyterHub version and the Jupyter notebook package.
For instance, from the docker-stacks, pin your JupyterHub version and you are done:
FROM jupyter/scipy-notebook:8f56e3c47fec
ARG JUPYTERHUB_VERSION=0.8.0
RUN pip3 install --no-cache \
jupyterhub==$JUPYTERHUB_VERSIONOr for the absolute minimal JupyterHub user image starting only from the base Python image:
FROM python:3.6
RUN pip3 install \
jupyterhub==0.7.2 \
'notebook>=5.0,<=6.0'
# create a user, since we don't want to run as root
RUN useradd -m jovyan
ENV HOME=/home/jovyan
WORKDIR $HOME
USER jovyan
CMD ["jupyterhub-singleuser"]This Dockerfile should work with just about any base image in the FROM line, provided it has Python 3 installed.
If you would like to contribute to the project, please read our
contributor documentation
and the CONTRIBUTING.md.
For a development install, clone the repository and then install from source:
git clone https://github.com/jupyterhub/dockerspaawner
cd dockerspawner
pip3 install -r dev-requirements.txt -e .We use a shared copyright model that enables all contributors to maintain the copyright on their contributions.
All code is licensed under the terms of the revised BSD license.
We encourage you to ask questions on the mailing list, and you may participate in development discussions or get live help on Gitter.
- Reporting Issues
- JupyterHub tutorial | Repo | Tutorial documentation
- Documentation for JupyterHub | PDF (latest) | PDF (stable)
- Documentation for JupyterHub's REST API