WAIIDE Configuration

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

This section covers all aspects of configuring WAIIDE for different deployment scenarios.

🚀 Quick Configuration

• JupyterHub Setup - Main configuration guide for JupyterHub spawners
• Environment Variables - Complete reference of all environment variables
• Multi-Instance Setup - Configure unlimited instances per user

🌐 Deployment Scenarios

Docker Spawner (Most Common)

• JupyterHub Setup - Standard Docker integration
• Example Configuration - Complete working example

ECS/Fargate Spawner

• ECS Integration - Custom spawner configuration
• Instance Names - Unique naming patterns

Kubernetes

• KubeSpawner Setup - K8s-specific configuration

📝 Configuration Files

🎯 Modern Architecture (v2.0+)

WAIIDE now supports modern multi-instance architecture:

✅ Current Pattern

# Multi-instance support
c.JupyterHub.allow_named_servers = True
c.JupyterHub.named_server_limit_per_user = 0  # Unlimited

# Container naming matches server names
c.DockerSpawner.name_template = '{servername}'

# Example URLs:
# /user/lmata/lmata-waiide-abc123/
# /user/lmata/lmata-lab-def456/

❌ Legacy Pattern (Deprecated)

# Single instance only
c.JupyterHub.allow_named_servers = False
c.DockerSpawner.name_template = '{username}-waiide'

# Old URL: /user/lmata/waiide/WAIIDE/

🔧 Key Configuration Concepts

1. Instance Names

• Format: username-service-hash (e.g., lmata-waiide-abc123)
• Uniqueness: 6-character hash ensures no conflicts
• Consistency: Container name = JupyterHub server name

2. URL Structure

• Root serving: WAIIDE loads at /user/lmata/lmata-waiide-abc123/
• No prefixes: No /WAIIDE/ or /proxy/8081/ paths needed
• Clean URLs: Easy to share and bookmark

3. Environment Variables

• Auto-set: JupyterHub sets JUPYTERHUB_SERVER_NAME automatically
• Instance-aware: WAIIDE detects and logs instance names
• OAuth-ready: Proper callback URLs for authentication

📋 Configuration Checklist

For New Deployments

• Update jupyterhub_config.py with modern patterns
• Enable unlimited named servers
• Set correct container naming template
• Configure environment variables
• Test multi-instance spawning

For Existing Deployments

• Review Migration Guide
• Update spawner configuration
• Test OAuth with named servers
• Update user documentation
• Validate URL patterns

🔍 Configuration Validation

Test Commands

# Test environment variables
docker exec <container> env | grep JUPYTERHUB

# Check instance name detection
docker logs <container> | grep "Running as named server"

# Verify URL patterns
curl http://localhost:8080/api

Expected Results

{
  "server": "waiide",
  "user": "lmata", 
  "service_prefix": "/user/lmata/lmata-waiide-abc123/",
  "mode": "jupyterhub"
}

🚨 Common Configuration Issues

📖 Related Documentation

• Troubleshooting - Fix configuration issues
• Architecture - Understand the system design
• API Reference - API endpoints and integration

💡 Tip: Start with JupyterHub Setup for your first deployment!