JupyterHub

JupyterHub is the best way to serve Jupyter notebook for multiple users. Because JupyterHub manages a separate Jupyter environment for each user, it can be used in a class of students, a corporate data science group, or a scientific research group. It is a multi-user Hub that spawns, manages, and proxies multiple instances of the single-user Jupyter notebook server.

JupyterHub offers distributions for different use cases. As of now, you can find two main cases:

1. The Littlest JupyterHub distribution is suitable if you need a small number of users (1-100) and a single server with a simple environment.

2. Zero to JupyterHub with Kubernetes allows you to deploy dynamic servers on the cloud if you need even more users.

JupyterHub can be used in a collaborative environment by both both small (0-100 users) and large teams (more than 100 users) such as a class of students, corporate data science group or scientific research group. It has distributions which are developed to serve the needs of each of these teams respectively.

JupyterHub is made up of four subsystems:

• a Hub (tornado process) that is the heart of JupyterHub

• a configurable http proxy (node-http-proxy) that receives the requests from the client’s browser

• multiple single-user Jupyter notebook servers (Python/IPython/tornado) that are monitored by Spawners

• an authentication class that manages how users can access the system

Additionally, optional configurations can be added through a config.py file and manage users kernels on an admin panel. A simplification of the whole system is displayed in the figure below:

JupyterHub performs the following functions:

• The Hub launches a proxy

• The proxy forwards all requests to the Hub by default

• The Hub handles user login and spawns single-user servers on demand

• The Hub configures the proxy to forward URL prefixes to the single-user notebook servers

For convenient administration of the Hub, its users, and services, JupyterHub also provides a REST API.

The JupyterHub team and Project Jupyter value our community, and JupyterHub follows the Jupyter Community Guides.

Contents

Distributions

A JupyterHub distribution is tailored towards a particular set of use cases. These are generally easier to set up than setting up JupyterHub from scratch, assuming they fit your use case.

Today, you can find two main use cases:

1. If you need a simple case for a small amount of users (0-100) and single server take a look at The Littlest JupyterHub distribution.

2. If you need to allow for a larger number of machines and users, a dynamic amount of servers can be used on a cloud, take a look at the Zero to JupyterHub with Kubernetes distribution. This distribution runs JupyterHub on top of Kubernetes.

It is important to evaluate these distributions before you can continue with the configuration of JupyterHub.

Installation Guide

• Installation
  • Quickstart
  • Install JupyterHub with Docker
  • Installation Basics

Getting Started

• Get Started
  • Configuration Basics
  • Networking basics
  • Security settings
  • Authentication and User Basics
  • Spawners and single-user notebook servers
  • External services
  • Frequently asked questions
  • Institutional FAQ

Technical Reference

• Technical Reference
  • Technical Overview
  • JupyterHub URL scheme
  • Security Overview
  • Authenticators
  • Spawners
  • Services
  • Writing a custom Proxy implementation
  • Running proxy separately from the hub
  • Using JupyterHub’s REST API
  • JupyterHub REST API
  • Starting servers with the JupyterHub API
  • Monitoring
  • The Hub’s Database
  • Working with templates and UI
  • Deploying JupyterHub in “API only mode”
  • Event logging and telemetry
  • Configuring user environments
  • Configuration examples
  • Configure GitHub OAuth
  • Using a reverse proxy
  • Run JupyterHub without root privileges using sudo
  • Configuration Reference
  • JupyterHub and OAuth

Administrators guide

• Administrator’s Guide
  • Troubleshooting
  • Capacity planning
  • Upgrading JupyterHub
  • Interpreting common log messages
  • Changelog

API Reference

• JupyterHub API
  • Application configuration
  • Authenticators
  • Spawners
  • Proxies
  • Users
  • Services
  • Services Authentication

RBAC Reference

• JupyterHub RBAC
  • Motivation
  • Definitions
  • Technical Overview

Contributing

We welcome you to contribute to JupyterHub in ways that are most exciting & useful to you. We value documentation, testing, bug reporting & code equally and are glad to have your contributions in whatever form you wish :)

Our Code of Conduct and reporting guidelines help keep our community welcoming to as many people as possible.

• Contributing
  • Community communication channels
  • Setting up a development install
  • Contributing Documentation
  • Testing JupyterHub and linting code
  • The JupyterHub roadmap
  • Reporting security issues in Jupyter or JupyterHub

About JupyterHub

• About
  • Contributors
  • Changelog
  • A Gallery of JupyterHub Deployments

Indices and tables

• Index

• Module Index

Questions? Suggestions?

All questions and suggestions are welcome. Please feel free to use our Jupyter Discourse Forum to contact our team.

Looking forward to hearing from you!