Homelab Documentation¶
Welcome to the homelab infrastructure documentation. This site is generated from
the homelab monorepo using
mkdocs-material and auto-deploys on merge to main.
What's Here¶
| Section | Description |
|---|---|
| Architecture | ADRs, network diagrams, lab audit |
| Hosts | Per-host documentation (auto-generated stubs) |
| Services | Per-service documentation (auto-generated stubs) |
| Appliances | Network gear, NAS, managed appliances |
| Customer Apps | Apps with their own deploy pipelines |
| Security Register | Tracked findings and remediation status |
| Runbooks | Operational procedures |
| Postmortems | Incident write-ups |
| Bus Factor | What someone else needs to know to keep the lights on |
Key Principles¶
- Inventory is the source of truth. Hosts, services, and networks are defined
in
inventory/YAML files. Generators produce Ansible inventory, Prometheus targets, Homepage config, and doc stubs from that single source. mainis production.ansible-pullreconciles frommainevery 30 minutes. All changes go through PRs.- Secrets are encrypted in git. SOPS + age, with keys stored in 1Password.
- Entity boundaries matter. The repo manages different things differently — see the entity class table in PLAN.md.
Quick Links¶
- PLAN.md — master plan and execution spec
- Adding a Service — how to onboard a new service (Phase 4+)
- Secrets — bootstrap and rotation procedures (Phase 2+)