# BuildHut
> Binary distribution platform for Android, Linux, and Windows apps.

BuildHut is a self-hosted binary distribution platform. Developers upload application builds (APK, AAB, EXE, MSI, MSIX, AppImage, DEB, RPM, Flatpak, Snap) and share them through public download pages with developer profiles, organization management, and telemetry.

## Website
https://buildhut.sh

## Source Code
https://git.sr.ht/~drzoidberg/Buildhut

## Contact
Telegram: https://t.me/+8lgWL2r63mk5Zjhk

## Public Pages
- / — Landing page with recent builds, features overview, and navigation
- /apps — Browse all apps with search, filtering by organization, and pagination
- /apps/{name} — Individual app page with builds, versions, and download links
- /devs — Browse all developers with search and pagination
- /devs/{name} — Developer profile with apps, organization membership, and stats
- /orgs — Browse all organizations with search and pagination
- /orgs/{name} — Organization profile with team members and apps
- /submit — Upload a new build (requires bot challenge or auth)
- /login — Developer authentication page
- /privacy — Privacy policy (GDPR compliant)
- /terms — Terms of service
- /support — Support page with Telegram community link

## Authentication
- Session cookies: Set after bot challenge or login (dev-id, session-token)
- API tokens (Bearer): Generate at /portal/tokens. Format: bh_ + 64 hex. Up to 5 per dev.
- App secrets: 32-char hex for telemetry/OTLP. Passed via X-Secret header, ?secret= query, or body.

## API Endpoints

### App & Build APIs
- GET /api/app/{id} — Latest build info + presigned download URL (public, 5-min cache)
- GET /api/apps/{name}/latest — Redirect to latest build download (public)
- GET /api/apps/{name}/latest/{os}/{arch}/{format} — Platform-specific download (public)
- POST /api/upload/presign — Get presigned S3 upload URL (auth: session/bearer)
- POST /api/upload — Finalize build upload (auth: session/bearer, max 200MB)

### Telemetry API
- POST /api/telemetry — Submit telemetry events (auth: app secret)
- GET /api/telemetry — List telemetry events (auth: session, query: appName, devId, orgId, kind, limit)
- GET /api/telemetry/stream — WebSocket stream health (auth: session)

### OTLP Endpoints (OpenTelemetry Protocol)
- POST /v1/metrics — Ingest OTLP metrics (auth: app secret, JSON/Protobuf)
- POST /v1/logs — Ingest OTLP logs (auth: app secret, JSON/Protobuf)
- POST /v1/traces — Ingest OTLP traces (auth: app secret, JSON/Protobuf)

### Feature Flags API
- GET /v1/flags — Fetch feature flag definitions (auth: app secret)
- POST /v1/flags/eval — Report flag evaluations (auth: app secret)

### Publishing APIs
- POST /api/publish/generate — Preview publishing files (auth: session)
- POST /api/publish/publish — Execute publish run (auth: session)
- GET /api/publish/status/{runId} — Poll publish status (auth: session)
- GET /api/publish/ssh-keys — List SSH keys (auth: session)
- POST /api/publish/ssh-keys — Add SSH key (auth: session, encrypted at rest)
- DELETE /api/publish/ssh-keys/{id} — Delete SSH key (auth: session)
- POST /api/publish/rotate-key — Rotate encryption keys (auth: admin only)

### Utility APIs
- GET|POST /api/auth/status — Check auth state
- POST /api/logout — Clear session
- GET /api/img/{key} — Serve uploaded images (public)
- GET /api/branches?app={name} — List git branches (auth: session)
- POST /api/pgp/fetch-key — Fetch PGP key from keys.openpgp.org (auth: session)
- POST /api/validate — Validate bot challenge (public)
- GET /api/debug/builds — List all builds (dev only, disabled in production)

## Features
- Direct-to-cloud uploads via presigned S3 URLs (max 200 MB)
- Multi-platform support: Android (APK, AAB), Linux (AppImage, DEB, RPM, Snap), Windows (EXE, MSI, MSIX)
- API tokens with custom expiry for CI/CD integration
- Interactive SVG bot protection (no third-party captcha)
- Real-time telemetry and analytics per app
- OpenTelemetry Protocol (OTLP) ingestion for traces, metrics, and logs
- Feature flag management with evaluation tracking
- AUR and F-Droid publishing with SSH key management
- Developer profiles with public pages
- Organization management with team membership
- Session-based authentication with token support

## Supported File Types
.apk, .aab, .exe, .msi, .msix, .appimage, .deb, .rpm, .flatpak, .snap, .bin

## Crawling Notes
- All pages under /portal/* require authentication
- App, developer, and organization detail pages use dynamic URLs based on their name
- Pagination uses ?page=N query parameter
- Search uses ?search=query query parameter
- Organization filtering uses ?org=name query parameter