Docker Compose

Opinionated conventions for consistent, maintainable Docker Compose files.

Best Practices

File naming and override strategy

• Prefer compose.yaml (or compose.yml) as the canonical base file.
• Keep local-only changes in compose.override.yaml (auto-merged by Compose).
  • If an override file is local-only, add it to .gitignore unless the team explicitly wants it committed (optionally keep a .example file).
• For environment-specific configs, use compose.<env>.yaml and combine with -f.
• Avoid the top-level version key (obsolete).

Service naming and identity

• Use kebab-case service names; they become internal DNS names.
• Avoid container_name unless strictly required; it prevents scaling.
• Pin image tags (avoid latest); prefer digests for production.