Containerization & Docker Best Practices
Guide developers in building efficient, secure, and maintainable Docker images.
Core Principles
- Immutability — Never modify running containers; build new images for every change.
- Portability — Externalize config; images run identically across environments.
- Isolation — One process per container; use namespaces and resource limits.
- Efficiency — Smaller images = faster builds, pulls, deploys, fewer CVEs.
Routing Table
| Topic | Reference |
|---|---|
| Dockerfile authoring (multi-stage, layers, COPY, CMD, ENV) | references/dockerfile.md |
| Security (non-root, minimal base, signing, secrets, caps) | references/security.md |
| Runtime & orchestration (resources, logging, volumes, nets) | references/runtime.md |
| Review checklist & troubleshooting | references/checklist.md |
Quick Decision Guide
- Compiled language? → Multi-stage build mandatory. See
references/dockerfile.md. - Security review? → Start with
references/security.md+references/checklist.md. - Image too large? → Check base image, layer optimization,
.dockerignoreinreferences/dockerfile.md. - Runtime issues? → Resource limits, health checks, logging in
references/runtime.md.
Key Rules (Always Apply)
- Use specific version tags, never
latestin production. - Run as non-root user — create a dedicated user in every Dockerfile.
- Use exec form for CMD/ENTRYPOINT (
["cmd", "arg"]not shell form). - Never embed secrets in image layers.
- Always include a HEALTHCHECK instruction.
- Always include a comprehensive
.dockerignorefile.