DOCSEARCHbyAlgolia
Submit Docs

BinderHub Documentation

repository·main·Indexed 25 days ago

https://github.com/jupyterhub/binderhub

BinderHub automates building Docker images from Git repositories using repo2docker and serving them via JupyterHub. It provides a workflow to create interactive computational environments, featuring a Python-based service, a Kubernetes Helm chart for deployment, and a set of React components and a client library for UI and API integration. Key capabilities include build and registration of images, support for multiple repository providers (GitHub, GitLab, Zenodo, etc.), and extensive configuration for UI branding, security, and resource quotas.

Tokens
18.2K
Snippets
45
Records
111
Agent score
83%

What's inside BinderHub

  1. Overview of BinderHub capabilities

    main

    BinderHub provides a workflow to serve interactive computational environments from Git repositories. It integrates JupyterHub (for user authentication and spawning single-user servers) with Repo2Docker (for generating Docker images from Git repositories).

    Key capabilities include:

    • BUILD: Create a Docker image from a Git repository.
    • REGISTER: Register the built image.
    • CONNECT: Connect with JupyterHub to provide a public IP address where users can interact with the code and environment in a live JupyterHub instance.
    • Version Control: Support for serving specific branches, commits, or tags.

  2. Overview of BinderHub

    main
    BinderHub is a Kubernetes-based cloud service designed to allow users to share reproducible interactive computing environments directly from code repositories. It serves as the underlying technology for mybinder.org. This project is intended for administrators who need to set up and manage their own BinderHub deployments.

  4. Understand the BinderHub Architecture

    main

    BinderHub is a system that provides on-the-fly creation and registry of Docker images to provide standardized computing environments. It orchestrates several components to transform a Git repository URL into a running JupyterHub environment.

    Core Components

    • Cloud Provider: (e.g., Google Cloud, Microsoft Azure, Amazon EC2) provides the underlying infrastructure.
    • Kubernetes: Manages resources on the cloud.
    • Helm: Used to configure and control Kubernetes deployments.
    • Docker: Provides the containerized environments.
    • BinderHub UI: The interface where users specify Git repositories for building.
    • repo2docker: The engine that generates Docker images from Git repository URLs.
    • Docker Registry: (e.g., gcr.io) Hosts the built container images.
    • JupyterHub: Deploys and manages the temporary containers for end-users.

  6. Understand BinderHub Event Logging

    main

    BinderHub emits discrete, structured items called events when specific actions occur. Unlike Prometheus metrics, which are pre-aggregated and primarily used for operational monitoring (e.g., 'how many launches happened in the last hour?'), events are intended for deep analytics (e.g., 'how many times was this specific repo launched in the last 6 months?').

    Events are sent to a sink using handlers from the Python logging module.

  8. Enable Authentication using JupyterHub as an OAuth provider

    main

    By default, BinderHub runs without authentication, creating a temporary user for each launch. To enable authentication via JupyterHub, update your config.yaml to enable authentication in both the BinderHub config and the BinderSpawner. You must also configure the jupyterhub.hub.config with your desired authenticator class and its specific configuration.

    Important Requirements:

    • Ensure jupyterhub-singleuser is used in the singleuser.cmd setting.
    • jupyterhub-singleuser requires JupyterHub to be installed in your user server images. It is recommended to use at least jupyter/repo2docker:ccce3fe to ensure repo2docker installs JupyterHub automatically.
    config:
  BinderHub:
    auth_enabled: true

jupyterhub:
  cull:
    # don't cull authenticated users (reverts binderhub chart's default)
    users: false
  hub:
    config:
      BinderSpawner:
        auth_enabled: true
      JupyterHub:
        redirect_to_server: false
        # specify the desired authenticator
        authenticator_class: <desired-authenticator>
      # use config of your authenticator here
      Authenticator: {}
      <desired-authenticator-class>: {}
    services:
      binder:
        oauth_client_id: service-binderhub
        oauth_no_confirm: true
        oauth_redirect_uri: "https://<binderhub_url>/oauth_callback"
    loadRoles:
      user:
        scopes:
          - self
          - "access:services!service=binder"

  singleuser:
    # make notebook servers aware of hub
    cmd: jupyterhub-singleuser

  9. Deploy BinderHub on Kubernetes using Helm

    main
    BinderHub is deployed on Kubernetes using a Helm chart. The chart contains Kubernetes manifest templates and a values.yaml file for configuration. For detailed instructions on integrating BinderHub into a full JupyterHub deployment, refer to the Zero to JupyterHub with Kubernetes guide.

  10. Set up a local environment to develop the BinderHub Helm chart

    main

    To develop the BinderHub Helm chart, you need a Kubernetes cluster and helm. This workflow involves building local Docker images and using chartpress to update the chart's values.

    # 1. Install dev requirements
python3 -m pip install -r dev-requirements.txt

# 2. Configure Docker for your cluster (example for minikube)
eval $(minikube docker-env)

# 3. Build images and update chart values
(python3 -m build . && cd helm-chart && chartpress)

# 4. Update chart dependencies
cd helm-chart/binderhub
helm dependency update

# 5. Validate and install the chart
helm template --validate binderhub-test helm-chart/binderhub \
   --values testing/k8s-binder-k8s-hub/binderhub-chart-config.yaml \
   --set config.BinderHub.hub_url=http://$(minikube ip):30902 \
   --set config.GitHubRepoProvider.access_token=$GITHUB_ACCESS_TOKEN

helm upgrade --install binderhub-test helm-chart/binderhub \
   --values testing/k8s-binder-k8s-hub/binderhub-chart-config.yaml \
   --set config.BinderHub.hub_url=http://$(minikube ip):30902 \
   --set config.GitHubRepoProvider.access_token=$GITHUB_ACCESS_TOKEN

  11. Set up Nginx Ingress Proxy

    main

    Use the nginx ingress controller to proxy TLS connections using your acquired static IP.

    1. Create a nginx-ingress.yaml file:
    controller:
  service:
    loadBalancerIP: <STATIC-IP>
    1. Install the proxy using Helm:
    helm install binderhub-proxy stable/nginx-ingress --namespace <same-namespace-as-binderhub> -f nginx-ingress.yaml
    1. Verify the installation by checking the service IP:
    kubectl --namespace <same-namespace-as-binderhub> get services binderhub-proxy-nginx-ingress-controller

  12. Enable access to private GitHub repositories

    main

    By default, BinderHub cannot access private repositories. To enable this, you must provide a GitHub access token with full read/write permissions on all your repos (the repo scope).

    Warning: Since cloning is performed 'as binderhub', any user on your BinderHub instance will be able to build any private repository that the BinderHub token has access to.