0
# JupyterHub
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: jupyterhub
7
- **Language**: Python
8
- **Installation**: `pip install jupyterhub`
9
- **Version**: 5.3.0
10
11
## Core Imports
12
13
```python
14
# Main application class
15
from jupyterhub.app import JupyterHub
16
17
# Authentication system
18
from jupyterhub.auth import Authenticator, PAMAuthenticator, DummyAuthenticator
19
20
# Spawner system
21
from jupyterhub.spawner import Spawner, LocalProcessSpawner
22
23
# Database models
24
from jupyterhub.orm import User, Server, Group, Role, Service
25
26
# Configuration utilities
27
from jupyterhub.utils import new_token, hash_token, url_path_join
28
```
29
30
## Basic Usage
31
32
### Starting JupyterHub
33
34
```python
35
# Command line (most common)
36
# jupyterhub --config=/path/to/jupyterhub_config.py
37
38
# Programmatic usage
39
from jupyterhub.app import JupyterHub
40
41
# Create application instance
42
app = JupyterHub()
43
app.initialize()
44
app.start()
45
```
46
47
### Basic Configuration
48
49
```python
50
# jupyterhub_config.py
51
c = get_config()
52
53
# Basic settings
54
c.JupyterHub.ip = '0.0.0.0'
55
c.JupyterHub.port = 8000
56
c.JupyterHub.hub_ip = '127.0.0.1'
57
58
# Authentication
59
c.JupyterHub.authenticator_class = 'pam' # or 'dummy' for testing
60
61
# Spawner
62
c.JupyterHub.spawner_class = 'localprocess'
63
64
# Admin users
65
c.Authenticator.admin_users = {'admin'}
66
67
# Database
68
c.JupyterHub.db_url = 'sqlite:///jupyterhub.sqlite'
69
```
70
71
## Architecture
72
73
JupyterHub follows a hub-and-spoke architecture:
74
75
- **Hub**: Central server that manages authentication, user sessions, and configuration
76
- **Proxy**: Routes HTTP traffic between users and their notebook servers
77
- **Spawners**: Create and manage individual notebook servers for each user
78
- **Authenticators**: Handle user authentication via various backends
79
- **Database**: Stores user, server, and configuration state
80
81
The plugin architecture allows custom implementations of authenticators, spawners, and proxies through Python entry points, making JupyterHub highly extensible for different deployment scenarios.
82
83
## Capabilities
84
85
### Core Application Management
86
87
Main JupyterHub application class and configuration management for orchestrating the multi-user notebook server system.
88
89
```python { .api }
90
class JupyterHub(Application):
91
def initialize(self, argv=None): ...
92
def start(self): ...
93
def stop(self): ...
94
95
def main(argv=None): ...
96
```
97
98
[Core Application](./core-application.md)
99
100
### Authentication System
101
102
Pluggable authentication system supporting multiple backends including PAM, OAuth, LDAP, and custom authenticators.
103
104
```python { .api }
105
class Authenticator(LoggingConfigurable):
106
async def authenticate(self, handler, data): ...
107
async def pre_spawn_start(self, user, spawner): ...
108
def pre_spawn_hook(self, spawner): ...
109
110
class PAMAuthenticator(LocalAuthenticator): ...
111
class DummyAuthenticator(Authenticator): ...
112
class NullAuthenticator(Authenticator): ...
113
```
114
115
[Authentication](./authentication.md)
116
117
### Spawner System
118
119
System for creating and managing single-user notebook servers with support for local processes, containers, and cloud platforms.
120
121
```python { .api }
122
class Spawner(LoggingConfigurable):
123
async def start(self): ...
124
async def stop(self, now=False): ...
125
async def poll(self): ...
126
127
class LocalProcessSpawner(Spawner): ...
128
class SimpleLocalProcessSpawner(LocalProcessSpawner): ...
129
```
130
131
[Spawners](./spawners.md)
132
133
### Database Models and ORM
134
135
SQLAlchemy-based database models for persistent storage of users, servers, groups, roles, and authentication state.
136
137
```python { .api }
138
class User(Base):
139
name: str
140
admin: bool
141
servers: List[Server]
142
groups: List[Group]
143
144
class Server(Base):
145
name: str
146
user: User
147
url: str
148
state: Dict[str, Any]
149
150
class Group(Base):
151
name: str
152
users: List[User]
153
roles: List[Role]
154
155
class Role(Base):
156
name: str
157
description: str
158
scopes: List[str]
159
```
160
161
[Database Models](./database-models.md)
162
163
### REST API System
164
165
Complete REST API for external integration and management of JupyterHub resources including users, groups, services, and servers.
166
167
```python { .api }
168
class APIHandler(BaseHandler):
169
def get_current_user(self): ...
170
def check_xsrf_cookie(self): ...
171
172
# API endpoints at /api/*
173
# - /api/users - User management
174
# - /api/groups - Group management
175
# - /api/services - Service management
176
# - /api/proxy - Proxy management
177
```
178
179
[REST API](./rest-api.md)
180
181
### Role-Based Access Control (RBAC)
182
183
Comprehensive permission system with roles, scopes, and fine-grained access control for users, groups, and services.
184
185
```python { .api }
186
def get_default_roles() -> Dict[str, Dict[str, Any]]: ...
187
188
scope_definitions: Dict[str, str] # All available scopes
189
190
class Role(Base):
191
name: str
192
scopes: List[str]
193
users: List[User]
194
groups: List[Group]
195
```
196
197
[RBAC and Permissions](./rbac-permissions.md)
198
199
### Service Integration
200
201
System for integrating external services with JupyterHub authentication and authorization, including OAuth provider capabilities.
202
203
```python { .api }
204
class Service:
205
def __init__(self, **kwargs): ...
206
207
# OAuth provider
208
class OAuthClient(Base): ...
209
class OAuthCode(Base): ...
210
```
211
212
[Services and OAuth](./services-oauth.md)
213
214
### Configuration and Utilities
215
216
Configuration system using traitlets and utility functions for tokens, URLs, SSL, and other common operations.
217
218
```python { .api }
219
# Configuration traitlets
220
class Command(TraitType): ...
221
class URLPrefix(TraitType): ...
222
class ByteSpecification(TraitType): ...
223
224
# Utility functions
225
def new_token(length=32, entropy=None) -> str: ...
226
def hash_token(token: str, salt=None, rounds=16384) -> str: ...
227
def url_path_join(*pieces) -> str: ...
228
def make_ssl_context(keyfile, certfile, **kwargs): ...
229
```
230
231
[Configuration and Utilities](./configuration-utilities.md)
232
233
### Single-user Server Integration
234
235
Tools and mixins for creating Hub-authenticated single-user servers and Jupyter server extensions.
236
237
```python { .api }
238
def make_singleuser_app(cls): ...
239
240
class HubAuthenticatedHandler(BaseHandler): ...
241
242
def _jupyter_server_extension_points() -> List[Dict[str, Any]]: ...
243
```
244
245
[Single-user Integration](./singleuser-integration.md)
246
247
### Monitoring and Metrics
248
249
Prometheus metrics collection and monitoring capabilities for tracking system performance and usage.
250
251
```python { .api }
252
# Prometheus metrics
253
TOTAL_USERS: Gauge
254
RUNNING_SERVERS: Gauge
255
REQUEST_DURATION_SECONDS: Histogram
256
257
class PeriodicMetricsCollector:
258
def __init__(self, app): ...
259
async def collect_metrics(self): ...
260
```
261
262
[Monitoring and Metrics](./monitoring-metrics.md)
263
264
## Types
265
266
```python { .api }
267
# Configuration types
268
Config = Dict[str, Any]
269
UserDict = Dict[str, User]
270
271
# Authentication types
272
AuthModel = Dict[str, Any]
273
UserInfo = Dict[str, Any]
274
275
# Server types
276
ServerState = Dict[str, Any]
277
SpawnerOptions = Dict[str, Any]
278
279
# API types
280
APIResponse = Dict[str, Any]
281
APIError = Dict[str, str]
282
283
# OAuth types
284
OAuthToken = Dict[str, Any]
285
OAuthScope = str
286
```