or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdconfiguration-utilities.mdcore-application.mddatabase-models.mdindex.mdmonitoring-metrics.mdrbac-permissions.mdrest-api.mdservices-oauth.mdsingleuser-integration.mdspawners.md
tile.json

tessl/pypi-jupyterhub

A multi-user server for Jupyter notebooks that provides authentication, spawning, and proxying for multiple users simultaneously

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/jupyterhub@5.3.x

To install, run

npx @tessl/cli install tessl/pypi-jupyterhub@5.3.0

index.mddocs/

JupyterHub

JupyterHub is a multi-user server for Jupyter notebooks that enables organizations to provide shared access to Jupyter notebook environments for multiple users simultaneously. It consists of three main components: a central Hub (tornado process) that manages authentication and user sessions, a configurable HTTP proxy that routes traffic, and multiple single-user Jupyter notebook servers that provide isolated computing environments for each user.

Package Information

  • Package Name: jupyterhub
  • Language: Python
  • Installation: pip install jupyterhub
  • Version: 5.3.0

Core Imports

# Main application class
from jupyterhub.app import JupyterHub

# Authentication system
from jupyterhub.auth import Authenticator, PAMAuthenticator, DummyAuthenticator

# Spawner system  
from jupyterhub.spawner import Spawner, LocalProcessSpawner

# Database models
from jupyterhub.orm import User, Server, Group, Role, Service

# Configuration utilities
from jupyterhub.utils import new_token, hash_token, url_path_join

Basic Usage

Starting JupyterHub

# Command line (most common)
# jupyterhub --config=/path/to/jupyterhub_config.py

# Programmatic usage
from jupyterhub.app import JupyterHub

# Create application instance
app = JupyterHub()
app.initialize()
app.start()

Basic Configuration

# jupyterhub_config.py
c = get_config()

# Basic settings
c.JupyterHub.ip = '0.0.0.0'
c.JupyterHub.port = 8000
c.JupyterHub.hub_ip = '127.0.0.1'

# Authentication
c.JupyterHub.authenticator_class = 'pam'  # or 'dummy' for testing

# Spawner
c.JupyterHub.spawner_class = 'localprocess'

# Admin users
c.Authenticator.admin_users = {'admin'}

# Database
c.JupyterHub.db_url = 'sqlite:///jupyterhub.sqlite'

Architecture

JupyterHub follows a hub-and-spoke architecture:

  • Hub: Central server that manages authentication, user sessions, and configuration
  • Proxy: Routes HTTP traffic between users and their notebook servers
  • Spawners: Create and manage individual notebook servers for each user
  • Authenticators: Handle user authentication via various backends
  • Database: Stores user, server, and configuration state

The plugin architecture allows custom implementations of authenticators, spawners, and proxies through Python entry points, making JupyterHub highly extensible for different deployment scenarios.

Capabilities

Core Application Management

Main JupyterHub application class and configuration management for orchestrating the multi-user notebook server system.

class JupyterHub(Application):
    def initialize(self, argv=None): ...
    def start(self): ...
    def stop(self): ...

def main(argv=None): ...

Core Application

Authentication System

Pluggable authentication system supporting multiple backends including PAM, OAuth, LDAP, and custom authenticators.

class Authenticator(LoggingConfigurable):
    async def authenticate(self, handler, data): ...
    async def pre_spawn_start(self, user, spawner): ...
    def pre_spawn_hook(self, spawner): ...

class PAMAuthenticator(LocalAuthenticator): ...
class DummyAuthenticator(Authenticator): ...  
class NullAuthenticator(Authenticator): ...

Authentication

Spawner System

System for creating and managing single-user notebook servers with support for local processes, containers, and cloud platforms.

class Spawner(LoggingConfigurable):
    async def start(self): ...
    async def stop(self, now=False): ...
    async def poll(self): ...

class LocalProcessSpawner(Spawner): ...
class SimpleLocalProcessSpawner(LocalProcessSpawner): ...

Spawners

Database Models and ORM

SQLAlchemy-based database models for persistent storage of users, servers, groups, roles, and authentication state.

class User(Base):
    name: str
    admin: bool
    servers: List[Server]
    groups: List[Group]

class Server(Base):
    name: str
    user: User
    url: str
    state: Dict[str, Any]

class Group(Base):
    name: str
    users: List[User]
    roles: List[Role]

class Role(Base):
    name: str
    description: str
    scopes: List[str]

Database Models

REST API System

Complete REST API for external integration and management of JupyterHub resources including users, groups, services, and servers.

class APIHandler(BaseHandler):
    def get_current_user(self): ...
    def check_xsrf_cookie(self): ...

# API endpoints at /api/*
# - /api/users - User management
# - /api/groups - Group management  
# - /api/services - Service management
# - /api/proxy - Proxy management

REST API

Role-Based Access Control (RBAC)

Comprehensive permission system with roles, scopes, and fine-grained access control for users, groups, and services.

def get_default_roles() -> Dict[str, Dict[str, Any]]: ...

scope_definitions: Dict[str, str]  # All available scopes

class Role(Base):
    name: str
    scopes: List[str]
    users: List[User]
    groups: List[Group]

RBAC and Permissions

Service Integration

System for integrating external services with JupyterHub authentication and authorization, including OAuth provider capabilities.

class Service:
    def __init__(self, **kwargs): ...
    
# OAuth provider
class OAuthClient(Base): ...
class OAuthCode(Base): ...

Services and OAuth

Configuration and Utilities

Configuration system using traitlets and utility functions for tokens, URLs, SSL, and other common operations.

# Configuration traitlets
class Command(TraitType): ...
class URLPrefix(TraitType): ...
class ByteSpecification(TraitType): ...

# Utility functions
def new_token(length=32, entropy=None) -> str: ...
def hash_token(token: str, salt=None, rounds=16384) -> str: ...
def url_path_join(*pieces) -> str: ...
def make_ssl_context(keyfile, certfile, **kwargs): ...

Configuration and Utilities

Single-user Server Integration

Tools and mixins for creating Hub-authenticated single-user servers and Jupyter server extensions.

def make_singleuser_app(cls): ...

class HubAuthenticatedHandler(BaseHandler): ...

def _jupyter_server_extension_points() -> List[Dict[str, Any]]: ...

Single-user Integration

Monitoring and Metrics

Prometheus metrics collection and monitoring capabilities for tracking system performance and usage.

# Prometheus metrics
TOTAL_USERS: Gauge
RUNNING_SERVERS: Gauge
REQUEST_DURATION_SECONDS: Histogram

class PeriodicMetricsCollector:
    def __init__(self, app): ...
    async def collect_metrics(self): ...

Monitoring and Metrics

Types

# Configuration types
Config = Dict[str, Any]
UserDict = Dict[str, User]

# Authentication types  
AuthModel = Dict[str, Any]
UserInfo = Dict[str, Any]

# Server types
ServerState = Dict[str, Any]
SpawnerOptions = Dict[str, Any]

# API types
APIResponse = Dict[str, Any]
APIError = Dict[str, str]

# OAuth types
OAuthToken = Dict[str, Any]
OAuthScope = str