README.md

---
title: HF Builder
sdk: docker
pinned: false
---

# HF Builder

Daemonless Docker image builder for HuggingFace Spaces using [Kaniko](https://github.com/GoogleContainerTools/kaniko).

## Features

- **Build Tracking**: Unique build IDs, history, and metrics
- **GitHub Webhooks**: Automatic builds on push with signature verification
- **Notifications**: Slack, Discord, and custom webhook notifications
- **Observability**: OpenTelemetry tracing, Prometheus metrics, structured logging
- **Status Badge**: SVG badge for READMEs
- **Request Tracing**: Trace IDs through logs and responses
- **HTMX Dashboard**: Real-time web interface with live updates
- **Hivemind Integration**: Connect to hivemind controller for distributed builds
- **Task Runner**: go-task automation for common operations

## Quick Start

```bash
# Install go-task
brew install go-task

# Run locally
task dev

# Check status
task status

# Trigger a build
task build REPO_URL=https://github.com/owner/repo IMAGE=owner/repo
```

## Configuration

### Core Settings

| Secret | Required | Default | Description |
|--------|----------|---------|-------------|
| `REGISTRY_URL` | No | `ghcr.io` | Container registry URL |
| `REGISTRY_USER` | Yes | - | Registry username |
| `REGISTRY_PASSWORD` | Yes | - | Registry password/token |
| `GITHUB_TOKEN` | For private | - | Token for cloning |
| `WEBHOOK_SECRET` | Recommended | - | GitHub webhook secret |
| `DEFAULT_IMAGE` | No | - | Default image name |
| `BUILD_TIMEOUT` | No | `1800` | Timeout in seconds |
| `ENABLE_CACHE` | No | `false` | Enable Kaniko cache |

### Notifications

| Secret | Description |
|--------|-------------|
| `NOTIFICATION_URL` | Generic webhook URL for build results |
| `SLACK_WEBHOOK_URL` | Slack incoming webhook URL |
| `DISCORD_WEBHOOK_URL` | Discord webhook URL |
| `NOTIFY_ON` | When to notify: `all`, `failure`, `success` (default: `failure`) |

### Observability

| Secret | Description |
|--------|-------------|
| `LOG_FORMAT` | `text` or `json` (default: `text`) |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry collector endpoint |
| `OTEL_SERVICE_NAME` | Service name for traces (default: `hf-builder`) |

### Hivemind Integration

| Secret | Description |
|--------|-------------|
| `HIVEMIND_CONTROLLER_URL` | URL of the hivemind controller (enables worker mode) |
| `HIVEMIND_POLL_INTERVAL` | Seconds between work polls (default: `30`) |

When `HIVEMIND_CONTROLLER_URL` is set, the builder:
1. Registers itself with the controller as a "build" worker
2. Polls for build work items
3. Executes builds and reports completion/failure
4. Sends heartbeats to indicate status

## Web Dashboard

The builder includes a real-time HTMX-powered dashboard at the root URL showing:

- **Stats**: Status, completed/failed builds, success rate
- **Current Build**: Active build with cancel button
- **Build History**: Recent builds with status badges
- **New Build Form**: Trigger builds from the UI
- **Live Logs**: Real-time log streaming

All panels auto-refresh via HTMX polling.

## Status Badge

Add to your README:

```markdown
![Build Status](https://your-space.hf.space/badge)
```

Returns an SVG badge showing: `passing`, `failing`, `building`, or `no builds`.

## Request Tracing

Every request gets a trace ID:
- Pass `X-Request-ID` or `X-Trace-ID` header, or one is auto-generated
- Response includes `X-Trace-ID` header
- Logs include trace ID: `[HH:MM:SS] [trace123] message`
- JSON logs include `trace_id` field

## Notifications

### Slack

Set `SLACK_WEBHOOK_URL` to receive formatted messages:

```
✅ Build SUCCESS
owner/repo:latest
ID: abc123 | Duration: 180.5s | Branch: main
```

### Discord

Set `DISCORD_WEBHOOK_URL` to receive embedded messages with build details.

### Custom Webhook

Set `NOTIFICATION_URL` or pass `callback_url` in API request. Receives JSON:

```json
{
  "build": {
    "id": "abc123",
    "status": "success",
    "image": "ghcr.io/owner/repo",
    "tags": ["latest"],
    "duration_seconds": 180.5,
    "trace_id": "xyz789"
  },
  "runner_id": "runner1",
  "registry": "ghcr.io"
}
```

## OpenTelemetry

Set `OTEL_EXPORTER_OTLP_ENDPOINT` to enable distributed tracing.

Traces include:
- Span per build with `build.id`, `build.image`, `build.status`
- Errors recorded as span events

Works with:
- Jaeger
- Grafana Tempo
- Honeycomb
- Any OTLP-compatible backend

## Prometheus Metrics

`GET /api/metrics` returns:

```
# HELP hf_builder_builds_total Total builds
# TYPE hf_builder_builds_total counter
hf_builder_builds_total{status="success"} 42
hf_builder_builds_total{status="failed"} 3

# HELP hf_builder_build_duration_seconds Avg build duration
# TYPE hf_builder_build_duration_seconds gauge
hf_builder_build_duration_seconds 180.50

# HELP hf_builder_success_rate Success rate
# TYPE hf_builder_success_rate gauge
hf_builder_success_rate 0.9333
```

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Web dashboard (HTMX) |
| `/health` | GET | Health check |
| `/ready` | GET | Readiness check |
| `/badge` | GET | SVG status badge |
| `/api/status` | GET | Builder status |
| `/api/metrics` | GET | Prometheus metrics |
| `/api/history` | GET | Build history |
| `/api/logs` | GET | Recent logs |
| `/api/build` | POST | Trigger build |
| `/api/build/{id}/cancel` | POST | Cancel build |
| `/webhook/github` | POST | GitHub webhook |
| `/webhook/test` | POST | Test endpoint |
| `/stats-partial` | GET | Stats HTML partial |
| `/current-partial` | GET | Current build HTML partial |
| `/history-partial` | GET | History HTML partial |
| `/logs-partial` | GET | Logs HTML partial |

## Webhook Headers

| Header | Description |
|--------|-------------|
| `X-Builder-Image` | Override image name |
| `X-Builder-Tags` | Comma-separated tags |
| `X-Builder-Token` | GitHub token |
| `X-Builder-Platform` | Target platform |
| `X-Builder-Args` | Build args: `K1=V1,K2=V2` |
| `X-Builder-Callback` | Notification URL |

## Task Runner

The project includes a `Taskfile.yml` for [go-task](https://taskfile.dev/):

```bash
# Development
task dev           # Run locally
task dev:watch     # Run with auto-reload

# Testing
task lint          # Run linting
task lint:fix      # Fix linting issues

# Docker
task docker:build  # Build Docker image
task docker:run    # Run Docker image

# API Operations
task health        # Check health
task status        # Get status
task metrics       # Get metrics
task history       # Get build history
task logs          # Get recent logs

# Build Operations
task build REPO_URL=... IMAGE=...  # Trigger a build
task build:cancel BUILD_ID=...     # Cancel a build

# Hivemind
task hivemind:register  # Register with controller
task hivemind:heartbeat # Send heartbeat

# Deployment
task deploy:hf     # Deploy to HuggingFace
```

## License

MIT