Documentation
Waiide
WAIIDE Architecture Migration - July 2025

WAIIDE Architecture Migration - July 2025

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

This document captures the major architectural changes made to WAIIDE to fix ECS deployment issues and improve multi-user support.

Major Changes

1. System File Locations

Old: Files stored in /home/calliope/ New: Files stored in /opt/calliope/

  • /opt/calliope/WAIIDE-server/ - WAIIDE Server binaries
  • /opt/calliope/scripts/ - System scripts (jupyter_server_config.py, etc.)

Rationale: When JUPYTERHUB_USER is set (e.g., lmata), the container changes to that user’s home directory, but the hardcoded paths to /home/calliope/ would fail.

2. Default Ports

Old: Various docs showed 8080 as default New: Consistent defaults of 8070/8071

  • Port 8070: Main service (JupyterHub/API)
  • Port 8071: WAIIDE Server (internal)

Rationale: Avoid conflicts with common services on 8080, maintain consistency.

3. WAIIDE URL Path

Old: WAIIDE served at root (/) New: WAIIDE served at /ide

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

Rationale: Better separation of concerns, clearer URL structure.

4. User Directory Management

Old: Fixed directories under /home/calliope/ New: Dynamic per-user directories

  • System files: /opt/calliope/ (read-only)
  • User files: /home/{username}/ (writable, persistent)
  • Extensions copied at runtime to user directory
  • Settings persist in user’s home

Rationale: Support for multi-user environments with proper isolation and persistence.

Files Updated

Core Files

  • Dockerfile - Moved installation paths to /opt/calliope/
  • scripts/entrypoint-jupyterhub.sh - Updated paths, added user directory setup
  • scripts/jupyter_server_config.py - Changed default_url to ‘/ide’

Documentation

  • README.md - Updated ports and architecture diagram
  • docs/BOOTSTRAP.md - Complete rewrite with current architecture
  • docs/architecture/port-summary.md - Corrected port information

Deprecated Patterns

Don’t Use: 

# Old: WAIIDE at root
c.Spawner.default_url = '/'
c.Spawner.default_url = '/proxy/8081/'

# Old: Hardcoded paths
/home/calliope/WAIIDE-server/
/home/calliope/scripts/

Do Use: 

# New: WAIIDE at /ide
c.Spawner.default_url = '/ide'

# New: System paths
/opt/calliope/WAIIDE-server/
/opt/calliope/scripts/

Migration Steps

  1. Rebuild Images: Use the updated Dockerfile
  2. Update Task Definitions: Change from port 8080 to 8070
  3. Update Documentation: Reference /ide path for WAIIDE access
  4. Test Multi-User: Verify different users get isolated environments

Known Issues Fixed

  1. ✅ ECS boot failures with missing files
  2. ✅ Multi-user path conflicts
  3. ✅ Port inconsistencies in documentation
  4. ✅ Extension persistence issues
  5. ✅ Settings not persisting across restarts

Testing Checklist

  • Build completes without errors
  • Container starts with JUPYTERHUB_USER=testuser
  • WAIIDE accessible at /ide
  • Extensions persist after restart
  • Multiple users can run simultaneously
  • Files exist at /opt/calliope/ not /home/calliope/
WAIIDE ArchitectureWAIIDE Configuration