WAIIDE Port Configuration & Architecture

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

This document explains the port configuration for WAIIDE (Web AI IDE) and what ports are needed in different deployment scenarios.

🎯 Default Port Architecture

WAIIDE uses Dockerfile build arguments to configure default ports:

ARG JUPYTERHUB_PORT=8070  # Main service port (Jupyter Server)
ARG VSCODE_PORT=8071      # Internal WAIIDE Server port

Component	Default Port	Override Env	Access	Purpose
Main Service	`8070`	`PORT` or `JUPYTERHUB_PORT`	External	Primary endpoint (JupyterHub/API)
WAIIDE Server	`8071`	`VSCODE_PORT`	Internal	Core IDE (proxied through main service)

🔧 Port Configuration by Mode

JupyterHub Mode (`JUPYTERHUB_SERVICE_PREFIX` set)

External Request → Port 8070 → JupyterHub SingleUser → Jupyter Server Proxy → WAIIDE (localhost:8071)

Components:

jupyterhub-singleuser listens on port 8070 (external, default)
WAIIDE-server runs on localhost:8071 (internal, default)
jupyter-server-proxy routes to WAIIDE

Default Exposed Ports: 8070 only

Standalone Mode (`JUPYTERHUB_SERVICE_PREFIX` not set)

External Request → Port 8070 → Custom API Server → WAIIDE (localhost:8071) or API endpoints

Components:

api_server.py listens on port 8070 (external, default)
WAIIDE-server auto-started on localhost:8071 (internal, default)
API server proxies non-API requests to WAIIDE

Default Exposed Ports: 8070 only

📡 Port Mappings for Different Deployments

Docker Run

# Basic deployment with defaults (JupyterHub integration)
docker run -p 8070:8070 calliopeai/waiide:latest

# Override to port 8080 (common alternative)
docker run -p 8080:8080 -e PORT=8080 calliopeai/waiide:latest

# Custom port mapping with WAIIDE port override
docker run -p 8070:8070 -e VSCODE_PORT=8072 calliopeai/waiide:latest

# Direct WAIIDE access (not recommended in production)
docker run -p 8070:8070 -p 8071:8071 calliopeai/waiide:latest

Docker Compose

version: '3.8'
services:
  waiide:
    image: calliopeai/waiide:latest
    ports:
      - "8070:8070"    # Main service (default)
    environment:
      - JUPYTERHUB_USER=testuser
      - JUPYTERHUB_SERVICE_PREFIX=/user/testuser/testuser-waiide-abc123/
    # Optional port overrides:
    # environment:
    #   - PORT=8080         # Override main service port
    #   - VSCODE_PORT=8072  # Override WAIIDE port
    # ports:
    #   - "8080:8080"       # Match the PORT override

Kubernetes

apiVersion: v1
kind: Service
metadata:
  name: waiide-service
spec:
  selector:
    app: waiide
  ports:
    - name: main
      port: 8070        # Default port
      targetPort: 8070
      protocol: TCP
    # Optional: Direct WAIIDE access
    # - name: WAIIDE
    #   port: 8071
    #   targetPort: 8071
    #   protocol: TCP

🌐 Network Architecture

Internal Routing

Container Internal Network:
┌─────────────────────────────┐
│ Port 8070: Jupyter Server   │ ← External traffic
│ ├─ Authentication           │
│ ├─ Proxy management         │
│ └─ API endpoints            │
├─────────────────────────────┤
│ Port 8071: WAIIDE Server   │ ← Internal only
│ ├─ WebSocket connections    │
│ ├─ File operations          │
│ └─ Extension host           │
└─────────────────────────────┘

External Access Patterns

# JupyterHub URL patterns
/user/username/username-waiide-abc123/          → Main service (8070)
/user/username/username-waiide-abc123/proxy/8071/ → WAIIDE (proxied)

# Standalone URL patterns  
http://localhost:8070/          → Main service
http://localhost:8070/api/      → API endpoints
http://localhost:8070/          → WAIIDE (proxied)

⚙️ Port Override Examples

Environment Variable Priority

# Priority order (highest to lowest):
1. PORT=8080              # Overrides main service port
2. JUPYTERHUB_PORT=8070   # Default main service port
3. Dockerfile ARG         # Build-time default (8070)

# WAIIDE port:
1. VSCODE_PORT=8072       # Override WAIIDE port
2. Dockerfile ARG         # Build-time default (8071)

Common Override Scenarios

# Scenario 1: Use familiar port 8080
docker run -p 8080:8080 -e PORT=8080 calliopeai/waiide:latest

# Scenario 2: Avoid port conflicts
docker run -p 9000:9000 -e PORT=9000 calliopeai/waiide:latest

# Scenario 3: Custom WAIIDE port
docker run -p 8070:8070 -e VSCODE_PORT=8888 calliopeai/waiide:latest

# Scenario 4: Both ports custom
docker run -p 9000:9000 -e PORT=9000 -e VSCODE_PORT=9001 calliopeai/waiide:latest

🔍 Port Verification & Testing

Check Port Status

# Inside container
netstat -tlnp | grep -E ':(8070|8071)'
ss -tlnp | grep -E ':(8070|8071)'

# From host
docker port <container_name>
curl -I http://localhost:8070/health

Test Connectivity

# Health check (main service)
curl http://localhost:8070/health

# API status
curl http://localhost:8070/api/status

# WAIIDE access (through proxy)
curl -I http://localhost:8070/proxy/8071/

Debug Port Issues

# Check what's listening
docker exec -it <container> netstat -tlnp

# Check environment variables
docker exec -it <container> env | grep -E '(PORT|VSCODE_PORT|JUPYTERHUB_PORT)'

# Check process status
docker exec -it <container> ps aux | grep -E '(jupyter|WAIIDE|python)'

🚨 Common Port Issues & Solutions

Port Already in Use

# Problem: Port 8070 is already bound
Error: bind: address already in use

# Solutions:
1. Use different port: docker run -p 8080:8080 -e PORT=8080 ...
2. Stop conflicting service: lsof -i :8070
3. Use random port: docker run -P calliopeai/waiide:latest

Cannot Access WAIIDE

# Problem: WAIIDE not accessible
# Check WAIIDE server is running:
docker exec -it <container> curl localhost:8071

# Check proxy configuration:
docker logs <container> | grep -i proxy

Wrong Port in URLs

# Problem: JupyterHub generates wrong URLs
# Ensure spawner configuration matches container ports:
c.DockerSpawner.port = 8070  # Match JUPYTERHUB_PORT default
# Or use PORT override:
c.DockerSpawner.environment = {'PORT': '8080'}

📋 Production Recommendations

Security

Never expose WAIIDE port directly in production
Use reverse proxy (nginx, traefik) for SSL termination
Firewall rules to restrict access to main service port only

Performance

Stick to defaults when possible (8070/8071)
Use port overrides only when necessary
Monitor port usage with container metrics

Monitoring

# Essential port monitoring
curl -f http://localhost:8070/health || exit 1
curl -f http://localhost:8070/api/status || exit 1

# Container resource monitoring
docker stats <container_name>

📚 Related Documentation

Architecture Overview - System design and components
Environment Variables - Complete variable reference
Deployment Guide - Production deployment patterns
Troubleshooting - Common issues and solutions

🎯 Summary

Default Configuration

Main Service: Port 8070 (JUPYTERHUB_PORT)
WAIIDE Server: Port 8071 (VSCODE_PORT)
Override: Use PORT and VSCODE_PORT environment variables

Best Practices

Use default ports unless you have specific requirements
Override with PORT=8080 for familiarity
Never expose WAIIDE port directly in production
Always test port configuration before deploying

Quick Reference

# Default setup
docker run -p 8070:8070 calliopeai/waiide:latest

# Common override
docker run -p 8080:8080 -e PORT=8080 calliopeai/waiide:latest

# Health check
curl http://localhost:8070/health

WAIIDE OAuth Workaround for Named Servers WAIIDE Port Summary