Skip to content

PiHerder documentation

Secure fleet management for Raspberry Pi and Linux hosts — backups, patching, Docker control, and service templates with secrets encrypted at rest.
Current line v0.5.0 (RC / main — package 0.5.0.dev0 until freeze)
Previous tag v0.4.0 (templates foundation)
Ship plan PLAN_v0.5.0.md
Source github.com/bjorngluck/piherder
Docs (this site) bjorngluck.github.io/piherder
License MIT (open source)

Start here

  • Install in ~15 minutes

    Docker Compose, master key, first admin user.

    Install guide

  • Add your first Pi

    SSH key deploy, least-priv user, feature flags.

    Add a server

  • Deploy a service template

    NPM, Uptime Kuma, Pi-hole, Grafana — wizard + secrets.

    Templates

  • Operator scenarios

    “I want to…” → the right page for every common task.

    Scenario index

What PiHerder does

flowchart LR
  You[Browser / PWA] --> Caddy[Caddy TLS]
  Caddy --> Web[FastAPI web]
  Web --> DB[(PostgreSQL)]
  Web --> Redis[(Redis)]
  Celery[Celery workers] --> DB
  Celery --> Redis
  Celery -->|SSH · rsync · docker · apt| Fleet[Pi / Linux fleet]
  Web -.->|deep links| Kuma[Uptime Kuma]
  Web -.->|deep links| GF[Grafana]
  Web -.->|DNS / proxy| PH[Pi-hole / NPM]
  • Fleet ops: rsync backups, apt OS patch, Docker compose projects, bulk actions
  • Safety: Fernet-encrypted SSH keys & certs, audit trail (+ client IP), RBAC, optional 2FA + Web Push
  • Templates: versioned stacks, desired state, drift, step-up secrets
  • Catalog (optional): Kuma, Grafana, Pi-hole, NPM, Certificates, Network maps

Core fleet work never requires Kuma, Grafana, NPM, or templates.

Documentation map

Section For
Getting started Install, HTTPS, appearance, scenarios
Day to day Dashboard, Services, servers, backups, updates, jobs
Docker Host containers & compose
Templates Catalog → Templates (deploy / from-host / secrets / drift)
Integrations Catalog → Integrations · Certificates · Network
Account & security RBAC, users, 2FA, PWA
Operations Settings, env, DR, metrics, API
Troubleshooting Common failures
Developers Code, tests, locks, screenshots

Maintainer roadmaps and release plans stay in the repo under docs/ — not in this user-facing tree.

Screenshots

Dashboard wireframe

Dashboard — fleet summary and attention table. wireframe Replace with a real capture when ready — local git workflow in Contributing docs.

Default: light + desktop. Optional dark/mobile showcases only. Capture inventory: screenshots README.

  • Interactive API (on your instance): /docs (OpenAPI, tag api-v1)
  • Security policy: SECURITY.md
  • Report issues: GitHub Issues