Requirements
PiHerder host (where the stack runs)
| Need | Notes |
| Linux host with Docker + Docker Compose v2 | x86_64 or arm64 (Pi 4/5 OK for small fleets) |
| Disk for images + volumes | Postgres, backups destination, herder archives, avatars |
| Ports | Default compose: 8888 (HTTP), 8443 (HTTPS), optional direct 8000 to web |
| Network to fleet | SSH (22 or custom) to managed hosts |
Resource ballpark
| Fleet size | Rough guide |
| Lab / few Pis | 2 CPU, 2–4 GB RAM |
| Larger fleet | Raise CELERY_CONCURRENCY; more RAM for parallel rsync |
See Multi-worker Celery.
Managed hosts (the fleet)
| OS | Support notes |
| Raspberry Pi OS / Debian / Ubuntu | Full path: apt OS patch, least-priv user scripts, rsync sudo |
| HAOS / specialised | Key deploy + plain rsync guidance; no automated least-priv |
PiHerder probes dependencies for enabled features only (no auto-install on the remote).
| Feature enabled | Remote tools expected |
| Always | SSH + shell |
| Backups | rsync on PATH; sudo -n rsync or plain rsync (root/HAOS) |
| Docker / containers | docker (+ group/socket as needed) |
| OS patch | apt-get / apt |
Operator workstation
- Modern browser (Chrome/Firefox/Safari/Edge)
- For Web Push on phones: trusted HTTPS + (iOS) Add to Home Screen — see PWA & Web Push
Secrets you must keep safe
| Secret | Why |
PIHERDER_MASTER_KEY | Fernet key for SSH keys, integration tokens, template secrets, VAPID private key |
SECRET_KEY | Session/JWT signing |
| Postgres password | If you change defaults |
| TLS private key | certs/privkey.pem |
Never commit .env or PEMs
They are gitignored. Losing PIHERDER_MASTER_KEY means encrypted fields in a restored DB/self-backup cannot be decrypted.