JupyterHub Integration Implementation Checklist

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

Pre-Implementation Planning

• Identify Original Service: What service are you integrating?
• Current Port: What port does your service currently use?
• Service Type: Web app, API, desktop app with web interface?
• WebSocket Needs: Does your service use WebSockets?
• URL Complexity: Does your service generate complex URLs that need rewriting?

Core Implementation (Required)

1. Environment Detection Script

• Create entrypoint-jupyterhub.sh (~250 lines)
• Implement JupyterHub environment detection
• Add permission handling (root → drop privileges)
• Create dual-mode startup logic
• Add proper signal handling and cleanup

2. API Server with Proxy

• Create api_server.py (~500 lines)
• Implement JupyterHub-compatible API endpoints
• Add URL prefix stripping functionality
• Implement content rewriting for HTML/CSS/JS
• Add WebSocket upgrade handling (if needed)
• Implement health checking for original service

3. Jupyter Server Configuration

• Create jupyter_server_config.py (~100 lines)
• Configure jupyter-server-proxy for your service
• Set up permissive authentication
• Configure URL routing and redirects

4. Dockerfile Updates

• Add JupyterHub dependencies (jupyterhub, jupyter-server-proxy)
• Set standard Jupyter UID/GID (1000:100)
• Copy integration scripts to /usr/local/bin/
• Expose both ports (8080, 8081)
• Change entrypoint to use orchestration script

OAuth Fixes (If Using Named Servers)

5. OAuth URL Fixes

• Create oauth_named_server_fix.py (~100 lines)
• Implement redirect URL correction
• Handle service prefix removal from hub URLs

6. OAuth Scope Fixes

• Create jupyter_scope_fix.py (~100 lines)
• Implement scope patching for named servers
• Add proper server access permissions

Testing Implementation

7. Unit Tests

• Create test_api.py - Test API endpoints
• Create test_entrypoint.py - Test startup logic
• Create test_url_rewriting.py - Test URL rewriting
• Create test_unit.py - Test core functions
• Create run_tests.py - Test runner

8. Integration Tests

• Test standalone mode startup
• Test JupyterHub mode startup
• Test API compatibility
• Test URL path handling
• Test WebSocket connections (if applicable)

Documentation (Recommended)

9. Configuration Guides

• Create JupyterHub spawner configuration guide
• Document environment variables
• Create quick start guide

10. Troubleshooting Guides

• Document common issues and solutions
• Create debugging command reference
• Document OAuth troubleshooting

Service-Specific Adaptations

For Web Applications

• Identify all URL patterns that need rewriting
• Test with different browsers
• Verify CORS headers are correct
• Test WebSocket connections

For API Services

• Ensure API endpoints don’t conflict with /api
• Test API authentication
• Verify API versioning works
• Test with different API clients

For Desktop Apps (via web)

• Test VNC/X11 forwarding (if applicable)
• Test clipboard functionality
• Test file upload/download
• Verify keyboard shortcuts work

Deployment Checklist

11. Container Testing

• Test standalone mode: docker run -p 8080:8080 your-image
• Test JupyterHub mode with mock environment variables
• Test health endpoints: curl localhost:8080/api/status
• Test service access: curl localhost:8080/

12. JupyterHub Integration

• Configure spawner in jupyterhub_config.py
• Set up persistent volumes
• Configure network settings
• Test user spawning
• Test service accessibility through JupyterHub

Quality Assurance

13. Performance Testing

• Measure memory usage increase (~500MB expected)
• Test startup time (10-15 seconds additional expected)
• Measure proxy latency (<5ms expected)
• Test under load

14. Security Review

• Verify permission handling is secure
• Check URL rewriting doesn’t allow injection
• Test OAuth flows
• Verify proper user isolation

Documentation Updates

15. Update Project Documentation

• Update main README.md
• Document new API endpoints
• Update deployment instructions
• Add troubleshooting section

16. Create Migration Guide

• Document changes from previous version
• Provide migration steps
• List breaking changes
• Provide rollback instructions

Final Verification

17. End-to-End Testing

• Deploy to staging environment
• Test with real users
• Verify all use cases work
• Test OAuth with named servers

18. Production Readiness

• Set up monitoring/alerting
• Test backup/restore procedures
• Document operational procedures
• Create runbook for common issues

Success Criteria

• ✅ Service starts in both standalone and JupyterHub modes
• ✅ All API endpoints respond correctly
• ✅ JupyterHub can spawn and health-check the service
• ✅ URL rewriting works for all service content
• ✅ OAuth authentication works (including named servers)
• ✅ WebSocket connections work (if applicable)
• ✅ Performance is acceptable
• ✅ All tests pass
• ✅ Documentation is complete

Estimated Implementation Time

• Core Implementation: 2-3 weeks
• Testing: 1-2 weeks
• Documentation: 1 week
• OAuth Fixes: 1 week (if using named servers)
• Total: 5-7 weeks for complete implementation

File Count and Line Estimates

• Core Files: 5 files, ~1,000 lines
• OAuth Fixes: 2 files, ~200 lines
• Testing: 5 files, ~1,000 lines
• Documentation: 10-15 files, ~2,000 lines
• Total: ~20-25 files, ~4,000-5,000 lines

This checklist provides a systematic approach to implementing JupyterHub compatibility for any containerized service. Following this checklist should result in a robust, enterprise-ready integration that works seamlessly in both standalone and JupyterHub environments.