WAIIDE JupyterHub Integration

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

This document explains how WAIIDE (Web AI IDE) integrates with JupyterHub using multiple components for maximum compatibility and functionality.

Architecture Overview

WAIIDE runs four components simultaneously when USE_ALL_COMPONENTS=true (default):

1. WAIIDE Server (port 8080, internal)

   • Core IDE functionality
   • Runs on localhost only for security

2. JupyterHub SingleUser (port 8090, main)

   • Primary JupyterHub integration
   • Provides standard JupyterHub API endpoints
   • Handles user authentication and session management

3. Jupyter Server Proxy (within JupyterHub)

   • Proxies WAIIDE Server through JupyterHub
   • Accessible at /WAIIDE/ path
   • Provides seamless integration with JupyterHub interface

4. Custom API Server (port 8091)

   • Additional API endpoints
   • Direct WAIIDE Server proxy
   • Enhanced service discovery and health checking

Port Configuration

API Endpoints

JupyterHub Standard Endpoints (port 8090)

These are provided by jupyterhub-singleuser:

• GET /api/status - JupyterHub server status
• GET /api/user - Current user information
• GET /hub/api/... - Full JupyterHub API
• GET /WAIIDE/ - WAIIDE Server via proxy

Custom API Endpoints (port 8091)

These are provided by our custom API server:

• GET /api - Main API endpoint with service overview
• GET /api/status - Enhanced status with WAIIDE health check
• GET /api/user - User information
• GET /api/services - Detailed service discovery
• GET /* - Proxy to WAIIDE Server for direct access

Environment Variables

Required for JupyterHub Integration

• JUPYTERHUB_SERVICE_PREFIX - Set by JupyterHub
• JUPYTERHUB_USER - Username from JupyterHub
• JUPYTERHUB_API_TOKEN - API token from JupyterHub

Configuration Options

• USE_ALL_COMPONENTS=true - Run all components (default)
• USE_ALL_COMPONENTS=false - Run only WAIIDE + Custom API
• PORT=8090 - Main port for JupyterHub integration
• API_SERVER_PORT=8091 - Port for custom API server
• HOST=0.0.0.0 - Listen address

JupyterHub Spawner Configuration

For Full Integration (Recommended)

# In jupyterhub_config.py
c.JupyterHub.spawner_class = 'dockerspawner.DockerSpawner'

# WAIIDE spawner configuration
c.DockerSpawner.image_whitelist = {
    'waiide': 'calliopeai/waiide:latest'
}

# Service configuration
c.DockerSpawner.services = {
    'waiide': {
        'name': 'waiide',
        'image': 'calliopeai/waiide:latest',
        'port': 8090,
        'uses_jupyterhub_singleuser': True,  # Use JupyterHub integration
        'health_check': {
            'endpoint': '/api/status',
            'timeout': 60,
            'disable_health_check': False
        },
        'environment': {
            'USE_ALL_COMPONENTS': 'true'
        }
    }
}

For Lightweight Integration

# For environments where you want minimal JupyterHub integration
c.DockerSpawner.services = {
    'waiide': {
        'name': 'waiide',
        'image': 'calliopeai/waiide:latest',
        'port': 8090,
        'uses_jupyterhub_singleuser': False,  # Use custom API only
        'health_check': {
            'endpoint': '/api/status',
            'timeout': 30,
            'disable_health_check': False
        },
        'environment': {
            'USE_ALL_COMPONENTS': 'false'
        }
    }
}

Health Checking

JupyterHub Health Check

JupyterHub will health check at the configured endpoint:

• Full integration: http://container:8090/api/status
• Lightweight: http://container:8090/api/status

Manual Health Check

You can manually check service health:

# Check main API
curl http://localhost:8091/api

# Check specific services
curl http://localhost:8091/api/services

# Check JupyterHub integration
curl http://localhost:8090/api/status

Access Methods

Through JupyterHub (Recommended)

1. Standard JupyterHub Interface: /hub/spawn
2. Direct WAIIDE Access: /user/{username}/waiide/WAIIDE/
3. API Access: /user/{username}/waiide/api/

Direct Access (Development)

1. WAIIDE Server: http://localhost:8080 (if exposed)
2. Custom API: http://localhost:8091/api
3. JupyterHub: http://localhost:8090

Testing

Quick Test

# Run the test script
python3 scripts/test_api.py

# Or test specific endpoint
curl http://localhost:8091/api/services

Full Integration Test

# Set environment variables
export JUPYTERHUB_USER=testuser
export JUPYTERHUB_SERVICE_PREFIX=/user/testuser/waiide/
export USE_ALL_COMPONENTS=true

# Start WAIIDE
./scripts/entrypoint-jupyterhub.sh

Troubleshooting

Common Issues

1. JupyterHub Health Check Fails

   • Check if port 8090 is accessible
   • Verify /api/status endpoint responds
   • Check container logs for startup errors

2. WAIIDE Not Accessible

   • Ensure WAIIDE Server started (check port 8080)
   • Verify proxy configuration
   • Check /WAIIDE/ path accessibility

3. API Endpoints Not Working

   • Ensure API server started on port 8091
   • Check firewall/network configuration
   • Verify JSON responses are valid

Debug Mode

Add debug logging:

export DEBUG=true
./scripts/entrypoint-jupyterhub.sh

Architecture Benefits

This multi-component architecture provides:

• Maximum Compatibility: Works with all JupyterHub configurations
• Flexibility: Can run in full or lightweight mode
• Robustness: Multiple access methods prevent single points of failure
• Extensibility: Easy to add new API endpoints or services
• Standard Compliance: Follows JupyterHub API conventions

Migration Notes

If upgrading from a previous version:

1. The default behavior now runs all components
2. Set USE_ALL_COMPONENTS=false for old behavior
3. Update health check endpoints if needed
4. Review port configurations in your spawner

© 2025 CalliopeAI - Web AI IDE (WAIIDE) with comprehensive JupyterHub integration