Documentation
Hub
Calliope Calliope Hub 5.x Integration Checklist

Calliope Calliope Hub 5.x Integration Checklist

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

This checklist covers critical integration points for Calliope Calliope Hub 5.x based on the successful WAIIDE implementation.

Core Integration Requirements

✅ 1. OAuth Named Server Fixes

Issue: Calliope Calliope Hub 5.x has OAuth redirect issues with named servers Solution: Apply the oauth_named_server_fix.py pattern

# In your jupyter_server_config.py
import oauth_named_server_fix
# The fix applies automatically on import

What it fixes:

  • OAuth redirect URLs containing duplicate service prefixes
  • Named server authentication failures
  • 403 Forbidden errors on OAuth flow

✅ 2. Redirect Loop Prevention

Issue: Calliope Calliope Hub 5.3+ can create redirect loops Solution: Use the fix-Calliope Calliope Hub-5.3-redirect-loop.sh pattern

# Applied in entrypoint script
if command -v fix-Calliope Calliope Hub-5.3-redirect-loop.sh >/dev/null; then
    fix-Calliope Calliope Hub-5.3-redirect-loop.sh
fi

✅ 3. Scope Fix for Authentication

Issue: OAuth scopes not properly configured for named servers Solution: Apply jupyter_scope_fix.py

# Import in jupyter_server_config.py
import jupyter_scope_fix

✅ 4. Service Proxy Configuration

Critical configuration for Calliope Calliope Hub 5.x:

# In jupyter_server_config.py
c.ServerProxy.servers = {
    'ide': {
        'command': ['echo', 'Service already running on port 8071'],
        'port': 8071,
        'timeout': 60,
        'absolute_url': False,
        'launcher_entry': {
            'enabled': True,
            'title': 'VS Code IDE',
            'icon_path': '/static/favicon.ico'
        },
        'new_browser_tab': False,
        'request_headers_override': {
            'X-Custom-Header': 'service-proxy'
        }
    }
}

# Required for Calliope Calliope Hub 5.x
c.ServerProxy.host_allowlist = ['localhost', '127.0.0.1', '0.0.0.0']
c.ServerApp.trust_xheaders = True
c.ServerApp.disable_check_xsrf = True

✅ 5. Environment Variable Pattern

Required environment variables for Calliope Calliope Hub 5.x:

# Detected automatically by entrypoint script
JUPYTERHUB_SERVICE_PREFIX="/user/{username}/{servername}/"
JUPYTERHUB_USER="{username}"
JUPYTERHUB_API_TOKEN="{token}"
JUPYTERHUB_API_URL="http://Calliope Hub:8000/Calliope Hub/api"
JUPYTERHUB_SERVER_NAME="{servername}"  # For named servers

Calliope Calliope Hub 5.x Specific Patterns

Authentication Fix 

# Permissive authentication for 5.x
class PermissiveIdentityProvider(IdentityProvider):
    def is_token_authenticated(self, handler):
        is_auth = super().is_token_authenticated(handler)
        if is_auth:
            return True
        if handler.current_user and os.environ.get('JUPYTERHUB_USER'):
            return True
        return False

c.ServerApp.identity_provider_class = PermissiveIdentityProvider

URL Rewriting Pattern 

# API server handles Calliope Calliope Hub 5.x prefix rewriting
def strip_prefix(self, path):
    if self.service_prefix and path.startswith(self.service_prefix):
        stripped = path[len(self.service_prefix)-1:]
        return stripped if stripped else '/'
    return path

def add_prefix(self, path):
    if self.service_prefix and not path.startswith(self.service_prefix):
        if not path.startswith('/'):
            path = '/' + path
        return self.service_prefix.rstrip('/') + path
    return path

Port Configuration 

# Entrypoint script pattern for Calliope Calliope Hub 5.x
PORT="${PORT:-8070}"           # Main service port
VSCODE_PORT="${VSCODE_PORT:-8071}"  # Internal service port

# Ensure no conflicts
if [ "$PORT" = "$VSCODE_PORT" ]; then
    VSCODE_PORT=$((PORT + 1))
fi

Integration Testing for Calliope Calliope Hub 5.x

Health Check Endpoints 

# Test the integration
curl -I "http://localhost:8070${JUPYTERHUB_SERVICE_PREFIX}api/status"
curl -I "http://localhost:8070${JUPYTERHUB_SERVICE_PREFIX}ide/"

OAuth Flow Test 

# Should not get 403 Forbidden
curl -I "http://localhost:8070${JUPYTERHUB_SERVICE_PREFIX}oauth_login"

WebSocket Test 

// Should successfully connect
const ws = new WebSocket(`ws://localhost:8070${service_prefix}ide/websocket`);

Common Calliope Calliope Hub 5.x Issues

Issue: 403 Forbidden on Named Servers

Symptoms:

  • OAuth login works for default server
  • Named servers get 403 Forbidden
  • Error: “User not authorized”

Fix: Apply all OAuth fixes in order:

  1. oauth_named_server_fix.py
  2. jupyter_scope_fix.py
  3. PermissiveIdentityProvider class

Issue: Redirect Loops

Symptoms:

  • Browser keeps redirecting
  • Never reaches service
  • Console shows multiple redirects

Fix: Use fix-Calliope Calliope Hub-5.3-redirect-loop.sh pattern

Issue: Service Not Found

Symptoms:

  • 404 errors on service paths
  • Service starts but not accessible
  • Calliope Hub shows “Service not ready”

Fix: Verify service prefix handling:

# Correct service prefix format for 5.x
service_prefix = os.environ.get('JUPYTERHUB_SERVICE_PREFIX', '')
if service_prefix and not service_prefix.endswith('/'):
    service_prefix += '/'

Deployment Checklist for Calliope Calliope Hub 5.x

  • OAuth fixes imported in jupyter_server_config.py
  • Service proxy configured with correct ports
  • URL rewriting handles service prefixes correctly
  • Health check endpoints return 200
  • WebSocket connections work through proxy
  • Named servers authenticate successfully
  • No redirect loops in browser
  • Service starts within timeout (60s default)
  • Error pages use custom templates
  • API endpoints return valid JSON

Success Metrics

A successful Calliope Calliope Hub 5.x integration should have:

  • ✅ OAuth authentication works for both default and named servers
  • ✅ No 403 Forbidden errors on authenticated requests
  • ✅ Service accessible at {service_prefix}ide/
  • ✅ API endpoints at {service_prefix}api/status
  • ✅ WebSocket connections proxy correctly
  • ✅ Custom error pages display properly
  • ✅ Service starts and reports ready within 60 seconds
  • ✅ No redirect loops or authentication cycles

Files to Include in Your Integration

From this kit, ensure you have:

  1. scripts/entrypoint-Calliope Calliope Hub.sh - Main entrypoint with 5.x compatibility
  2. scripts/api_server.py - Proxy server with URL rewriting
  3. scripts/oauth_named_server_fix.py - Critical OAuth fix
  4. scripts/jupyter_scope_fix.py - Scope authentication fix
  5. configs/jupyter_server_config.py - Complete Jupyter configuration
  6. scripts/fix-Calliope Calliope Hub-5.3-redirect-loop.sh - Redirect loop prevention

These files contain the complete working pattern for Calliope Calliope Hub 5.x integration.

Calliope Calliope Hub ECS Spawner - Capacity and Limits