Documentation
Waiide
Quick Start Guide

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 running in under 5 minutes!

Prerequisites

  • Docker 20.10+ installed
  • (For JupyterHub) JupyterHub 3.0+ with DockerSpawner

Standalone Deployment (Development)

1. Run the container 

docker run -d \
  --name waiide \
  -p 8070:8070 \
  calliopeai/waiide:latest

2. Access WAIIDE

Open http://localhost:8070 in your browser.

3. Check health 

curl http://localhost:8070/api/services

JupyterHub Deployment

1. Create Docker network 

docker network create jupyterhub-network

2. Add to jupyterhub_config.py 

c.JupyterHub.spawner_class = 'dockerspawner.DockerSpawner'
c.DockerSpawner.image = 'calliopeai/waiide:latest'
c.DockerSpawner.network_name = 'jupyterhub-network'
c.DockerSpawner.volumes = {
    'jupyterhub-user-{username}': '/home/{username}'
}
c.Spawner.default_url = '/ide'

3. Start JupyterHub 

jupyterhub -f jupyterhub_config.py

4. Login and spawn

  1. Navigate to http://localhost:8000
  2. Login with your credentials
  3. Start your server
  4. Automatically redirected to WAIIDE!

Docker Compose Deployment

1. Create docker-compose.yml 

version: '3.8'

services:
  jupyterhub:
    image: jupyterhub/jupyterhub:4
    container_name: jupyterhub
    ports:
      - "8000:8000"
    volumes:
      - ./jupyterhub_config.py:/srv/jupyterhub/jupyterhub_config.py
    environment:
      DOCKER_NETWORK_NAME: jupyterhub-network
    networks:
      - jupyterhub-network

networks:
  jupyterhub-network:
    name: jupyterhub-network

2. Start services 

docker-compose up -d

Kubernetes Deployment

1. Create namespace 

kubectl create namespace jupyterhub

2. Install with Helm 

helm repo add jupyterhub https://jupyterhub.github.io/helm-chart/
helm repo update

helm install jupyterhub jupyterhub/jupyterhub \
  --namespace jupyterhub \
  --values values.yaml

3. values.yaml configuration 

singleuser:
  image:
    name: calliopeai/waiide
    tag: latest
  defaultUrl: "/proxy/8081/"
  storage:
    dynamic:
      storageClass: standard
  cpu:
    limit: 2
    guarantee: 0.5
  memory:
    limit: 4G
    guarantee: 1G

Verify Installation

Check container status 

# Docker
docker ps | grep waiide

# Kubernetes
kubectl get pods -n jupyterhub

Test API endpoints 

# Standalone
curl http://localhost:8080/api

# JupyterHub (from inside network)
curl http://jupyter-username:8080/api

Check logs 

# Docker
docker logs waiide

# JupyterHub spawned container
docker logs jupyter-username

Common Issues

Container exits immediately

  • Check logs: docker logs waiide
  • Ensure port 8080 is not in use

Can’t access WAIIDE

  • Wait 15-20 seconds for initialization
  • Check firewall rules for port 8080

JupyterHub spawn fails

  • Verify Docker network exists
  • Check spawner configuration
  • Ensure image is pulled: docker pull calliopeai/waiide:latest

Next Steps

JupyterHub WAIIDE Spawning Issues - FixedTroubleshooting ECS Boot Errors