| 1 | # Docker Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | Dedicated playbook for containerized development, testing, and operational reproducibility. |
| 5 | |
| 6 | ## Scope |
| 7 | - Image and build discipline |
| 8 | - Runtime contracts and environment parity |
| 9 | - Volume/network/process safety |
| 10 | - Security and supply-chain hygiene |
| 11 | |
| 12 | ## Evidence-Based Working Format |
| 13 | - Fact: define the reproducibility or environment mismatch issue. |
| 14 | - Hypothesis: specify which container change resolves it. |
| 15 | - Check: verify with smallest reproducible container scenario. |
| 16 | - Decision criterion: success/failure thresholds before rollout. |
| 17 | - Confidence mark: explicit certainty level. |
| 18 | |
| 19 | ## Build Contracts |
| 20 | - Pin base image families and document update cadence. |
| 21 | - Keep images minimal and purpose-specific. |
| 22 | - Separate build and runtime stages where possible. |
| 23 | - Cache dependencies consciously; avoid stale artifact masking. |
| 24 | |
| 25 | ## Runtime Contracts |
| 26 | - Make ports, volumes, and env vars explicit. |
| 27 | - Keep working directory mapping deterministic. |
| 28 | - Prefer immutable container behavior for CI. |
| 29 | - Ensure graceful startup/shutdown signals for app processes. |
| 30 | |
| 31 | ## Project-Aware Contracts |
| 32 | - Bind only required host paths into containers. |
| 33 | - Avoid hidden host dependencies. |
| 34 | - Align container entrypoints with repository task contracts. |
| 35 | - Document command parity between local and CI usage. |
| 36 | |
| 37 | ## Security Contracts |
| 38 | - Avoid running as root unless required and justified. |
| 39 | - Scan image dependencies on update cycles. |
| 40 | - Keep secrets out of images and compose files. |
| 41 | - Restrict capabilities and networking surface area when possible. |
| 42 | |
| 43 | ## Metrics |
| 44 | - Local vs CI parity failure rate. |
| 45 | - Time to reproduce environment-specific defects. |
| 46 | - Container startup time for core workflows. |
| 47 | - Frequency of image-related regressions. |
| 48 | |
| 49 | ## Revisit Triggers |
| 50 | - Repeated “works locally but not in CI” incidents. |
| 51 | - Frequent image bloat or slow build regressions. |
| 52 | - Security findings with recurring root causes. |
| 53 | |
| 54 | |