Lesson 25 / 25

A Compose File Review Checklist

Before sharing or deploying.

By · 15 years in web development

Questions to ask

Does docker compose config pass (in CI too)? Are images pinned and builds using .dockerignore? Are required variables marked with ${VAR:?...} and is a .env.example committed? Are secrets delivered as files and kept out of git? Do dependencies use health checks and service_healthy conditions? Are only necessary ports published, with dev ports bound to localhost? Are databases on named volumes and isolated networks, with a backup plan? Are dev conveniences in the override file and production settings in a separate file? Are optional tools behind profiles?

The checklist

Use it in reviews.

[ ] docker compose config passes locally and in CI
[ ] pinned image tags; .dockerignore for builds
[ ] ${VAR:?message} for required values; .env.example committed, .env ignored
[ ] secrets as files (secrets: + *_FILE), not plain env vars
[ ] health checks + depends_on condition: service_healthy
[ ] minimal published ports; dev ports on 127.0.0.1
[ ] named volumes for data; backups tested
[ ] tiered networks; internal: true for data stores
[ ] dev tweaks in compose.override.yaml; prod via -f compose.prod.yaml
[ ] optional tools behind profiles; restart policies and log rotation on servers

Diff the merged config

When changing environments, compare docker compose config output before and after to see exactly what changes.

Quick check: Which item belongs on a Compose review checklist?

  • Commit the real .env with passwords
  • Publish every database port on all interfaces
  • Required variables use ${VAR:?message}
  • Use the latest tag everywhere
Answer

Required variables use ${VAR:?message} — Fail fast, expose little, keep secrets out of git.