Skip to main content

JupyterHub

JupyterHub deployment for Jupyter UI is currently under development and needs community contributions to complete the integration.

Current Status​

Jupyter UI components are compatible with JupyterHub's authentication system since @datalayer/jupyter-react is built as a Jupyter Server extension. Initial proof-of-concept deployments have been successful, but complete documentation and production-ready configurations are still in progress.

Known Working Approach​

Based on community experimentation (#191), the following approach has been validated:

1. Install Jupyter UI​

cd /path/to/jupyter-ui
pip install -e .

2. Configure JupyterHub​

Update your jupyterhub_config.py:

# Set the default landing page to Jupyter UI
c.Spawner.default_url = '/jupyter_react'

# Configure the single-user app (if needed)
c.Spawner.environment = {
    'JUPYTERHUB_SINGLEUSER_APP': 'jupyter_react.serverextension'
}

3. Launch and Access​

The Jupyter UI application will be accessible at:

http://your-jupyterhub-domain/jupyter_react

Known Limitations​

  • Base URL Handling: Some JavaScript assets may not load correctly with custom base URLs. The index.html template needs updates to properly include JupyterHub's base_url.
  • Asset Paths: Static assets may require path adjustments in production configurations.
  • Incomplete Documentation: Setup steps need to be fully documented and tested across different JupyterHub configurations.

Integration Options​

Several approaches are being explored:

Option 1: JUPYTERHUB_SINGLEUSER_APP​

Use JupyterHub's environment variable to specify a custom application:

c.Spawner.environment = {
    'JUPYTERHUB_SINGLEUSER_APP': 'your.custom.module'
}

Reference: JupyterHub User Environment Configuration

Option 2: Custom Spawner​

Create a custom spawner that launches Jupyter UI. See:

Option 3: Proxy Integration​

Use JupyterHub's configurable HTTP proxy to serve Jupyter UI alongside other services.

We Need Your Help! 🙋​

This deployment method needs community contributions to become production-ready. We're looking for help with:

🐛 Testing & Bug Reports​

  • Test Jupyter UI with different JupyterHub configurations (Docker, Kubernetes, bare metal)
  • Report issues with authentication, base URL handling, or asset loading
  • Validate the setup on different operating systems and environments

📝 Documentation​

  • Document step-by-step installation procedures
  • Create configuration examples for common setups
  • Write troubleshooting guides based on real deployment experiences

💻 Code Contributions​

  • Fix base URL handling in templates
  • Improve static asset path resolution
  • Add JupyterHub-specific configuration options
  • Create example Helm charts for Kubernetes deployments

🔧 Infrastructure​

  • Create Docker images with Jupyter UI + JupyterHub
  • Build example deployment configurations (docker-compose, k8s manifests)
  • Test with different authentication providers (OAuth, LDAP, etc.)

How to Contribute​

  1. Join the discussion on GitHub Issue #191
  2. Share your experience - Even partial setups or failed attempts help others
  3. Submit PRs for documentation improvements or bug fixes
  4. Test and report your deployment configuration

Resources​

Community Support​

If you're working on a JupyterHub deployment or have questions:

  • GitHub Discussions: Share configurations and ask questions
  • Issue Tracker: Report bugs or request features
  • Pull Requests: Submit improvements to documentation or code

Your contributions will help make Jupyter UI a robust solution for JupyterHub multi-user environments!