Documentation
Waiide
🛠️ WAIIDE Development Guide

🛠️ WAIIDE Development Guide

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

Welcome to the WAIIDE development documentation. This section covers everything you need to build, extend, and contribute to WAIIDE.

🚀 Quick Start for Developers

Prerequisites

  • Docker: For building and testing
  • Node.js 16+: For WAIIDE extension development
  • Python 3.8+: For JupyterHub integration
  • Git: With submodules support

Get Started 

# Clone with submodules
git clone --recurse-submodules https://github.com/CalliopeAI/calliope-WAIIDE.git
cd calliope-WAIIDE

# Build the image
./build.sh build

# Run tests
./build.sh test

📚 Development Guides

Building Extensions

Complete guide to building CalliopeAI WAIIDE extensions:

  • Extension architecture and structure
  • Build process and packaging
  • Integration with WAIIDE container
  • Testing and debugging extensions

Plugin Integration

How to integrate plugins and extensions into WAIIDE:

  • CalliopeAI Agent integration
  • Custom extension development
  • Theme integration (Pergamon)
  • Extension marketplace compatibility

Testing Framework

Comprehensive testing approaches for WAIIDE:

  • Unit testing strategies
  • Integration testing with JupyterHub
  • Container testing workflows
  • CI/CD testing pipeline

Contributing Guidelines

How to contribute to the WAIIDE project:

  • WAIIDE style and standards
  • Pull request process
  • Issue reporting and triage
  • Development workflow

🏗️ Architecture for Developers

Container Architecture 

WAIIDE Container
├── WAIIDE Server (port 8071)     # Core IDE functionality
├── Jupyter Server (port 8080)     # JupyterHub integration
├── API Server (scripts/)          # Custom API endpoints
└── Entrypoint (entrypoint-*.sh)   # Orchestration logic

Key Components

WAIIDE Server

  • Base: Open-source WAIIDE Server
  • Extensions: CalliopeAI Agent, Pergamon theme
  • Configuration: Custom settings and keybindings
  • Integration: WebSocket and HTTP communication

Jupyter Integration

  • jupyter-server-proxy: Proxies WAIIDE through Jupyter
  • jupyterhub-singleuser: Handles authentication and lifecycle
  • Custom handlers: Root URL redirection and routing

API Server

  • Health checks: Container and service status
  • Proxy management: URL rewriting and request routing
  • Environment detection: JupyterHub vs standalone mode

🔧 Development Workflows

Local Development 

# Development with live reloading
./scripts/dev-setup.sh

# Run in development mode (default ports)
docker run -it --rm -p 8070:8070 \
  -v $(pwd):/workspace \
  -e DEV_MODE=true \
  calliopeai/waiide:latest

# Run with override port if needed
docker run -it --rm -p 8080:8080 \
  -v $(pwd):/workspace \
  -e DEV_MODE=true \
  -e PORT=8080 \
  calliopeai/waiide:latest

Extension Development 

# Build extensions only
cd calliope-WAIIDE-agent
npm run build

# Package extensions
npm run package

# Install in container
docker cp extension.vsix container:/extensions/

Testing Locally 

# Test with JupyterHub simulation (default ports)
docker run -it --rm -p 8070:8070 \
  -e JUPYTERHUB_USER=testdev \
  -e JUPYTERHUB_SERVICE_PREFIX=/user/testdev/testdev-dev/ \
  calliopeai/waiide:latest

# Test with port override
docker run -it --rm -p 8080:8080 \
  -e PORT=8080 \
  -e JUPYTERHUB_USER=testdev \
  -e JUPYTERHUB_SERVICE_PREFIX=/user/testdev/testdev-dev/ \
  calliopeai/waiide:latest

# Test standalone mode (default ports)
docker run -it --rm -p 8070:8070 \
  -e STANDALONE_MODE=true \
  calliopeai/waiide:latest

🧪 Development Tools

Build Scripts

  • build.sh: Main build orchestration
  • scripts/build-calliope-extensions.sh: Extension building
  • scripts/package.js: Container packaging

Testing Tools

  • scripts/test-ci.js: CI/CD testing
  • Docker Compose: Multi-service testing
  • WAIIDE Test Runner: Extension testing

Debugging Tools

  • scripts/debug_live_container.sh: Live container debugging
  • WAIIDE Remote: Container development
  • Browser DevTools: Frontend debugging

📦 Build Process

Multi-Stage Docker Build 

# Stage 1: WAIIDE compilation
FROM node:16 AS WAIIDE-builder
# Build WAIIDE from source

# Stage 2: Extension building  
FROM node:16 AS extension-builder
# Build CalliopeAI extensions

# Stage 3: Runtime assembly
FROM ubuntu:22.04 AS runtime
# Assemble final container

Extension Integration

  • Extensions built in separate stage
  • Packaged as .vsix files
  • Installed during container build
  • Activated on WAIIDE startup

Theme Integration

  • Pergamon theme from separate repository
  • Built and packaged during build
  • Applied as default theme
  • Customizable via environment variables

🔍 Debugging and Troubleshooting

Container Debugging 

# Access running container
docker exec -it <container> /bin/bash

# Check service status
docker logs <container>

# Debug specific service
docker exec -it <container> ps aux | grep WAIIDE

Extension Debugging 

# Enable extension debugging
-e VSCODE_LOG_LEVEL=debug

# Check extension logs
docker exec -it <container> cat /home/calliope/.WAIIDE-server-oss/logs/*

Network Debugging 

# Check port bindings
docker port <container>

# Test internal connectivity
docker exec -it <container> curl localhost:8071
docker exec -it <container> curl localhost:8080

🚀 Performance Optimization

Build Optimization

  • Multi-stage builds: Reduce final image size
  • Layer caching: Optimize Docker layer reuse
  • Parallel builds: Use build-arg for parallelization

Runtime Optimization

  • Resource limits: Configure memory/CPU limits
  • Extension lazy loading: Load extensions on demand
  • Caching strategies: Cache frequently accessed data

Development Efficiency

  • Volume mounts: Live reload during development
  • Image layering: Optimize rebuild times
  • Test parallelization: Run tests concurrently

📊 Metrics and Monitoring

Build Metrics

  • Build time tracking
  • Image size optimization
  • Layer efficiency analysis

Runtime Metrics

  • Container resource usage
  • WAIIDE performance metrics
  • Extension load times

User Experience Metrics

  • Startup time measurement
  • Response time tracking
  • Error rate monitoring

🔄 Release Process

Version Management

  • Semantic versioning (semver)
  • Git tags for releases
  • Changelog generation

CI/CD Pipeline

  • Automated testing on PRs
  • Multi-architecture builds
  • Security scanning

Distribution

  • Docker Hub publishing
  • GitHub releases
  • Documentation updates

📝 WAIIDE Standards

Python WAIIDE

  • Style: PEP 8 compliance
  • Docstrings: Google style docstrings
  • Testing: pytest framework
  • Linting: flake8, black, isort

JavaScript/TypeScript

  • Style: ESLint configuration
  • Testing: Jest framework
  • Build: webpack/vite
  • Types: Strict TypeScript

Shell Scripts

  • Style: shellcheck compliance
  • Error handling: set -e, set -u
  • Logging: Structured logging
  • Portability: POSIX compatibility where possible

💡 Advanced Topics

Custom Spawners

  • ECS spawner integration
  • Kubernetes spawner support
  • Custom spawner development

Authentication Integration

  • OAuth provider setup
  • Custom authenticator development
  • Token management

Scaling Considerations

  • Multi-instance architecture
  • Resource management
  • Load balancing strategies

📞 Developer Support

Getting Help

  • Issues: GitHub issue tracker
  • Discussions: GitHub discussions
  • WAIIDE Review: Pull request feedback
  • Documentation: This documentation site

Contributing

  • WAIIDE: Follow the contribution guidelines
  • Docs: Help improve documentation
  • Testing: Add test coverage
  • Issues: Report bugs and feature requests

Ready to start developing? Begin with Building Extensions →

📄 Developer Resources

WAIIDE_TECHNICAL_BLUEPRINT_V1🤝 Contributing to WAIIDE