### Start Local BinderHub Webserver (Mocked Hub)

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Start the BinderHub webserver locally with a mocked JupyterHub. This setup is suitable for UI development without a full Kubernetes or JupyterHub deployment.

```bash
python3 -m binderhub -f testing/local-binder-mocked-hub/binderhub_config.py
```

--------------------------------

### Start BinderHub Locally

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Start BinderHub using the testing configuration file.

```bash
python3 -m binderhub -f testing/local-binder-k8s-hub/binderhub_config.py
```

--------------------------------

### Start Minikube Kubernetes Cluster

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Starts a local Kubernetes cluster using Minikube. Ensure Minikube is installed and configured.

```bash
minikube start
```

--------------------------------

### Install BinderHub and Documentation Tools

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Install BinderHub and its documentation dependencies, including sphinx-autobuild for live reloading.

```bash
python3 -m pip install -r docs/requirements.txt
python3 -m pip install sphinx-autobuild
```

--------------------------------

### Install Local BinderHub from Source

Source: https://github.com/jupyterhub/binderhub/blob/main/testing/local-binder-local-hub/README.md

Installs BinderHub in editable mode from the local source directory.

```bash
pip install -e ../..
```

--------------------------------

### Install BinderHub Locally

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Install BinderHub as a Python package with development requirements.

```bash
python3 -m pip install -e "[pycurl]" -r dev-requirements.txt
```

--------------------------------

### Install Helm 3

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-prerequisites.md

Use this command to install Helm, the package manager for Kubernetes. This script is the simplest way to get Helm installed.

```bash
curl -sf https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
```

--------------------------------

### Example config.yaml with CORS enabled and HTTPS setup

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/cors.md

This example shows how to enable CORS alongside other configurations for a secure BinderHub deployment, including hub URL, ingress settings, and TLS certificates. Ensure you replace placeholder values with your specific URLs and secret names.

```yaml
config:
  BinderHub:
    hub_url: https://<jupyterhub-URL> # e.g. https://hub.binder.example.com
    cors_allow_origin: '*'

jupyterhub:
  hub:
    config:
      BinderSpawner:
        cors_allow_origin: '*'
  ingress:
    enabled: true
    hosts:
      - <jupyterhub-URL> # e.g. hub.binder.example.com
    annotations:
      kubernetes.io/ingress.class: nginx
      kubernetes.io/tls-acme: "true"
      cert-manager.io/issuer: letsencrypt-production
      https:
        enabled: true
        type: nginx
    tls:
      - secretName: <jupyterhub-URL-with-dashes-instead-of-dots>-tls # e.g. hub-binder-example-com-tls
        hosts:
          - <jupyterhub-URL> # e.g. hub.binder.example.com

ingress:
  enabled: true
  hosts:
    - <binderhub-URL> # e.g. binder.example.com
  annotations:
    kubernetes.io/ingress.class: nginx
    kubernetes.io/tls-acme: "true"
    cert-manager.io/issuer: letsencrypt-production
    https:
      enabled: true
      type: nginx
  tls:
    - secretName: <binderhub-URL-with-dashes-instead-of-dots>-tls  # e.g. binder-example-com-tls
      hosts:
        - <binderhub-URL> # e.g. binder.example.com
```

--------------------------------

### Install BinderHub Helm Chart

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-binderhub.md

Install the BinderHub Helm chart with specified version, namespace, and configuration files.

```bash
helm upgrade \
<choose-name> \
jupyterhub/binderhub \
--install \
--version=1.0.0-0.dev.git.3673.h040c9bbe \
--create-namespace \
--namespace=<choose-namespace> \
-f secret.yaml \
-f config.yaml
```

--------------------------------

### Install Development Requirements

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Install development requirements including pytest and chartpress.

```bash
python3 -m pip install -r dev-requirements.txt
```

--------------------------------

### Install kubectl CLI

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Downloads and installs the kubectl command-line tool for interacting with Kubernetes clusters. Requires curl and sudo privileges.

```bash
curl -LO "https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/
```

--------------------------------

### Install NodeJS Dependencies

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Install the necessary NodeJS dependencies for frontend development. This is required for UI and asset building.

```bash
npm install
```

--------------------------------

### Example OVH Container Registry Configuration

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-binderhub.md

An example `config.yaml` snippet demonstrating the configuration for OVH Container Registry with specific values.

```yaml
config:
  BinderHub:
    use_registry: true
    image_prefix: abcde.gra7.container-registry.ovh.net/myproject/binder-
  DockerRegistry:
    url: https://abcde.gra7.container-registry.ovh.net
    token_url: https://abcde.gra7.container-registry.ovh.net/service/token?service=harbor-registry
```

--------------------------------

### Start Minikube with Increased Memory

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Starts the Minikube VM with 8GiB of memory allocated, which may be necessary for the builder to run successfully. Adjust the memory value as needed.

```bash
minikube start --memory 8192
```

--------------------------------

### Install cert-manager

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/https.md

Apply the cert-manager Kubernetes manifest to install it. For older Kubernetes versions, use the --validate=false flag.

```bash
kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.8.1/cert-manager.yaml
```

--------------------------------

### Waiting Event Structure

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/api.md

Emitted when a build pod has started and is waiting to initialize.

```default
{'phase': 'waiting', 'message': 'Human readable message'}
```

--------------------------------

### Install JupyterHub Helm Chart

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Install the JupyterHub Helm chart into your Kubernetes cluster. Append --auth for non-public BinderHub development.

```bash
# Append --auth here if you want to develop against a non-public BinderHub
# that relies on JupyterHub's configured Authenticator to decide if the users
# are allowed access or not.
./testing/local-binder-k8s-hub/install-jupyterhub-chart
```

--------------------------------

### Install BinderHub Python Package

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Install BinderHub as an editable Python package. This allows for direct modification and testing of the package.

```bash
python3 -m pip install -e .
```

--------------------------------

### Configure Kubernetes Launch Quota

Source: https://context7.com/jupyterhub/binderhub/llms.txt

Set up resource quotas for BinderHub launches using Kubernetes, defining total concurrent user pods and per-repository limits. Includes an example of a custom quota class.

```python
# binderhub_config.py — quota configuration

c.LaunchQuota.total_quota  = 300    # max total concurrent user pods; None = unlimited
c.BinderHub.per_repo_quota = 20     # max pods per repo; 0 = unlimited

# Custom quota class (e.g. for non-Kubernetes deployments)
from binderhub.quota import LaunchQuota
class MyQuota(LaunchQuota):
    async def check_repo_quota(self, image_name, repo_config, repo_url):
        # query your own database here
        used = await my_db.count_active_sessions(repo_url)
        quota = repo_config.get("quota", 50)
        if used >= quota:
            from binderhub.quota import LaunchQuotaExceeded
            raise LaunchQuotaExceeded(
                f"Too many users on {repo_url}",
                quota=quota, used=used, status="repo_quota"
            )
        from binderhub.quota import ServerQuotaCheck
        return ServerQuotaCheck(total=used, matching=used, quota=quota)

c.BinderHub.launch_quota_class = MyQuota
```

--------------------------------

### BinderHub Configuration Trait Example

Source: https://github.com/jupyterhub/binderhub/blob/main/helm-chart/binderhub/templates/NOTES.txt

When migrating from older BinderHub versions, special handling for simple configurables has been removed. Use the Python traits configuration directly. For example, to set configuration on BinderHub, use the `config.ClassName.trait_name: value` format.

```yaml
config:
  BinderHub:
    use_registry: false
```

```yaml
config:
  GitHubRepoProvider:
    access_token: "..."
```

--------------------------------

### Run JupyterHub with Dummy Authentication

Source: https://github.com/jupyterhub/binderhub/blob/main/testing/local-binder-local-hub/README.md

Starts a local JupyterHub instance with dummy authentication enabled for testing purposes. This is an alternative to the standard authentication.

```bash
export AUTHENTICATOR=dummy
jupyterhub --config=jupyterhub_config.py
```

--------------------------------

### Install/Upgrade BinderHub Helm Chart

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Install or upgrade the BinderHub Helm chart in the current Kubernetes namespace.

```bash
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

echo "BinderHub inside the Minikube based Kubernetes cluster is starting up at http://$(minikube ip):30901"
```

--------------------------------

### Install JupyterHub Dependencies

Source: https://github.com/jupyterhub/binderhub/blob/main/testing/local-binder-local-hub/README.md

Installs necessary Python packages for JupyterHub and Node.js for the configurable HTTP proxy.

```bash
pip install -r requirements.txt
npm install -g configurable-http-proxy
```

--------------------------------

### Verify Helm Installation

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-prerequisites.md

Check if Helm has been installed correctly by running the version command. This confirms that Helm is accessible and provides its current version details.

```bash
helm version
```

--------------------------------

### Run JupyterHub Locally

Source: https://github.com/jupyterhub/binderhub/blob/main/testing/local-binder-local-hub/README.md

Starts a local JupyterHub instance using a specified configuration file. This is the first terminal to run.

```bash
jupyterhub --config=jupyterhub_config.py
```

--------------------------------

### Verify Kubectl Installation and Cluster Communication

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-prerequisites.md

Confirm that kubectl is installed and can communicate with your Kubernetes cluster. This command displays both client and server versions.

```bash
kubectl version
```

--------------------------------

### BinderHub Class Configuration

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/reference/app.md

Configuration options for the BinderHub application class, which is responsible for starting a builder.

```APIDOC
## binderhub.app.BinderHub

### Description
An Application for starting a builder.

### Class Attributes

- **about_message** (Unicode) - Additional message to display on the about page. Will be directly inserted into the about page’s source so you can use raw HTML.
- **appendix** (Unicode) - DEPRECATED: Use c.BuildExecutor.appendix. Appendix to pass to repo2docker. A multi-line string of Docker directives to run.
- **auth_enabled** (Bool) - If JupyterHub authentication enabled, require user to login (don’t create temporary users during launch) and start the new server for the logged in user.
- **badge_base_url** (Union) - Base URL to use when generating launch badges. Can also be a function that is passed the current handler and returns the badge base URL, or "" for the default.
- **ban_networks** (Dict) - Dict of networks from which requests should be rejected with 403. Keys are CIDR notation (e.g. ‘1.2.3.4/32’), values are a label used in log / error messages.
- **banner_message** (Unicode) - Message to display in a banner on all pages. The value will be inserted “as is” into a HTML <div> element with grey background, located at the top of the BinderHub pages. Raw HTML is supported.
- **base_url** (Unicode) - The base URL of the entire application.
- **build_class** (Type) - The class used to build repo2docker images. Must inherit from binderhub.build.BuildExecutor.
- **build_cleaner_class** (Type) - The class used to cleanup builders.
- **build_cleanup_interval** (Int) - Interval (in seconds) for how often stopped build pods will be deleted.
- **build_docker_config** (Dict) - A dict which will be merged into the .docker/config.json of the build container (repo2docker). WARNING: The value of this parameter is managed by the binderHub Helm Chart.
- **build_docker_host** (Unicode) - DEPRECATED: Use c.KubernetesBuildExecutor.docker_host. The docker URL repo2docker should use to build the images.
- **build_image** (Unicode) - DEPRECATED: Use c.KubernetesBuildExecutor.build_image. The repo2docker image to be used for doing builds.
- **build_max_age** (Int) - Maximum age of builds. Builds that are still running longer than this will be killed.
- **build_memory_limit** (ByteSpecification) - DEPRECATED: Use c.BuildExecutor.memory_limit. Max amount of memory allocated for each image build process. 0 sets no limit.
```

--------------------------------

### Get Application URL with ClusterIP Service

Source: https://github.com/jupyterhub/binderhub/blob/main/helm-chart/binderhub/templates/NOTES.txt

For services of type ClusterIP, use `kubectl port-forward` to access the application locally. The command will output a local URL and start a port-forwarding session.

```bash
export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "component=binder" -o name)
export POD_PORT=$(kubectl get svc binder -o jsonpath="{.spec.ports[0].targetPort}")
echo "Visit http://127.0.0.1:8080 to use your application"
kubectl port-forward $POD_NAME 8080:$POD_PORT
```

--------------------------------

### Ready Event Structure

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/api.md

Emitted when the notebook server is ready, providing the URL and an authentication token.

```default
{"phase": "ready", "message": "Human readable message", "url": "full-url-of-notebook-server", "token": "notebook-server-token"}
```

--------------------------------

### Build Documentation Locally

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Build the BinderHub documentation locally. Changes to source files will trigger an automatic rebuild.

```bash
sphinx-autobuild docs/source docs/_build/html
```

--------------------------------

### Configure BinderHub Launcher Settings

Source: https://context7.com/jupyterhub/binderhub/llms.txt

Tune launcher retries, retry delay, and launch timeout. Configure named servers and set up a pre-launch hook for custom logic like allowlisting.

```python
# binderhub_config.py — launcher tuning

c.Launcher.retries     = 4    # attempts per Hub API call
c.Launcher.retry_delay = 4    # seconds between retries (doubles each attempt)
c.Launcher.launch_timeout = 600  # seconds to wait for server to become ready

# Named servers (requires JupyterHub named-server support)
c.Launcher.allow_named_servers         = True
c.Launcher.named_server_limit_per_user = 5

# Pre-launch hook — run custom logic before every spawn
async def my_pre_launch_hook(launcher, image, username, server_name, repo_url):
    # e.g. enforce an allowlist
    allowed_repos = {"github.com/myorg/"}
    if not any(repo_url.startswith(r) for r in allowed_repos):
        from tornado.web import HTTPError
        raise HTTPError(403, f"Repo {repo_url} is not allowed")

c.Launcher.pre_launch_hook = my_pre_launch_hook
```

--------------------------------

### Create BinderHub Configuration Directory

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-binderhub.md

Creates a directory for BinderHub configuration files and navigates into it.

```bash
mkdir binderhub
cd binderhub
```

--------------------------------

### Launcher.launch

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/reference/launcher.md

Launches a server for a given image and username. This method handles user creation (if authentication is disabled), server spawning, token generation, and returns essential details about the launched server.

```APIDOC
## launch(image, username, server_name='', repo_url='', extra_args=None, event_callback=None)

### Description
Launch a server for a given image.

- creates a temporary user on the Hub if authentication is not enabled
- spawns a server for temporary/authenticated user
- generates a token
- returns a dict containing:
  - `url`: the URL of the server
  - `image`: image spec
  - `repo_url`: the url of the repo
  - `extra_args`: Dictionary of extra arguments passed to the server
  - `token`: the token for the server

### Parameters
- **image** (str) - The Docker image to launch.
- **username** (str) - The username for whom the server is launched.
- **server_name** (str, optional) - The name of the server. Defaults to ''.
- **repo_url** (str, optional) - The URL of the repository. Defaults to ''.
- **extra_args** (dict, optional) - Additional arguments to pass to the server. Defaults to None.
- **event_callback** (callable, optional) - A callback function to receive launch events. Defaults to None.

### Returns
- dict - A dictionary containing server details: `url`, `image`, `repo_url`, `extra_args`, `token`.
```

--------------------------------

### Build and launch a repository

Source: https://context7.com/jupyterhub/binderhub/llms.txt

The primary API endpoint. Accepts an SSE (Server-Sent Events) connection and streams JSON progress events while building and launching the requested repository. `provider_prefix` identifies the repo provider (e.g. `gh`, `gl`, `git`, `zenodo`). `spec` is provider-specific (e.g. `user/repo/ref` for GitHub). Optional query parameters: `build_token` (signed JWT), `build_only=true` (build without launching, requires `enable_api_only_mode=True`).

```APIDOC
## GET /build/<provider_prefix>/<spec>

### Description
Builds and launches a specified repository, streaming progress events via Server-Sent Events (SSE).

### Method
GET

### Endpoint
/build/<provider_prefix>/<spec>

### Parameters
#### Path Parameters
- **provider_prefix** (string) - Required - Identifies the repository provider (e.g., `gh`, `gl`, `git`, `zenodo`).
- **spec** (string) - Required - Provider-specific identifier for the repository (e.g., `user/repo/ref` for GitHub).

#### Query Parameters
- **build_token** (string) - Optional - A signed JWT for authentication.
- **build_only** (boolean) - Optional - If `true`, builds the repository without launching a server. Requires `enable_api_only_mode=True` to be set in BinderHub configuration.

### Request Example
```bash
# Stream build/launch events for a GitHub repo using curl
curl -N \
  -H "Accept: text/event-stream" \
  "https://mybinder.org/build/gh/binder-examples/requirements/HEAD"

# Build-only mode (API-only BinderHub deployment)
curl -N \
  -H "Accept: text/event-stream" \
  "https://binder.example.org/build/gh/myorg/myrepo/main?build_only=true"
```

### Response
#### Success Response (200 - SSE Stream)
- **data** (JSON object) - Streams JSON objects with `phase` and `message` fields indicating build/launch progress. May include `imageName` and `url` upon completion.

#### Response Example
```
# Example event stream output:
data: {"phase": "waiting", "message": "Waiting for build to start...\n"}
data: {"phase": "building", "message": "Step 1/4 : FROM python:3.9\n"}
data: {"phase": "pushing",  "message": "Pushing layers...", "progress": {"layer1": {"current": 1024, "total": 4096}}}
data: {"phase": "built",    "imageName": "gcr.io/binderhub/binder-examples-requirements-abc123:def456", "message": "Built image, launching...\n"}
data: {"phase": "launching","message": "Launching server...\n"}
data: {"phase": "ready",    "url": "https://hub.mybinder.org/user/tmp-abc123/", "token": "abc123token", "repo_url": "https://github.com/binder-examples/requirements"}

# Example build-only response:
data: {"phase": "ready", "imageName": "registry.example.org/myorg-myrepo:abcdef", "message": "Done! Image built\n"}
```
```

--------------------------------

### Configure Git Repository Provider

Source: https://context7.com/jupyterhub/binderhub/llms.txt

Enable BinderHub to launch repositories directly from any Git URL, supporting various protocols and private repositories using credentials.

```python
# binderhub_config.py — allow additional git protocols

c.GitRepoProvider.allowed_protocols = {"https", "http", "ssh", "git"}

# Spec format: URL-encoded-repo-url/ref
# e.g. to launch https://github.com/binder-examples/conda at main:
#   URL: /build/git/https%3A%2F%2Fgithub.com%2Fbinder-examples%2Fconda/main

# Private repos via git credentials helper
c.GitRepoProvider.git_credentials = r"username=myuser\npassword=mytoken"
```

--------------------------------

### Cleanup JupyterHub Helm Chart

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Delete the installed JupyterHub Helm chart to clean up resources.

```bash
helm delete binderhub-test
```

--------------------------------

### Build JS and CSS Bundles (Production)

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Create the JS and CSS bundles for BinderHub using webpack. This command is typically used for production builds or when watch mode is not needed.

```bash
npm run webpack
```

--------------------------------

### Update Helm Chart Dependencies

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Get the chart dependencies, such as JupyterHub, for the BinderHub Helm chart.

```bash
cd helm-chart/binderhub
helm dependency update
```

--------------------------------

### Build JS and CSS Bundles (Watch Mode)

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Create the JS and CSS bundles for BinderHub using webpack in watch mode. This is for UI development and automatically rebuilds assets on changes.

```bash
npm run webpack:watch
```

--------------------------------

### Migrating Build and PerRepoQuota Configuration

Source: https://github.com/jupyterhub/binderhub/blob/main/helm-chart/binderhub/templates/NOTES.txt

Top-level `build` configuration is removed. Use `config.BinderHub` for `appendix`, `build_cleanup_interval`, `build_image`, `build_max_age`, `build_namespace`, `build_node_selector`, `log_tail_lines`, and `per_repo_quota`.

```yaml
config:
  BinderHub:
    appendix: {{ .Values.build.appendix }}
    build_cleanup_interval: {{ .Values.build.cleanupInterval }}
    build_image: {{ .Values.build.repo2dockerImage }}
    build_max_age: {{ .Values.build.maxAge }}
    build_namespace: {{ .Values.build.namespace }}
    build_node_selector: {{ .Values.build.nodeSelector }}
    log_tail_lines: {{ .Values.build.logTailLines }}
    per_repo_quota: {{ .Values.perRepoQuota }}
```

--------------------------------

### Configure Docker for Docker Desktop

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Set the docker context to use the Docker Desktop daemon.

```bash
docker context use desktop-linux
```

--------------------------------

### Get Application URL with Ingress Hostname

Source: https://github.com/jupyterhub/binderhub/blob/main/helm-chart/binderhub/templates/NOTES.txt

If an ingress hostname is configured, the application URL is directly available via that hostname.

```bash
http://{{- .Values.ingress.hostname }}
```

--------------------------------

### BuildHandler.emit_launch_event

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/reference/builder.md

Emits a single launch event to the activity log.

```APIDOC
## emit_launch_event(provider, spec, ref)

### Description
Emit a single launch event to the activity log.

### Parameters
#### Path Parameters
- **provider** (any) - Description not specified
- **spec** (any) - Description not specified
- **ref** (any) - Description not specified
```

--------------------------------

### Get Application URL with NodePort Service

Source: https://github.com/jupyterhub/binderhub/blob/main/helm-chart/binderhub/templates/NOTES.txt

For services of type NodePort, retrieve the NodePort and Node IP to construct the application URL.

```bash
export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ template "fullname" . }})
export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
echo http://$NODE_IP:$NODE_PORT
```

--------------------------------

### BuildHandler.get

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/reference/builder.md

Retrieves a built image for a given spec and repository provider. This method relies on Tornado's GET request functionality.

```APIDOC
## get(provider_prefix, _unescaped_spec)

### Description
Get a built image for a given spec and repo provider. Different repo providers will require different spec information. This function relies on the functionality of the tornado `GET` request.

### Method
GET

### Parameters
#### Path Parameters
- **provider_prefix** (str) - The nickname for a repo provider (i.e. ‘gh’)
- **_unescaped_spec** (any) - Specifies information needed by the repo provider (i.e. user, repo, ref, etc.)
```

--------------------------------

### BinderHub SSE Build Phases Reference

Source: https://context7.com/jupyterhub/binderhub/llms.txt

This snippet provides a complete reference of the Server-Sent Event (SSE) phases emitted by the BinderHub /build endpoint. It includes representative JSON payloads for each phase, illustrating the data structure clients can expect. Handle 'Accept: text/event-stream' and close connections on 'phase=failed' or 'phase=ready'.

```javascript
// Complete phase reference with representative payloads

// 1. Waiting for the build pod to start
{ "phase": "waiting",  "message": "Waiting for build to start...\n" }
```

```javascript
// 2. Fetching the repository from source
{ "phase": "fetching", "message": "Cloning into /repo...\n" }
```

```javascript
// 3. Building — raw repo2docker / Docker build log lines
{ "phase": "building", "message": "Step 2/4 : RUN pip install -r requirements.txt\n" }
```

```javascript
// 4. Pushing layers to registry
{
  "phase": "pushing",
  "message": "Pushing image...",
  "progress": {
    "sha256:abc123": { "current": 1048576, "total": 4194304 },
    "sha256:def456": "Pushed",
    "sha256:789abc": "Layer already exists"
  }
}
```

```javascript
// 5. Image cached in registry — no build needed (or build finished)
{ "phase": "built", "imageName": "gcr.io/binder/user-repo:abc123", "message": "Found built image, launching...\n" }
```

```javascript
// 6. JupyterHub is spawning the server pod
{ "phase": "launching", "message": "Launching server...\n" }
```

```javascript
// 7. Ready — all fields below are present
{
  "phase":                    "ready",
  "url":                      "https://hub.mybinder.org/user/tmp-xyz789/",
  "token":                    "eyJraWQiOiJiaW5kZXJodWIiLCJhbGciOiJSUzI1...",
  "image":                    "gcr.io/binder/user-repo:abc123",
  "repo_url":                 "https://github.com/binder-examples/requirements",
  "binder_launch_host":       "https://mybinder.org/",
  "binder_request":           "v2/gh/binder-examples/requirements/HEAD",
  "binder_persistent_request":"v2/gh/binder-examples/requirements/abc1234",
  "binder_ref_url":           "https://github.com/binder-examples/requirements/tree/abc1234",
  "message":                  "server running at https://hub.mybinder.org/user/tmp-xyz789/\n"
}
```

```javascript
// 8. Failure — MUST close the EventSource connection
{ "phase": "failed", "message": "Docker build failed: exit code 1\n" }
```

```javascript
// Heartbeat comment (not a data event, ignored by EventSource)
// :heartbeat
```

--------------------------------

### Get JupyterHub Service IP

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-binderhub.md

Retrieve the external IP address of the JupyterHub service, typically named 'proxy-public', within the specified namespace.

```bash
kubectl --namespace=<namespace-from-above> get svc proxy-public
```

--------------------------------

### Direct RateLimiter Usage in Python

Source: https://context7.com/jupyterhub/binderhub/llms.txt

Demonstrates how to directly use the RateLimiter class to track and check request limits. Catches RateLimitExceeded exceptions.

```python
from binderhub.ratelimit import RateLimiter, RateLimitExceeded

limiter = RateLimiter()
limiter.limit = 5
limiter.period_seconds = 60

try:
    state = limiter.increment("192.168.1.42")
    print(f"OK — {state['remaining']} requests left until {state['reset']}")
except RateLimitExceeded as e:
    print(f"Blocked: {e}")
    # Output: Blocked: Rate limit exceeded (by 1) for '192.168.1.42', reset in 37s.
```

--------------------------------

### Configure JupyterHub Settings in BinderHub

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/customizing.md

Use this pattern in your `config.yaml` to modify JupyterHub settings within BinderHub. Refer to the JupyterHub for Kubernetes Customization Guide for detailed options.

```default
binderhub:
   jupyterhub:
      <JUPYTERHUB-CONFIG-YAML>
```

--------------------------------

### Get BinderHub Service IP Address

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-binderhub.md

Retrieve the external IP address of the BinderHub service using `kubectl`. This IP is needed to access your BinderHub deployment in a web browser.

```bash
kubectl --namespace=<namespace-from-above> get svc binder
```

--------------------------------

### Minimal Production BinderHub Configuration

Source: https://context7.com/jupyterhub/binderhub/llms.txt

This Python configuration file sets up essential parameters for a production BinderHub deployment, including hub URL, API token, image prefix, port, and registry usage. It also configures quotas, rate limiting, build settings, CORS, and UI customization.

```python
# binderhub_config.py — minimal production-ready configuration

c.BinderHub.hub_url = "https://hub.example.org/"
c.BinderHub.hub_api_token = "super-secret-token"          # or set JUPYTERHUB_API_TOKEN env var
c.BinderHub.image_prefix = "gcr.io/my-project/binder-"
c.BinderHub.port = 8585
c.BinderHub.use_registry = True

# --- Quota & rate limiting ---
c.LaunchQuota.total_quota = 200              # max concurrent user pods
c.BinderHub.per_repo_quota = 50             # max pods per repository
c.BinderHub.per_repo_quota_higher = 100     # quota for high-traffic repos
c.RateLimiter.limit = 10                    # builds per IP per hour
c.RateLimiter.period_seconds = 3600

# --- Build settings ---
c.KubernetesBuildExecutor.build_image = "quay.io/jupyterhub/repo2docker:2024.07.0"
c.KubernetesBuildExecutor.namespace = "binder-builds"
c.BinderHub.concurrent_build_limit = 32
c.BinderHub.build_max_age = 14400           # kill builds running > 4 hours

# --- CORS ---
c.BinderHub.cors_allow_origin = "https://my-frontend.example.org"

# --- UI customization ---
c.BinderHub.banner_message = '<div>Scheduled maintenance on 2024-12-01</div>'
c.BinderHub.about_message = "Powered by Project Jupyter"
c.BinderHub.extra_footer_scripts = {
    "01-analytics": "window.analytics && window.analytics.page();"
}

# --- API-only mode (no UI, useful for embedded/federated deployments) ---
# c.BinderHub.enable_api_only_mode = True

# Launch the app
# $ python -m binderhub -f binderhub_config.py

```

--------------------------------

### List available Azure subscriptions

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-registry.md

Run this command to see which Azure subscriptions are available for use. It refreshes the list before displaying it in a table format.

```bash
az account list --refresh --output table
```

--------------------------------

### Get Azure Container Registry resource ID

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-registry.md

Retrieve the unique resource ID of an Azure Container Registry. This ID is required for assigning roles and permissions, such as the AcrPush role.

```bash
az acr show --name <ACR_NAME> --query "id" -o tsv
```

--------------------------------

### Get BinderHub component versions

Source: https://context7.com/jupyterhub/binderhub/llms.txt

This endpoint returns a JSON object containing the version information for BinderHub and its key dependencies, such as repo2docker and JupyterHub. This is useful for debugging and ensuring compatibility between components.

```bash
curl https://mybinder.org/versions
```

```json
# Response:
# {
#   "binderhub": {"version": "0.2.0"},
#   "builder":   {"repo2docker": "2024.07.0"},
#   "jupyterhub": {"version": "4.1.5"}
# }
```

--------------------------------

### BuildHandler.launch

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/reference/builder.md

Requests JupyterHub to launch the specified image.

```APIDOC
## async launch(provider)

### Description
Ask JupyterHub to launch the image.

### Parameters
#### Path Parameters
- **provider** (any) - Description not specified
```

--------------------------------

### Get Application URL with LoadBalancer Service

Source: https://github.com/jupyterhub/binderhub/blob/main/helm-chart/binderhub/templates/NOTES.txt

For services of type LoadBalancer, retrieve the LoadBalancer IP and external port to construct the application URL. Note that it may take time for the LoadBalancer IP to become available.

```bash
NOTE: It may take a few minutes for the LoadBalancer IP to be available.
      You can watch the status of by running 'kubectl get svc -w {{ template "fullname" . }}"
export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ template "fullname" . }} -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo http://$SERVICE_IP:{{ .Values.service.externalPort }}
```

--------------------------------

### Configure Podman-in-Kubernetes (PinK) in BinderHub

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-binderhub.md

Set `imageBuilderType` to `pink` to use Podman as a replacement for Docker. This is a suitable option when Docker is not available.

```yaml
imageBuilderType: pink
```

--------------------------------

### Clone BinderHub Repository

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Clone the BinderHub repository to your local machine. This is the first step for any development task.

```bash
git clone https://github.com/jupyterhub/binderhub
cd binderhub
```

--------------------------------

### Stream build/launch events for a GitHub repo using curl

Source: https://context7.com/jupyterhub/binderhub/llms.txt

Use this endpoint to stream build and launch events for a specified repository. It accepts an SSE connection and provides real-time progress updates. The `build_only=true` parameter can be used to build an image without launching a user server, which requires `enable_api_only_mode=True` to be set in BinderHub's configuration.

```bash
curl -N \
  -H "Accept: text/event-stream" \
  "https://mybinder.org/build/gh/binder-examples/requirements/HEAD"
```

```text
# Example event stream output:
# data: {"phase": "waiting", "message": "Waiting for build to start...\n"}
# data: {"phase": "building", "message": "Step 1/4 : FROM python:3.9\n"}
# data: {"phase": "pushing",  "message": "Pushing layers...", "progress": {"layer1": {"current": 1024, "total": 4096}}}
# data: {"phase": "built",    "imageName": "gcr.io/binderhub/binder-examples-requirements-abc123:def456", "message": "Built image, launching...\n"}
# data: {"phase": "launching","message": "Launching server...\n"}
# data: {"phase": "ready",    "url": "https://hub.mybinder.org/user/tmp-abc123/", "token": "abc123token", "repo_url": "https://github.com/binder-examples/requirements"}
```

```bash
# Build-only mode (API-only BinderHub deployment)
curl -N \
  -H "Accept: text/event-stream" \
  "https://binder.example.org/build/gh/myorg/myrepo/main?build_only=true"
```

```text
# data: {"phase": "ready", "imageName": "registry.example.org/myorg-myrepo:abcdef", "message": "Done! Image built\n"}
```

--------------------------------

### Log in to Azure CLI

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-registry.md

Use this command to log in to your Azure account before configuring Azure Container Registry.

```bash
az login
```

--------------------------------

### Launching Event Structure

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/api.md

Emitted when the repository has been built and the system is waiting for the JupyterHub to launch the server.

```default
{'phase': 'launching', 'message': 'user friendly message'}
```

--------------------------------

### Configure Docker for Minikube

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/contribute.md

Configure docker to use the same daemon as your local Kubernetes cluster when using minikube.

```bash
eval $(minikube docker-env)
```

--------------------------------

### Building Event Structure

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/api.md

Emitted during the image building process, streaming logs directly from the build pod.

```default
{'phase': 'building', 'message': 'Log message'}
```

--------------------------------

### Configure GitLab Repository Provider

Source: https://context7.com/jupyterhub/binderhub/llms.txt

Set up BinderHub to use GitLab as a repository provider, including support for self-hosted instances and private repositories using access tokens.

```python
# binderhub_config.py — GitLab with self-hosted instance and token auth

# Self-hosted GitLab
c.GitLabRepoProvider.hostname = "gitlab.mycompany.com"

# Private repositories via personal/OAuth access token
c.GitLabRepoProvider.private_token = "glpat-xxxxxxxxxxxx"  # or GITLAB_PRIVATE_TOKEN env
# c.GitLabRepoProvider.access_token = "..."               # or GITLAB_ACCESS_TOKEN env

# Spec format: URL-escaped namespace + "/" + ref
# e.g. for https://gitlab.mycompany.com/group/subgroup/repo  ->  group%2Fsubgroup%2Frepo/main
```

--------------------------------

### Configure BinderHub for Google Artifact Registry

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/zero-to-binderhub/setup-binderhub.md

Add this configuration to `config.yaml` to use Google Artifact Registry. Replace placeholders with your specific project details.

```yaml
config:
  BinderHub:
    use_registry: true
    image_prefix: <region>-docker.pkg.dev/<google-project-id>/<prefix>-
    registry_class: "binderhub.registry.GoogleArtifactRegistry"
    DockerRegistry:
      url: "https://<region>-docker.pkg.dev"
      token_url: "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/<service-account-name>/token"
```

--------------------------------

### Configure Repository-Specific Settings

Source: https://github.com/jupyterhub/binderhub/blob/main/docs/source/customizing.md

Define repository-specific configurations using a list of patterns and overrides in `spec_config`. Later patterns in the list override earlier ones if they match the same repository.

```yaml
config:
    GitHubRepoProvider:
      spec_config:
        - pattern: ^ines/spacy-binder.*
          config:
             key1: value1
        - pattern: pattern2
          config:
             key1: othervalue1
             key2: othervalue2
```

```yaml
config:
    GitHubRepoProvider:
      spec_config:
        - pattern: ^ines/spacy-binder.*
          config:
             quota: 999
        - pattern: ^jupyterhub.*
          config:
             quota: 1337
```

--------------------------------

### Migrating Registry Prefix Configuration

Source: https://github.com/jupyterhub/binderhub/blob/main/helm-chart/binderhub/templates/NOTES.txt

`registry.prefix` is removed. Use `config.BinderHub.image_prefix` instead.

```yaml
config:
  BinderHub:
    image_prefix: {{.Values.registry.prefix }}
```

--------------------------------

### JavaScript BinderRepository Client

Source: https://context7.com/jupyterhub/binderhub/llms.txt

Use the JavaScript client to connect to a BinderHub build endpoint, stream progress events, and launch a notebook server. Ensure the EventSource connection is closed.

```javascript
import { BinderRepository } from "@jupyterhub/binderhub-client";

async function launchBinder() {
  const repo = new BinderRepository(
    "gh/binder-examples/requirements/HEAD",       // providerSpec
    new URL("https://mybinder.org/build/"),        // buildEndpointUrl
    {
      buildToken: null,     // optional JWT build token
      buildOnly:  false,    // set true to build without launching
      apiToken:   null,     // optional Bearer token for auth-enabled hubs
    }
  );

  try {
    for await (const event of repo.fetch()) {
      switch (event.phase) {
        case "waiting":
        case "fetching":
        case "building":
          console.log(`[${event.phase}] ${event.message.trim()}`);
          break;

        case "pushing":
          // structured layer-by-layer progress
          const layers = event.progress || {};
          const done = Object.values(layers).filter(v => v === "Pushed").length;
          console.log(`[pushing] ${done}/${Object.keys(layers).length} layers pushed`);
          break;

        case "built":
          console.log(`[built] Image ready: ${event.imageName}`);
          break;

        case "launching":
          console.log(`[launching] ${event.message.trim()}`);
          break;

        case "ready":
          console.log(`[ready] Server at: ${event.url}?token=${event.token}`);
          // Navigate the user to the live notebook server
          window.location.href = `${event.url}?token=${event.token}`;
          return;

        case "failed":
          console.error(`[failed] ${event.message.trim()}`);
          return;

        default:
          console.warn(`[${event.phase}]`, event);
      }
    }
  } finally {
    repo.close(); // always close the EventSource connection
  }
}

launchBinder();
```