Documentation
Waiide
⚙️ Basic WAIIDE Setup

⚙️ Basic WAIIDE Setup

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

This guide shows you how to configure JupyterHub to work with WAIIDE, enabling multi-instance spawning with clean URLs.

📝 JupyterHub Configuration

Create Configuration File 

# Create JupyterHub config directory
sudo mkdir -p /etc/jupyterhub

# Create basic configuration file
sudo nano /etc/jupyterhub/jupyterhub_config.py

Basic Configuration

Add this to /etc/jupyterhub/jupyterhub_config.py:

# JupyterHub Configuration for WAIIDE
import os

# Basic hub configuration
c.JupyterHub.ip = '0.0.0.0'
c.JupyterHub.port = 8000

# Enable named servers (multi-instance support)
c.JupyterHub.allow_named_servers = True
c.JupyterHub.named_server_limit_per_user = 0  # Unlimited instances

# Configure the spawner
c.JupyterHub.spawner_class = 'dockerspawner.DockerSpawner'

# WAIIDE Docker image
c.DockerSpawner.image = 'calliopeai/waiide:latest'

# Named server configuration
c.DockerSpawner.name_template = '{servername}'  # Use server name as container name

# Environment variables passed to containers
c.DockerSpawner.environment = {
    'USE_ALL_COMPONENTS': 'true',
    'LOG_LEVEL': 'INFO',
}

# Network configuration
c.DockerSpawner.network_name = 'bridge'
c.DockerSpawner.remove = True  # Remove containers when they stop

# Default URL configuration - serve WAIIDE at root
c.Spawner.default_url = '/'

# Authentication (use PAM for simplicity in testing)
c.JupyterHub.authenticator_class = 'jupyterhub.auth.PAMAuthenticator'

# Cookie secret
c.JupyterHub.cookie_secret_file = '/etc/jupyterhub/cookie_secret'

# Logging
c.JupyterHub.log_level = 'INFO'

🔐 Authentication Setup

For Testing (PAM Authentication) 

# Create a test user
sudo useradd -m testuser
sudo passwd testuser  # Set a password

# Verify the user can authenticate
su - testuser
exit

For Production (OAuth) 

# Add to jupyterhub_config.py for OAuth (example with GitHub)
c.JupyterHub.authenticator_class = 'oauthenticator.GitHubOAuthenticator'
c.GitHubOAuthenticator.client_id = 'your-github-client-id'
c.GitHubOAuthenticator.client_secret = 'your-github-client-secret'
c.GitHubOAuthenticator.oauth_callback_url = 'http://your-domain:8000/hub/oauth_callback'

🚀 Starting JupyterHub

Basic Startup 

# Start JupyterHub
cd /etc/jupyterhub
sudo jupyterhub -f jupyterhub_config.py

As a Service (Systemd) 

# Create systemd service file
sudo nano /etc/systemd/system/jupyterhub.service

Add this content:

[Unit]
Description=JupyterHub
After=docker.service
Requires=docker.service

[Service]
User=root
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/usr/local/bin/jupyterhub -f /etc/jupyterhub/jupyterhub_config.py
WorkingDirectory=/etc/jupyterhub
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable jupyterhub
sudo systemctl start jupyterhub
sudo systemctl status jupyterhub

🧪 Testing Your Setup

1. Access JupyterHub

Open your browser and navigate to:

http://localhost:8000

2. Login

  • Username: testuser (or your created user)
  • Password: (the password you set)

3. Start a Named Server

  1. After logging in, you’ll see the JupyterHub control panel
  2. Click “New Server” or “Start New Server”
  3. Give your server a name (e.g., “waiide-dev”)
  4. Click “Start”

4. Verify WAIIDE Access

Your WAIIDE instance should be accessible at:

http://localhost:8000/user/testuser/testuser-waiide-dev/

You should see WAIIDE loading directly (no /WAIIDE/ in the URL).

🔍 Verification Checklist

  • JupyterHub starts without errors
  • Can login with test user
  • Can create named servers
  • WAIIDE loads at clean URL (no /WAIIDE/ path)
  • WAIIDE interface appears correctly
  • Can create multiple instances with different names

🐛 Common Issues

JupyterHub Won’t Start 

# Check the logs
sudo journalctl -u jupyterhub -f

# Common issue: Cookie secret file permissions
sudo chmod 600 /etc/jupyterhub/cookie_secret
sudo chown root:root /etc/jupyterhub/cookie_secret

Container Won’t Start 

# Check Docker logs
docker logs $(docker ps -a | grep testuser | awk '{print $1}')

# Check if image exists
docker images | grep waiide

# Try pulling the image again
docker pull calliopeai/waiide:latest

Can’t Access WAIIDE 

# Check if container is running
docker ps | grep testuser

# Check container logs
docker logs <container-name>

# Verify port mapping
docker port <container-name>

Authentication Issues 

# For PAM authentication, check user exists
id testuser

# Check PAM configuration
sudo cat /etc/pam.d/login

# For OAuth, verify environment variables
env | grep OAUTH

📊 Resource Usage

Monitor your setup:

# Check system resources
htop

# Check Docker resource usage
docker stats

# Check JupyterHub logs
sudo journalctl -u jupyterhub --since "1 hour ago"

🔧 Configuration Customization

Increase Memory Limits 

# Add to jupyterhub_config.py
c.DockerSpawner.mem_limit = '2G'  # 2GB memory limit
c.DockerSpawner.cpu_limit = 2     # 2 CPU cores

Custom Environment Variables 

# Add to jupyterhub_config.py
c.DockerSpawner.environment.update({
    'CUSTOM_VAR': 'value',
    'WAIIDE_THEME': 'pergamon-dark',
})

Volume Mounts 

# Add to jupyterhub_config.py
c.DockerSpawner.volumes = {
    '/home/{username}': '/home/calliope',
    '/shared': '/shared'
}

✅ Setup Complete

After completing this guide, you should have:

  • ✅ JupyterHub running and accessible
  • ✅ WAIIDE containers spawning correctly
  • ✅ Multi-instance support enabled
  • ✅ Clean URLs working (/user/username/server-name/)
  • ✅ Authentication working

➡️ Next Steps

Ready to create your first instance? Continue to First Instance →

Or jump to advanced topics:

📞 Need Help?

🎯 Your First WAIIDE Instance