Runbooks
A runbook is successful when future-me can repeat a task without reconstructing an old chat or relying on undocumented memory.
Publication contract
Each technical recipe should cover:
- Goal and scope — what the recipe does and does not cover.
- Tested environment — operating system, runtime, version, CPU/GPU assumptions and dependencies.
- Inputs and secrets — example variables, with secret values excluded from Git.
- Installation — exact commands and configuration examples, in a reproducible sequence.
- Verification — health checks, sample requests, expected output and exit criteria.
- Troubleshooting — symptoms, diagnostics, likely causes and safe remedies.
- Upgrade and rollback — backup, migration, restore and clean uninstall where relevant.
- Security boundaries — binding addresses, authentication, permissions and sensitive logs.
- Evidence and revision — tested date, test host class, source versions and known limits.
Scope
Public topics can include general Linux/Docker setup, serving an openly available model with vLLM, generic GPU observability, API service deployment and test automation. Real employer configurations and internal services must be maintained in a private field manual instead.
Use the runbook template before publishing a new guide.