📋 WAIIDE Reference Documentation

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

Technical reference materials, patterns, and detailed specifications for WAIIDE.

📚 Reference Categories

Integration Patterns

Proven patterns and blueprints for integrating WAIIDE with different systems:

JupyterHub Integration

Complete blueprint for JupyterHub integration:

Spawner configuration patterns
Authentication flow design
Multi-instance architecture
URL routing and proxying
Environment variable management

Generic Integration Blueprint

Checklist and guidelines for any JupyterHub integration:

Prerequisites and requirements
Step-by-step integration process
Testing and validation procedures
Troubleshooting common issues
Best practices and recommendations

WAIIDE-Specific References

Detailed documentation specific to WAIIDE implementation:

Integration Summary

Comprehensive overview of WAIIDE’s integration approach:

Architecture decisions and rationale
Technical implementation details
Performance characteristics
Security considerations
Scalability patterns

LLM Blueprint

Patterns for integrating Language Learning Models with WAIIDE:

CalliopeAI Agent integration
LLM provider configuration
API key management
Response streaming and caching
Error handling and fallbacks

Network and Port Configuration

Port Configuration Reference

Complete reference for WAIIDE’s port usage:

Port mapping and routing
Internal vs external ports
Security considerations
Firewall configuration
Load balancer setup

🔧 Technical Specifications

Environment Variables

# JupyterHub Integration Variables
JUPYTERHUB_USER=username                    # User identifier
JUPYTERHUB_SERVER_NAME=username-waiide-abc  # Unique server name  
JUPYTERHUB_SERVICE_PREFIX=/user/username/   # URL prefix
JUPYTERHUB_SERVICE_URL=http://...           # Full service URL
JUPYTERHUB_API_TOKEN=token                  # Hub API token
JUPYTERHUB_API_URL=http://hub:8081/hub/api  # Hub API endpoint

# WAIIDE Configuration Variables  
USE_ALL_COMPONENTS=true                     # Enable all services
LOG_LEVEL=INFO                              # Logging level
VSCODE_PORT=8071                            # WAIIDE internal port (default)
JUPYTERHUB_PORT=8070                        # Main service port (default)
PORT=8070                                   # Override main service port (optional)

URL Patterns

# Modern Multi-Instance URLs
/user/{username}/{username}-{service}-{hash}/
/user/alice/alice-waiide-abc123/
/user/bob/bob-data-science-def456/

# Legacy Single-Instance URLs (deprecated)
/user/{username}/waiide/
/user/alice/waiide/

Container Lifecycle

# Container States
Starting → Running → Stopping → Stopped → Removed
    ↓         ↓         ↓          ↓         ↓
  Init    Active    Graceful   Inactive   Cleanup
         Process   Shutdown    State     Resources

🏗️ Architecture References

Service Architecture

WAIIDE Container Architecture:

┌─────────────────────────────────────────┐
│ Container: username-waiide-abc123       │
├─────────────────────────────────────────┤
│ Port 8080: Jupyter Server               │
│ ├─ JupyterHub SingleUser Extension      │
│ ├─ Jupyter Server Proxy                 │
│ └─ Custom Root Handler                   │
├─────────────────────────────────────────┤
│ Port 8071: WAIIDE Server               │
│ ├─ CalliopeAI Agent Extension           │
│ ├─ Pergamon Theme                       │
│ └─ Standard WAIIDE Extensions          │
├─────────────────────────────────────────┤
│ Background: API Server                  │
│ ├─ Health Check Endpoints               │
│ ├─ Proxy Management                     │
│ └─ Environment Detection                │
└─────────────────────────────────────────┘

Data Flow

User Request → Load Balancer → JupyterHub → WAIIDE Container
                                    ↓
                            ┌─────────────────┐
                            │ Container       │
                            │ ┌─────────────┐ │
                            │ │ Jupyter     │ │ ← Authentication
                            │ │ Server      │ │ 
                            │ │ (Port 8080) │ │
                            │ └─────────────┘ │
                            │        ↓        │
                            │ ┌─────────────┐ │
                            │ │ WAIIDE     │ │ ← IDE Interface
                            │ │ Server      │ │
                            │ │ (Port 8071) │ │
                            │ └─────────────┘ │
                            └─────────────────┘

📊 Performance References

Resource Benchmarks

Configuration	CPU Usage	Memory Usage	Startup Time
Minimal	0.1-0.5 cores	512MB-1GB	30-45s
Standard	0.5-2 cores	1-4GB	20-30s
Enhanced	2-4 cores	4-8GB	15-25s
Maximum	4-8 cores	8-16GB	10-20s

Scaling Metrics

# Concurrent Users per Host
Small Instance (2 vCPU, 8GB): 2-4 users
Medium Instance (4 vCPU, 16GB): 4-8 users  
Large Instance (8 vCPU, 32GB): 8-16 users
XLarge Instance (16 vCPU, 64GB): 16-32 users

# Network Requirements
Bandwidth per User: 1-5 Mbps
Latency Requirements: <100ms
WebSocket Connections: 5-10 per user

🔍 API References

Health Check Endpoints

GET /health
Response: {"status": "healthy", "timestamp": "2025-01-26T10:00:00Z"}

GET /api/status  
Response: {
  "services": {
    "WAIIDE": {"status": "running", "port": 8071},
    "jupyter": {"status": "running", "port": 8080}
  },
  "environment": {
    "user": "username",
    "server_name": "username-waiide-abc123"
  }
}

Proxy Endpoints

# WAIIDE Access
GET /proxy/8071/ → WAIIDE Server
GET /proxy/8071/static/ → WAIIDE static assets

# API Access  
GET /api/health → Health check
GET /api/status → Service status
POST /api/restart → Service restart (admin only)

🛡️ Security References

Authentication Flow

1. User → JupyterHub Login
2. JupyterHub → OAuth Provider  
3. OAuth Provider → Token Response
4. JupyterHub → Container Spawn (with token)
5. Container → Token Validation
6. Container → Service Access Granted

Security Headers

# Required Headers
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000

# JupyterHub Headers
Authorization: token <jwt-token>
X-JupyterHub-User: username
X-JupyterHub-Server: servername

📝 Configuration Templates

JupyterHub Spawner Template

# Modern Multi-Instance Configuration
c.JupyterHub.allow_named_servers = True
c.JupyterHub.named_server_limit_per_user = 0
c.DockerSpawner.name_template = '{servername}'
c.DockerSpawner.image = 'calliopeai/waiide:latest'

# Environment Variables
c.DockerSpawner.environment = {
    'USE_ALL_COMPONENTS': 'true',
    'LOG_LEVEL': 'INFO',
    'VSCODE_PORT': '8071'
}

# Resource Limits
c.DockerSpawner.mem_limit = '4G'
c.DockerSpawner.cpu_limit = 2

Docker Compose Template

version: '3.8'
services:
  waiide:
    image: calliopeai/waiide:latest
    ports:
      - "8070:8070"  # Default JUPYTERHUB_PORT
    environment:
      - JUPYTERHUB_USER=${USER}
      - JUPYTERHUB_SERVER_NAME=${USER}-waiide-${RANDOM_SUFFIX}
      - JUPYTERHUB_SERVICE_PREFIX=/user/${USER}/${USER}-waiide-${RANDOM_SUFFIX}/
      - USE_ALL_COMPONENTS=true
      - LOG_LEVEL=INFO
      # Override ports if needed:
      # - PORT=8080
      # - VSCODE_PORT=8081
    volumes:
      - waiide-data:/home/calliope
    restart: unless-stopped

volumes:
  waiide-data:

🔄 Migration References

Legacy to Modern URL Migration

# Old URLs (deprecated)
/user/username/waiide/ → Jupyter interface
/user/username/waiide/WAIIDE/ → WAIIDE access

# New URLs (current)  
/user/username/username-waiide-abc123/ → Direct WAIIDE access
/user/username/username-data-def456/ → Additional instance

Configuration Migration

# Old Configuration
c.DockerSpawner.name_template = '{username}-waiide'
c.Spawner.default_url = '/WAIIDE/'

# New Configuration  
c.DockerSpawner.name_template = '{servername}'
c.Spawner.default_url = '/'

📚 Standards and Conventions

Naming Conventions

# Server Names
Pattern: {username}-{service}-{hash}
Examples: alice-waiide-abc123, bob-data-science-def456

# Container Names  
Pattern: {server_name}
Examples: alice-waiide-abc123, bob-data-science-def456

# Environment Variables
JupyterHub: JUPYTERHUB_*
WAIIDE: WAIIDE_* or USE_*, LOG_*, PORT

Port Conventions

# Standard Ports
8000: JupyterHub Hub
8070: WAIIDE Main Service (Jupyter Server) - Default
8071: WAIIDE Server (Internal) - Default
8080: Common Override for Main Service

# Development Ports
3000: Extension Development Server
9229: Node.js Debugging
5678: Python Debugging

🔗 External References

JupyterHub Documentation

WAIIDE Server Documentation

Docker References

🎯 Using This Reference

This reference documentation is designed for:

System Administrators: Configuring and deploying WAIIDE
DevOps Engineers: Integrating with CI/CD and monitoring
Developers: Understanding architecture and extending functionality
Support Teams: Troubleshooting and performance tuning

📞 Reference Support

For questions about this reference documentation:

Technical Issues: Check Troubleshooting Guide
Integration Help: See Configuration Guide
Development Questions: Visit Development Guide
Architecture Details: Read Architecture Guide

🎯 Your First WAIIDE Instance 📚 WAIIDE Documentation