Dockerfile best practices
A production-ready Dockerfile template with security-focused best practices for building reliable container images.
What is Dockerfile best practices?
Dockerfile is a curated collection of best practices and a template Dockerfile for creating production-ready container images. It addresses common security and reliability issues in Docker image creation by providing specific guidance on user management, version pinning, signal handling, and file permissions.
Developers, DevOps engineers, and platform teams who build and maintain Docker images for production environments and want to avoid common security pitfalls.
It offers battle-tested recommendations from real production experience at companies like Sourcegraph, providing a ready-to-use template that balances security, maintainability, and practical deployment concerns better than generic Docker documentation.
Overview
Dockerfile best-practices for writing production-worthy Docker images.
Use Cases
Best For
- Securing Docker images against privilege escalation attacks
- Establishing consistent file permission patterns across containers
- Implementing reliable signal handling in containerized applications
- Creating reproducible builds while maintaining security updates
- Onboarding teams to Docker best practices quickly
- Auditing existing Dockerfiles for security improvements
Not Ideal For
- Projects requiring absolute build reproducibility via SHA pinning, as the template favors major.minor tags for security updates
- Large organizations with established container security pipelines that already enforce custom best practices
- Applications that must run as root for legitimate reasons, such as accessing privileged ports or system resources
Pros & Cons
Pros
Enforces non-root user execution and UIDs above 10,000 to mitigate privilege escalation risks, backed by references to Docker docs and Bitnami's security analysis.
Provides a ready-to-copy Dockerfile with detailed comments derived from real-world experience at companies like Sourcegraph, saving setup time and reducing common errors.
Recommends major.minor image tags to receive security updates while maintaining stability, and suggests tools like docker-lock for reproducibility without manual SHA tracking.
Integrates tini as the ENTRYPOINT to ensure proper signal processing and prevent zombie processes, even in environments like Kubernetes where Docker's --init is not default.
Cons
Fixed UID/GID of 10000:10001 may conflict with existing system users or container orchestration standards, requiring manual adjustments for integration.
Includes dependencies like tini and bind-tools (for Alpine) which add layers and maintenance overhead, potentially over-engineering simple containerized applications.
The major.minor pinning strategy introduces build variability, which might be unacceptable for strict compliance or auditing needs that demand SHA-based reproducibility.
Frequently Asked Questions
Related Projects
Docker CaveatsWhat You Should Know About Running Docker In Production (written 11 APRIL 2016) MUST SEE
GUI Apps with Dockerby fgrehm
Docker vs. VMs? Combining Both for Cloud Portability NirvanaDon't Repeat Yourself with Anchors, Aliases and Extensions in Docker Compose Filesby King Chung Huang
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.