The Technical Overview section gives you a high-level view of:
The goal of this section is to share a deeper technical understanding of JupyterHub and how it works.
JupyterHub is a set of processes that together provide a single user Jupyter
Notebook server for each person in a group. Three major subsystems are started
by the jupyterhub
command line program:
Users access JupyterHub through a web browser, by going to the IP address or the domain name of the server.
The basic principles of operation are:
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]
.
Different authenticators control access to JupyterHub. The default one (PAM) uses the user accounts on the server where JupyterHub is running. If you use this, you will need to create a user account on the system for each user on your team. Using other authenticators, you can allow users to sign in with e.g. a GitHub account, or with any single-sign-on system your organization has.
Next, spawners control how JupyterHub starts the individual notebook server for each user. The default spawner will start a notebook server on the same machine running under their system username. The other main option is to start each server in a separate container, often using Docker.
When a user accesses JupyterHub, the following events take place:
/user/[username]/*
to the single-user notebook server./hub/
, containing an encrypted token. (Prior to version
0.8, a cookie for /user/[username]
was used too.)/user/[username]
, and the request is handled by
the single-user notebook server.The single-user server identifies the user with the Hub via OAuth:
/hub/login
By default, the Proxy listens on all public interfaces on port 8000. Thus you can reach JupyterHub through either:
http://localhost:8000
In their default configuration, the other services, the Hub and Single-User Notebook Servers, all communicate with each other on localhost only.
By default, starting JupyterHub will write two files to disk in the current working directory:
jupyterhub.sqlite
is the SQLite database containing all of the state of the
Hub. This file allows the Hub to remember which users are running and
where, as well as storing other information enabling you to restart parts of
JupyterHub separately. It is important to note that this database contains
no sensitive information other than Hub usernames.jupyterhub_cookie_secret
is the encryption key used for securing cookies.
This file needs to persist so that a Hub server restart will avoid
invalidating cookies. Conversely, deleting this file and restarting the server
effectively invalidates all login cookies. The cookie secret file is discussed
in the Cookie Secret section of the Security Settings document.The location of these files can be specified via configuration settings. It is
recommended that these files be stored in standard UNIX filesystem locations,
such as /etc/jupyterhub
for all configuration files and /srv/jupyterhub
for
all security and runtime files.
There are two basic extension points for JupyterHub:
Each is governed by a customizable class, and JupyterHub ships with basic defaults for each.
To enable custom authentication and/or spawning, subclass Authenticator
or
Spawner
, and override the relevant methods.