WAIIDE JupyterHub Integration Troubleshooting Guide

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

Common Issues and Solutions

1. 404 Errors When Accessing WAIIDE

Symptom: Getting 404 errors for static resources when accessing WAIIDE through JupyterHub.

Solution: Make sure you’re accessing WAIIDE through the correct URL pattern:

• ✅ Correct: http://hub.example.com/user/{username}/proxy/8081/
• ❌ Wrong: http://hub.example.com/user/{username}/waiide/

The /proxy/8081/ path tells jupyter-server-proxy to strip the JupyterHub prefix before forwarding to WAIIDE.

2. Permission Denied Errors

Symptom: Container fails with permission errors like:

PermissionError: [Errno 13] Permission denied: '/home/lmata/.local/share/jupyter/runtime/jupyter_cookie_secret'

Solution: Ensure the container starts as root:

c.DockerSpawner.extra_create_kwargs = {'user': 'root'}

The entrypoint script will:

1. Create necessary directories
2. Fix ownership to 1000:100
3. Drop privileges to the non-root user

3. WAIIDE Not Loading

Symptom: Blank page or connection errors when trying to access WAIIDE.

Debug Steps:

1. Check container logs:

docker logs {username}-waiide-{id}

2. Verify WAIIDE is running on port 8081:

docker exec {container-id} curl -I http://127.0.0.1:8081

3. Check jupyterhub-singleuser is running:

docker exec {container-id} ps aux | grep jupyter

4. Wrong Port Configuration

Symptom: WAIIDE is unreachable or proxy errors.

Solution: Ensure port configuration is correct:

• WAIIDE Server: Port 8081 (internal)
• JupyterHub SingleUser: Port 8080 (exposed)
• Access URL uses: /proxy/8081/

5. Debugging Commands

Run these commands inside the container to debug:

# Check running processes
ps aux

# Check listening ports
netstat -tlnp

# Test WAIIDE directly
curl http://127.0.0.1:8081

# Check environment variables
env | grep JUPYTER

# View jupyter-server-proxy logs
jupyter server extension list

6. Container Startup Sequence

The correct startup sequence should be:

1. Container starts as root
2. Entrypoint script fixes permissions
3. Drops to user 1000 (calliope)
4. Starts WAIIDE Server on port 8081
5. Starts jupyterhub-singleuser with jupyter-server-proxy on port 8080
6. User accesses via /user/{username}/proxy/8081/

7. Testing Without JupyterHub

To test the container standalone:

docker run -it --rm \
  -p 8080:8080 \
  -e USE_ALL_COMPONENTS=true \
  calliopeai/waiide:latest

Access at: http://localhost:8080/ (uses custom API server in standalone mode)

8. Logs to Look For

Good startup logs:

🔐 Detected JupyterHub user: lmata
🔧 Running as root - fixing permissions...
🔐 Setting ownership to 1000:100 for /home/lmata
👤 Dropping to user 1000...
🚀 Starting WAIIDE Server on port 8081
📦 Starting jupyterhub-singleuser with jupyter-server-proxy on port 8080
🔗 jupyter-server-proxy handles path rewriting automatically

9. JupyterHub Configuration Checklist

• Using DockerSpawner
• Image set to calliopeai/waiide:latest
• Container starts as root: extra_create_kwargs = {'user': 'root'}
• Volume mounted at /home/{username}
• Network configured correctly
• Default URL set to /proxy/8081/ (optional)

10. Known Limitations

• Must access WAIIDE via /proxy/8081/ path
• Custom /waiide/ path requires additional nginx configuration
• WebSocket connections require proper proxy configuration in JupyterHub