WAIIDE Quick Start Guide

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

Get WAIIDE (Web AI IDE) running with JupyterHub in 5 minutes.

🎯 What You’ll Get

After completing this guide:

✅ WAIIDE running in JupyterHub
✅ WAIIDE accessible at clean URLs like /user/lmata/lmata-waiide-abc123/
✅ Multiple instances per user supported
✅ CalliopeAI Agent and Pergamon theme included

📋 Prerequisites

JupyterHub server running
Docker installed and accessible to JupyterHub
Admin access to modify jupyterhub_config.py

🚀 5-Minute Setup

Step 1: Pull the WAIIDE Image

docker pull calliopeai/waiide:latest

Step 2: Configure JupyterHub

Add this to your jupyterhub_config.py:

# Enable WAIIDE with multi-instance support
c.JupyterHub.spawner_class = 'dockerspawner.DockerSpawner'
c.DockerSpawner.image = 'calliopeai/waiide:latest'

# CRITICAL: Multi-instance configuration
c.JupyterHub.allow_named_servers = True
c.JupyterHub.named_server_limit_per_user = 0  # Unlimited instances
c.DockerSpawner.name_template = '{servername}'  # Container name = server name

# Network and volumes
c.DockerSpawner.network_name = 'jupyterhub-network'  # Your network name
c.DockerSpawner.volumes = {'jupyterhub-user-{username}': '/home/{username}'}

# Environment and resources
c.DockerSpawner.environment = {'PORT': '8080', 'USE_ALL_COMPONENTS': 'true'}
c.DockerSpawner.cpu_limit = 2
c.DockerSpawner.mem_limit = '4G'
c.DockerSpawner.remove = True

# WAIIDE at /ide URL
c.Spawner.default_url = '/ide'

Step 3: Restart JupyterHub

sudo systemctl restart jupyterhub
# or
docker-compose restart jupyterhub

Step 4: Test It Works

Login to JupyterHub: Go to your JupyterHub URL
Spawn WAIIDE: Click “Start My Server” or spawn a named server
Access WAIIDE: You should see WAIIDE loading directly at the root URL
Verify Instance: Check that URL shows format like /user/lmata/lmata-waiide-abc123/

✅ Verification Checklist

Container Running

# Check WAIIDE containers
docker ps | grep waiide

# Should show: lmata-waiide-abc123 (matches JupyterHub server name)

Environment Variables

# Check container environment
docker exec <container-name> env | grep JUPYTERHUB_SERVER_NAME

# Should show: testuser-waiide-abc123 (or similar)

API Response

# Check WAIIDE API
curl http://localhost:8080/api

# Should return JSON with instance info

WAIIDE Loading

✅ WAIIDE loads at root URL (no /WAIIDE/ or /proxy/ in path)
✅ CalliopeAI Agent extension available in extensions panel
✅ Pergamon theme applied (purple color scheme)
✅ Terminal and file explorer working

🎉 Success! What’s Next?

Spawn Multiple Instances

Users can now spawn multiple WAIIDE instances:

First instance: lmata-waiide-abc123
Second instance: lmata-waiide-def456
Lab instance: lmata-lab-ghi789

Configure Advanced Features

ECS Integration - Use with ECS/Fargate spawners
Environment Variables - Customize behavior
Multi-Instance Setup - Advanced multi-instance patterns

🚨 Common Issues

“WAIIDE Not Loading”

# Check container logs
docker logs <container-name>

# Look for: "WAIIDE Server is ready"
# If missing, see troubleshooting guide

“OAuth 403 Errors”

# Check server name in container
docker exec <container-name> echo $JUPYTERHUB_SERVER_NAME

# Should match the JupyterHub server name exactly

“Can’t Spawn Multiple Instances”

# Verify in jupyterhub_config.py
c.JupyterHub.allow_named_servers = True
c.JupyterHub.named_server_limit_per_user = 0

“Container Names Don’t Match”

# Fix container naming template
c.DockerSpawner.name_template = '{servername}'  # NOT '{username}-waiide'

📖 Need More Help?

Documentation

Full Configuration Guide - Comprehensive setup
Troubleshooting - Fix common issues
Architecture - Understand how it works

Testing Configurations

# Test with minimal environment (default ports)
docker run -it --rm -p 8070:8070 \
  -e JUPYTERHUB_SERVICE_PREFIX=/user/testuser/testuser-waiide-abc123/ \
  -e JUPYTERHUB_SERVICE_URL=http://hub.example.com/user/testuser/testuser-waiide-abc123/ \
  -e JUPYTERHUB_USER=testuser \
  -e JUPYTERHUB_SERVER_NAME=testuser-waiide-abc123 \
  -e JUPYTERHUB_API_TOKEN=test_token \
  -e JUPYTERHUB_API_URL=http://hub.example.com:8081/hub/api \
  calliopeai/waiide:latest

# Test with port override
docker run -it --rm -p 8080:8080 \
  -e PORT=8080 \
  -e JUPYTERHUB_SERVICE_PREFIX=/user/testuser/testuser-waiide-abc123/ \
  -e JUPYTERHUB_SERVICE_URL=http://hub.example.com/user/testuser/testuser-waiide-abc123/ \
  -e JUPYTERHUB_USER=testuser \
  -e JUPYTERHUB_SERVER_NAME=testuser-waiide-abc123 \
  -e JUPYTERHUB_API_TOKEN=test_token \
  -e JUPYTERHUB_API_URL=http://hub.example.com:8081/hub/api \
  calliopeai/waiide:latest

🔄 Migration from Legacy WAIIDE

If upgrading from an older version:

❌ Old Configuration (Remove)

# Old single-instance patterns
c.JupyterHub.allow_named_servers = False
c.DockerSpawner.name_template = '{username}-waiide'
c.Spawner.default_url = '/proxy/8081/'

✅ New Configuration (Use)

# New multi-instance patterns  
c.JupyterHub.allow_named_servers = True
c.JupyterHub.named_server_limit_per_user = 0
c.DockerSpawner.name_template = '{servername}'
c.Spawner.default_url = '/'

💡 Pro Tips

Start Simple: Use the basic configuration first, then customize
Check Logs: Enable LOG_LEVEL=DEBUG for troubleshooting
Test Locally: Use docker run to test configurations before deploying
Monitor Resources: Set appropriate CPU and memory limits
Backup Configs: Keep backups of working configurations

🎉 Congratulations! You now have WAIIDE running with modern multi-instance support. Users can spawn unlimited WAIIDE instances with clean URLs and full functionality.

📞 Need Help? Check the Troubleshooting Guide or review the Full Documentation.

WAIIDE Port Summary WAIIDE System Architecture