📚 WAIIDE Documentation

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

Complete guide to WAIIDE (Web AI IDE) - A JupyterHub-integrated WAIIDE Server environment

🚀 Quick Navigation

For New Users

• Quick Start - Get WAIIDE running in 5 minutes
• Quickstart Guide - Alternative quick setup guide
• Overview - What is WAIIDE and why use it?
• Getting Started Guide - Step-by-step setup

For Administrators

• Configuration - JupyterHub setup, environment variables, ECS
• Deployment - Docker, ECS, Kubernetes deployment guides
• Architecture - System design and integration patterns

For Developers

• Development - Building extensions, contributing, testing
• API Reference - API documentation and endpoints
• Color Palette - Official CalliopeAI brand colors and theme guide
• Theme Alignment - Pergamon theme color mapping and guidelines
• Reference Materials - Patterns, blueprints, and technical details

For Troubleshooting

• Troubleshooting - Common issues and solutions

📖 Documentation Structure

🎯 Getting Started

Perfect for first-time users and quick deployments:

getting-started/
├── installation.md         # Prerequisites and installation
├── basic-setup.md          # Basic JupyterHub integration  
└── first-instance.md       # Creating your first WAIIDE instance

⚙️ Configuration

Complete configuration reference for all deployment scenarios:

configuration/
├── README.md               # Configuration hub and overview
├── jupyterhub-setup.md     # JupyterHub configuration guide
├── environment-variables.md # Complete environment variable reference
├── ecs-instance-names.md   # ECS spawner instance naming
└── examples/               # Configuration examples
    └── hub_config.py       # Example JupyterHub configuration

🚀 Deployment

Production deployment guides for different platforms:

deployment/
├── README.md              # Deployment overview and comparison
├── docker.md              # Docker and Docker Compose setup
├── ecs.md                 # AWS ECS deployment guide
├── kubernetes.md          # Kubernetes deployment guide
└── quick-start.md         # Quick deployment for testing

🏗️ Architecture

Deep dive into WAIIDE’s design and integration patterns:

architecture/
├── README.md              # Architecture overview
├── system-overview.md     # High-level system design
├── multi-instance.md      # Multi-instance architecture
├── authentication.md      # OAuth and security model
├── networking.md          # Port configuration and networking
└── integration-flow.md    # JupyterHub integration flow

🛠️ Development

Resources for developers and contributors:

development/
├── README.md              # Development overview
├── building-extensions.md # CalliopeAI extension development
├── plugin-integration.md  # Plugin architecture and integration
├── testing.md             # Testing framework and procedures
└── contributing.md        # Contribution guidelines

🔧 Troubleshooting

Comprehensive problem-solving resources:

troubleshooting/
├── README.md              # Troubleshooting hub
├── common-issues.md       # Most frequent issues and solutions
├── oauth-issues.md        # Authentication troubleshooting
└── debugging.md           # Debugging tools and techniques

📋 Reference

Technical reference materials and patterns:

reference/
├── patterns/              # Integration patterns and blueprints
│   ├── jupyterhub-integration.md
│   └── generic-blueprint.md
├── waiide/               # WAIIDE-specific documentation
│   ├── integration-summary.md
│   └── llm-blueprint.md
└── ports-configuration.md # Port configuration reference

🎯 Key Concepts

Multi-Instance Architecture

WAIIDE supports running multiple isolated instances per user with unique, hashed names:

• Clean URLs: /user/username/username-waiide-abc123/
• Instance Isolation: Each instance runs independently
• Unlimited Instances: No artificial limits on concurrent instances

Root URL Serving

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

• No /WAIIDE/ paths: Direct access to the IDE
• No /proxy/port/ complexity: Clean, intuitive URLs
• Seamless Integration: Transparent JupyterHub integration

Modern JupyterHub Integration

Built for contemporary JupyterHub deployments:

• Named Servers: Full support for JupyterHub named servers
• OAuth Authentication: Secure, token-based authentication
• Service Discovery: Automatic service registration and discovery

📞 Getting Help

1. Check Troubleshooting - Most issues have known solutions
2. Review Configuration - Ensure proper setup
3. Consult Architecture - Understand the system design
4. Read Quick Start - Verify basic setup steps

🔄 Documentation Updates

This documentation reflects the modern multi-instance architecture with:

• ✅ Unique hashed server names (username-waiide-abc123)
• ✅ Clean root URL serving (/user/username/server-name/)
• ✅ Comprehensive ECS spawner integration
• ✅ Updated environment variable patterns
• ✅ Current JupyterHub best practices

Last updated: January 2025