🔧 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-pluginCentOS/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 $USERmacOS
# 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 --versionOption 2: Using conda
# Install JupyterHub
conda install -c conda-forge jupyterhub
conda install -c conda-forge dockerspawner
conda install -c conda-forge jupyter-server-proxyOption 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 waiideBuild 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_secretConfigure 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/tcpConfigure 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 versionTest 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 sessionPort 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?
- Docker Issues: Check Docker’s official documentation
- JupyterHub Issues: See JupyterHub documentation
- WAIIDE Issues: Check our Troubleshooting Guide