0
# Core Application Management
1
2
The JupyterHub application system provides the main orchestration layer for the multi-user notebook server. It manages configuration, initialization, startup, and shutdown processes for the entire JupyterHub deployment.
3
4
## Capabilities
5
6
### Main Application Class
7
8
The primary JupyterHub application class that coordinates all system components including the hub server, proxy, database, and user management.
9
10
```python { .api }
11
class JupyterHub(Application):
12
"""
13
The JupyterHub application class.
14
15
Manages the overall JupyterHub system including configuration,
16
initialization, and coordination of all components.
17
"""
18
19
# Configuration attributes
20
ip: str # IP address to bind to
21
port: int # Port to bind to
22
hub_ip: str # Hub internal IP
23
hub_port: int # Hub internal port
24
base_url: str # Base URL prefix
25
db_url: str # Database URL
26
27
# Component classes
28
authenticator_class: str # Authenticator to use
29
spawner_class: str # Spawner to use
30
proxy_class: str # Proxy to use
31
32
def initialize(self, argv=None):
33
"""
34
Initialize the application.
35
36
Args:
37
argv: Command line arguments
38
"""
39
40
def start(self):
41
"""
42
Start the JupyterHub application.
43
44
Starts the tornado web server and begins handling requests.
45
"""
46
47
def stop(self):
48
"""
49
Stop the JupyterHub application.
50
51
Gracefully shuts down all components.
52
"""
53
54
def cleanup(self):
55
"""
56
Cleanup on shutdown.
57
58
Stops spawners, closes database connections, etc.
59
"""
60
```
61
62
### Entry Point Functions
63
64
Command-line entry points for starting JupyterHub components.
65
66
```python { .api }
67
def main(argv=None):
68
"""
69
Main entry point for the jupyterhub command.
70
71
Args:
72
argv: Command line arguments (defaults to sys.argv)
73
74
Returns:
75
Exit code (0 for success)
76
"""
77
78
def singleuser_main(argv=None):
79
"""
80
Main entry point for jupyterhub-singleuser command.
81
82
Args:
83
argv: Command line arguments
84
85
Returns:
86
Exit code (0 for success)
87
"""
88
```
89
90
### Configuration Management
91
92
JupyterHub uses the traitlets configuration system for managing settings.
93
94
```python { .api }
95
# Configuration access pattern
96
from traitlets.config import get_config
97
98
c = get_config()
99
100
# Core settings
101
c.JupyterHub.ip = '0.0.0.0'
102
c.JupyterHub.port = 8000
103
c.JupyterHub.base_url = '/'
104
105
# Database
106
c.JupyterHub.db_url = 'sqlite:///jupyterhub.sqlite'
107
108
# Authentication
109
c.JupyterHub.authenticator_class = 'pam'
110
c.Authenticator.admin_users = {'admin'}
111
112
# Spawning
113
c.JupyterHub.spawner_class = 'localprocess'
114
c.Spawner.start_timeout = 60
115
```
116
117
## Usage Examples
118
119
### Basic Deployment
120
121
```python
122
# Create minimal JupyterHub instance
123
from jupyterhub.app import JupyterHub
124
125
app = JupyterHub()
126
app.ip = '0.0.0.0'
127
app.port = 8000
128
app.initialize()
129
app.start()
130
```
131
132
### Configuration File Deployment
133
134
```python
135
# jupyterhub_config.py
136
c = get_config()
137
138
# Network configuration
139
c.JupyterHub.ip = '0.0.0.0'
140
c.JupyterHub.port = 8000
141
c.JupyterHub.hub_ip = '127.0.0.1'
142
143
# Use dummy authenticator for testing
144
c.JupyterHub.authenticator_class = 'dummy'
145
146
# Set admin users
147
c.Authenticator.admin_users = {'admin', 'teacher'}
148
149
# Configure spawner
150
c.JupyterHub.spawner_class = 'localprocess'
151
c.LocalProcessSpawner.create_system_users = True
152
153
# Database
154
c.JupyterHub.db_url = 'postgresql://user:password@localhost/jupyterhub'
155
```
156
157
### Programmatic Control
158
159
```python
160
import asyncio
161
from jupyterhub.app import JupyterHub
162
163
async def run_hub():
164
"""Run JupyterHub programmatically"""
165
app = JupyterHub()
166
167
# Configure programmatically
168
app.ip = '127.0.0.1'
169
app.port = 8000
170
app.authenticator_class = 'dummy'
171
172
# Initialize and start
173
app.initialize()
174
175
try:
176
await app.start()
177
except KeyboardInterrupt:
178
await app.stop()
179
await app.cleanup()
180
181
# Run the hub
182
asyncio.run(run_hub())
183
```
184
185
## Integration Patterns
186
187
### Custom Application Subclass
188
189
```python
190
from jupyterhub.app import JupyterHub
191
192
class CustomJupyterHub(JupyterHub):
193
"""Custom JupyterHub with additional functionality"""
194
195
def initialize(self, argv=None):
196
"""Initialize with custom setup"""
197
super().initialize(argv)
198
199
# Add custom initialization
200
self.setup_custom_components()
201
202
def setup_custom_components(self):
203
"""Setup custom components"""
204
# Add custom handlers, services, etc.
205
pass
206
```
207
208
### Service Integration
209
210
```python
211
# Add external services to JupyterHub
212
c.JupyterHub.services = [
213
{
214
'name': 'announcement',
215
'url': 'http://localhost:8001',
216
'command': ['python', '/path/to/announcement-service.py'],
217
'oauth_redirect_uri': 'http://localhost:8001/oauth-callback'
218
}
219
]
220
```