WAIIDE JupyterHub Integration - Hub Side Implementation

Calliope Integration: This component is integrated into the Calliope AI platform. Some features and configurations may differ from the upstream project.

Context

WAIIDE (Web AI IDE) is a WAIIDE Server container that we’ve successfully configured for JupyterHub integration. The container side is complete - now we need to implement the JupyterHub hub-side configuration.

What We’ve Built (Container Side)

Port Architecture

• Port 8080: Main service (JupyterHub integration endpoint)
• Port 8081: Direct WAIIDE Server access (optional)
• Dockerfile: EXPOSE 8080 8081

Service Architecture

The container runs multiple services depending on environment detection:

JupyterHub Mode (when JUPYTERHUB_SERVICE_PREFIX is set):

1. WAIIDE Server on port 8081 (internal)
2. JupyterHub SingleUser + jupyter-server-proxy on port 8080 (main)
3. Automatic proxy configuration: /WAIIDE/ → WAIIDE Server

Standalone Mode (no JupyterHub environment):

1. Custom API server on port 8080 that proxies to WAIIDE Server
2. WAIIDE Server on port 8081
3. API endpoints: /api, /api/services, /api/* (JupyterHub compatibility)

API Endpoints (for health checking)

• GET /api - Service overview and status
• GET /api/services - Service discovery
• GET /api/* - Basic JupyterHub compatibility responses
• All other requests proxied to WAIIDE Server

Environment Variables

The container detects JupyterHub via:

• JUPYTERHUB_SERVICE_PREFIX - Triggers JupyterHub mode
• JUPYTERHUB_USER - Username from hub
• PORT - Main port (defaults to 8080)
• USE_ALL_COMPONENTS - Enable all services (default: true)

Key Files Created

• scripts/entrypoint-jupyterhub.sh - Main entrypoint
• scripts/api_server.py - Custom API server for standalone mode
• Docker image: calliopeai/waiide:latest

What We Need (Hub Side Configuration)

JupyterHub Spawner Configuration

Help me configure the JupyterHub spawner to:

1. Spawn WAIIDE containers with proper environment variables
2. Configure health checking using our API endpoints
3. Set up proper port mapping (8080 as primary, optionally 8081)
4. Handle both integration modes (with/without jupyter-server-proxy)

Integration Options

We support two integration approaches:

1. Native JupyterHub: Uses jupyterhub-singleuser + jupyter-server-proxy
2. API Proxy: Uses our custom API server that provides JupyterHub-compatible endpoints

Specific Questions

1. Which JupyterHub spawner should we use? (DockerSpawner, KubeSpawner, etc.)
2. How to configure the spawner to use our container image?
3. How to set up health checking with our /api endpoints?
4. How to handle the dual-port architecture in JupyterHub?
5. Should we disable JupyterHub’s built-in health checking in favor of our API?

Expected Behavior

When complete, users should be able to:

• Click “Start” in JupyterHub
• Get redirected automatically to WAIIDE Server interface
• Have their workspace persist across sessions
• Access via JupyterHub’s URL structure: /user/{username}/proxy/8081/

How jupyter-server-proxy Works

The jupyter-server-proxy package automatically handles URL rewriting:

• User accesses: http://hub.example.com/user/lmata/proxy/8081/
• Proxy strips the prefix and forwards to: http://localhost:8081/
• WAIIDE Server receives clean paths without JupyterHub prefixes

Current Status

✅ Container integration complete
✅ Dual port architecture working
✅ API endpoints functional
✅ Environment detection working
🔄 Need JupyterHub hub-side configuration

Please help me implement the JupyterHub hub configuration to spawn and manage WAIIDE containers effectively.