Installation Overview¶
Circuit Breaker is a homelab topology mapper that runs as a self-hosted Docker application. This section covers every supported installation method so you can choose the one that fits your environment.
System Requirements¶
| Requirement | Minimum |
|---|---|
| OS | Linux (amd64, arm64, arm/v7) |
| Docker | Engine 20+ with Compose plugin v2 |
| RAM | 1 GB available |
| Disk | 500 MB for image + space for your data volume |
| Network | Outbound access to ghcr.io to pull the image |
macOS / Windows: Circuit Breaker runs inside Docker Desktop. All install methods work the same — replace Linux-specific steps (systemd, CA cert import) with the platform equivalents described in Configuration Reference.
Method Comparison¶
| Method | Best for | HTTPS | Effort |
|---|---|---|---|
| Quick Install (Script) | Most Linux users — fastest path | Auto via Caddy | Low |
| Docker Compose — Prebuilt Full Stack | Full capability (discovery, webhooks) — no build | Auto via Caddy | Low |
| Docker Compose — Prebuilt Single | Minimal single-container, behind existing proxy | BYO | Low |
| Docker Compose — From Source | Contributors or custom builds | Auto via Caddy | Medium |
| Single Docker Container | Minimal setups, scripting, behind an existing reverse proxy | BYO | Low |
Which Method Should I Choose?¶
I just want to get Circuit Breaker running as fast as possible with full capability (discovery, webhooks, HTTPS). → Use the Quick Install script. Choose option 2 (Compose stack). One command, no build, under 60 seconds.
I want a full compose stack (backend, workers, Caddy) without building from source. → Use Docker Compose — Prebuilt Full Stack. Pull-only, zero build.
I want a minimal single container to drop into my stack. → Use Docker Compose — Prebuilt Single. No repo clone needed, pull-and-go.
I want to build Circuit Breaker from source (or contribute to development). → Use Docker Compose — From Source. Clones the repo and builds images locally.
I have my own reverse proxy (nginx, Traefik, Caddy) and just want a single container to proxy to. → Use the Single Docker Container method and point your proxy at port 8080.
After Installing¶
Regardless of method, your next steps are:
- Open Circuit Breaker in your browser.
- Complete the first-run setup wizard — see First-Run Setup.
- Back up the vault key shown at the end of the wizard (only displayed once).
- Optionally review the Configuration Reference to tune environment variables.