JupyterHub is a multi-user server that manages and proxies multiple instances of the single-user Jupyter notebook server.
There are three basic processes involved:
The proxy is the only process that listens on a public interface.
The Hub sits behind the proxy at /hub
.
Single-user servers sit behind the proxy at /user/[username]
.
When a new browser logs in to JupyterHub, the following events take place:
/user/[username]/*
to the single-user server/hub/
and another for /user/[username]
,
containing an encrypted token./user/[username]
, which is handled by the single-user serverLogging into a single-user server is authenticated via the Hub:
/hub/login
There are two basic extension points for JupyterHub: How users are authenticated, and how their server processes are started. Each is governed by a customizable class, and JupyterHub ships with just the most basic version of each.
To enable custom authentication and/or spawning, subclass Authenticator or Spawner, and override the relevant methods.
Authentication is customizable via the Authenticator class. Authentication can be replaced by any mechanism, such as OAuth, Kerberos, etc.
JupyterHub only ships with PAM authentication,
which requires the server to be run as root,
or at least with access to the PAM service,
which regular users typically do not have
(on Ubuntu, this requires being added to the shadow
group).
More info on custom Authenticators.
See a list of custom Authenticators on the wiki.
Each single-user server is started by a Spawner. The Spawner represents an abstract interface to a process, and needs to be able to take three actions:
See a list of custom Spawners on the wiki.