BatleHub - Proxy Cache
A self-hosted smart proxy and cache for package registries. It sits between your build tools and the internet, caches artifacts after the first download, and enforces access-control rules before any package reaches a developer or CI pipeline.
Quick start
With Docker Compose
git clone https://github.com/batlehub/batlehub
cd batlehub/deploy/compose/min
BATLEHUB_ADMIN_TOKEN=$(openssl rand -hex 32) docker compose up -d # or podman compose
The server listens on http://localhost:8080, and npm is proxied at /proxy/npm/. deploy/compose/base adds an OIDC login (Dex) and deploy/compose/max adds Valkey and S3 storage — see Docker Compose.
Build from source
Prerequisites: Rust 1.87+, Node 24+, PostgreSQL
# Backend
cargo build --release -p batlehub-server
# Frontend (optional — embeds the SPA into the server)
cd ui && pnpm install --frozen-lockfile && pnpm run build && cd ..
# Generate the OpenAPI spec and TypeScript client
cargo run -p batlehub-server -- --config config.example.toml dump-spec > ui/openapi.json
cd ui && pnpm run generate && pnpm run build && cd ..
# Run
./target/release/batlehub --config config.toml
Or use the Task shortcuts:
task compose:db # start only postgres
task run # cargo run with example config
task ui:dev # vite dev server (proxies /api and /proxy to :8080)
task test # cargo test --workspace
Documentation
| Document | Contents |
|---|
| Supported Registry | List of supported Registries and how to use them |
| Installation | Choosing a method: Docker Compose, container image, binary, source, Helm |
| Helm chart | Kubernetes: three complete values files — basic, S3, production-ready |
| Administration | Administration: config, auth, S3, health, package management |
| User guide | User guide: client setup and publishing for all registry types |
| Configuration | Full TOML reference, permissions, worked examples |
| Configuration § Registry modes | Private registry modes (local / hybrid) |
| Private upstreams | Upstream auth (Bearer / Basic / header) and custom CA certificates |
| Publishing | Step-by-step guide for publishing packages (npm, Cargo, VSIX, Go modules, gems, Maven artifacts, Terraform modules/providers, PyPI wheels, conda packages) |
| SBOM | SBOM configuration, format reference, API endpoints, and export guide |
| Adding a registry |
Development, Contributing, security, and license
task build # cargo build --workspace
task test # cargo test --workspace
task lint # cargo clippy --workspace
task fmt # cargo fmt --all
task dump-spec # regenerate ui/openapi.json
task ui:generate # regenerate TypeScript client from openapi.json
task coverage # generate HTML coverage report (requires PostgreSQL + RustFS)
task coverage-check # enforce ≥80% line coverage (fails the build if below threshold)
