🔧 Installing WAIIDE

🔧 Installing WAIIDE

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

This guide covers everything you need to install and prepare WAIIDE for use with JupyterHub.

📋 Prerequisites

System Requirements

  • Operating System: Linux (Ubuntu/RHEL/CentOS), macOS, or Windows with WSL2
  • RAM: Minimum 2GB, recommended 4GB+ per WAIIDE instance
  • Storage: 10GB+ available disk space
  • Network: Outbound internet access for image pulls

Required Software

  • Docker: Version 20.10+ with Docker Compose
  • Python: Version 3.8+ (for JupyterHub)
  • Node.js: Version 16+ (if building from source)

🐳 Docker Installation

Ubuntu/Debian

# Update package index
sudo apt update

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Install Docker Compose
sudo apt install docker-compose-plugin

CentOS/RHEL

# Install Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group
sudo usermod -aG docker $USER

macOS

# Install Docker Desktop
brew install --cask docker

# Or download from: https://www.docker.com/products/docker-desktop

🎡 JupyterHub Installation

Option 1: Using pip (Recommended)

# Create virtual environment
python3 -m venv jupyterhub-env
source jupyterhub-env/bin/activate

# Install JupyterHub
pip install jupyterhub
pip install dockerspawner  # For Docker spawning
pip install jupyter-server-proxy  # For proxy support

# Verify installation
jupyterhub --version

Option 2: Using conda

# Install JupyterHub
conda install -c conda-forge jupyterhub
conda install -c conda-forge dockerspawner
conda install -c conda-forge jupyter-server-proxy

Option 3: System packages (Ubuntu)

# Install from system packages
sudo apt install python3-pip nodejs npm
sudo pip3 install jupyterhub dockerspawner jupyter-server-proxy

📦 WAIIDE Image Setup

Pull Pre-built Image

# Pull the latest WAIIDE image
docker pull calliopeai/waiide:latest

# Verify the image
docker images | grep waiide

Build from Source (Optional)

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

# Build the image
./build.sh build

# Tag for local use
docker tag calliopeai/waiide:latest waiide:local

🔐 Authentication Setup

Create JupyterHub Cookie Secret

# Generate cookie secret
openssl rand -hex 32 > /etc/jupyterhub/cookie_secret

# Set proper permissions
sudo chmod 600 /etc/jupyterhub/cookie_secret

Configure OAuth (Optional)

For production deployments, configure OAuth with your identity provider:

# Example environment variables
export JUPYTERHUB_CRYPT_KEY=$(openssl rand -hex 32)
export OAUTH_CLIENT_ID="your-client-id"
export OAUTH_CLIENT_SECRET="your-client-secret"

🌐 Network Configuration

Open Required Ports

# JupyterHub web interface
sudo ufw allow 8000/tcp

# Container communication (internal)
sudo ufw allow 8080/tcp
sudo ufw allow 8071/tcp

Configure Docker Networks

# Create a dedicated network for WAIIDE
docker network create waiide-network

✅ Verification

Test Docker

# Test Docker installation
docker run --rm hello-world

# Test Docker Compose
docker compose version

Test JupyterHub

# Test JupyterHub installation
jupyterhub --version
python -c "import dockerspawner; print('DockerSpawner:', dockerspawner.__version__)"

Test WAIIDE Image

# Test WAIIDE image
docker run --rm calliopeai/waiide:latest echo "WAIIDE image ready"

📁 Directory Structure

Create the recommended directory structure:

# Create JupyterHub directories
sudo mkdir -p /etc/jupyterhub
sudo mkdir -p /var/log/jupyterhub
sudo mkdir -p /opt/waiide

# Set permissions
sudo chown -R $(whoami):$(whoami) /opt/waiide

🚨 Common Issues

Docker Permission Denied

# If you get permission denied errors
sudo usermod -aG docker $USER
newgrp docker
# Or restart your session

Port Already in Use

# Check what's using a port
sudo netstat -tulpn | grep :8000
sudo lsof -i :8000

# Kill the process if needed
sudo kill -9 <PID>

Image Pull Failures

# Try with explicit registry
docker pull docker.io/calliopeai/waiide:latest

# Or build locally if pull fails
git clone --recurse-submodules https://github.com/CalliopeAI/calliope-WAIIDE.git
cd calliope-WAIIDE && ./build.sh build

📝 Installation Summary

After completing this guide, you should have:

  • ✅ Docker and Docker Compose installed
  • ✅ JupyterHub with required plugins installed
  • ✅ WAIIDE container image available
  • ✅ Basic authentication configured
  • ✅ Network and directories set up

➡️ Next Steps

Ready for configuration? Continue to Basic Setup →

📞 Need Help?