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	Step-by-step guide for implementing a new registry adapter
/swagger-ui/ (runtime)	Interactive API docs

---

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)

• CONTRIBUTING.md — contributor guide (points to Contributing guide)
• Deployment
• ROADMAP.md for the full list of planned features, or browse the Roadmap page on the documentation site.
• Testing
• Access control
• RFCs
• SECURITY.md — supported versions and how to report a vulnerability
• LICENSE — Apache License 2.0