Decisions
Architecture decision records (ADRs): one short file per decision, with the problem, the options that were considered, what was chosen and what it costs. The README’s technology table says what is used; these files say why, and what was rejected. The format is MADR, shortened.
| ADR | Decision | Status |
|---|---|---|
| 0001 | Kubernetes on bare-metal nodes, not VMs | Accepted |
| 0002 | TrueNAS as a VM on Proxmox | Accepted |
| 0003 | Flux for GitOps, not Argo CD | Accepted |
| 0004 | ingress-nginx for traffic into the cluster | Superseded by 0006 |
| 0005 | Secrets in AWS SSM through External Secrets | Accepted |
| 0006 | Envoy Gateway (Gateway API) instead of ingress-nginx | Accepted |
| 0007 | restic for laptop backups, not Kopia | Accepted |
| 0008 | Renovate for dependency updates | Accepted |
| 0009 | A GitHub App for Flux’s commit statuses | Accepted |
| 0010 | No bot account or auto-approval for Claude’s pull requests | Accepted |
| 0011 | Alerts from Alertmanager to Telegram, and Uptime Kuma moved to Proxmox | Accepted |
| 0012 | Pi-hole stays in an LXC on Proxmox, not in Kubernetes | Accepted |
| 0013 | Uptime Kuma installed with Node.js in its LXC, not in Docker | Accepted |
| 0014 | Services needed to run or fix the cluster stay outside Kubernetes | Accepted |
| 0015 | A Hugo website built from docs/, published to GitHub Pages | Accepted |
0001 to 0006 were written down after the fact, in November 2026.
When to write one
- A new technology is added, or one replaces another.
- A choice between real alternatives that would be expensive to undo.
Not for version bumps, config changes or small fixes. The ADR goes in the same pull request as the change.
How
- Copy template.md to
NNNN-short-title.mdwith the next number. - Keep it short. The options and their reasons matter most.
- Add it to the table above, and link it from the technology choices if it is there.
An accepted ADR is not rewritten. When a decision changes, write a new ADR and set the old
one’s status to superseded by [NNNN](NNNN-...md).