Documentation
Waiide
WAIIDE Configuration Guide

WAIIDE Configuration Guide

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

Overview

WAIIDE (Web AI IDE) requires configuration at two levels:

  1. Hub-side: JupyterHub configuration to spawn containers
  2. Container-side: Jupyter Server configuration inside each container

URL Structure (Updated for Multi-Instance)

WAIIDE now supports multiple instances per user with unique hashed names:

Modern Instance URLs

  • Single instance: https://hub.example.com/user/lmata/lmata-waiide-abc123/
  • Multiple instances:
    • https://hub.example.com/user/lmata/lmata-waiide-def456/
    • https://hub.example.com/user/lmata/lmata-lab-ghi789/

WAIIDE Access

WAIIDE is served directly at the root of each instance URL:

  • ✅ Direct access: https://hub.example.com/user/lmata/lmata-waiide-abc123/
  • ❌ Old paths: No more /WAIIDE/ or /proxy/8081/ required

Configuration Files

1. hub_config_for_waiide.py (Hub Administrator Config)

Location: On the JupyterHub server
Purpose: Tells JupyterHub how to spawn WAIIDE containers
Used by: JupyterHub administrators

This file configures:

  • Docker image to use (calliopeai/waiide:latest)
  • Volume mounts for user data persistence
  • Multi-instance support with unique container names
  • Network settings and resource limits
  • Environment variables including instance names

Key updates for multi-instance:

# Enable unlimited named servers for multi-instance support
c.JupyterHub.allow_named_servers = True
c.JupyterHub.named_server_limit_per_user = 0  # Unlimited instances
c.JupyterHub.active_server_limit = 0  # Unlimited total servers

# Container naming matches server names exactly
c.DockerSpawner.name_template = '{servername}'  # e.g., 'lmata-waiide-abc123'

# Environment variables for instance identification
c.DockerSpawner.environment = {
    'PORT': '8080',
    'USE_ALL_COMPONENTS': 'true',
    # JUPYTERHUB_SERVER_NAME will be auto-set to the full instance name
}

2. scripts/jupyter_server_config.py (Container-Side Config)

Location: Built into the Docker image
Purpose: Configures Jupyter Server inside each container
Used by: jupyterhub-singleuser process

This file now configures:

  • WAIIDE served at root path (/) instead of /proxy/8081/
  • OAuth authentication with JupyterHub for named servers
  • Instance name detection and logging
  • Automatic URL routing without path prefixes

This file automatically:

  • Detects the instance name from JUPYTERHUB_SERVER_NAME
  • Logs: “Running as named server: lmata-waiide-abc123 for user: lmata”
  • Serves WAIIDE directly at the root URL
  • Handles OAuth callbacks correctly for hashed names

Architecture Diagram (Updated) 

┌─────────────────────────────────┐
│         JupyterHub Host         │
│                                 │
│    jupyterhub_config.py         │
│            +                    │
│    hub_config_for_waiide.py     │
│                                 │
│ Multi-instance spawning enabled │
└──────────────┬──────────────────┘
               │ Spawns multiple instances
               ▼
┌─────────────────────────────────┐
│    WAIIDE Instance Containers   │
│                                 │
│  lmata-waiide-abc123:           │
│  ├─ jupyterhub-singleuser:8080  │
│  ├─ WAIIDE Server:8071         │
│  └─ Served at: /user/lmata/     │
│      lmata-waiide-abc123/       │
│                                 │
│  lmata-lab-def456:              │
│  ├─ jupyterhub-singleuser:8080  │
│  ├─ WAIIDE Server:8071         │
│  └─ Served at: /user/lmata/     │
│      lmata-lab-def456/          │
└─────────────────────────────────┘

ECS Spawner Integration

For ECS/Fargate deployments, ensure your spawner:

  1. Generates unique instance names: username-service-hash format
  2. Sets environment variables:
    JUPYTERHUB_SERVER_NAME=lmata-waiide-abc123
JUPYTERHUB_SERVICE_PREFIX=/user/lmata/lmata-waiide-abc123/
JUPYTERHUB_SERVICE_URL=https://hub.example.com/user/lmata/lmata-waiide-abc123/
  3. Matches container names to server names for consistency

Key Benefits of New Architecture

  1. Multiple instances per user: Users can run multiple WAIIDE instances simultaneously
  2. Clean URLs: WAIIDE loads directly at /user/lmata/lmata-waiide-abc123/
  3. Unique identification: Each instance has a clear, identifiable name
  4. Consistent naming: Container names match JupyterHub server names exactly
  5. No path confusion: No /WAIIDE/, /proxy/, or similar paths needed

Migration from Legacy Setup

If upgrading from older WAIIDE configurations:

❌ Old URLs

  • https://hub.example.com/user/lmata/waiide/WAIIDE/
  • https://hub.example.com/user/lmata/proxy/8081/

✅ New URLs

  • https://hub.example.com/user/lmata/lmata-waiide-abc123/

Required Changes

  1. Update spawner configuration for multi-instance support
  2. Remove any hardcoded /WAIIDE/ redirects
  3. Update documentation and user instructions
  4. Test OAuth flows with named servers

Troubleshooting Modern Issues

Instance Name Not Appearing in Logs

  • Check JUPYTERHUB_SERVER_NAME is set correctly
  • Verify spawner is passing the full instance name

Multiple Instances Not Working

  • Ensure named_server_limit_per_user = 0 (unlimited)
  • Check container naming doesn’t conflict

WAIIDE Not at Root

  • Verify jupyter_server_config.py has root handler configured
  • Check default_url = '/' is set correctly

See ECS Instance Names for detailed ECS integration.

WAIIDE ConfigurationWAIIDE JupyterHub Integration