Top 15 Mistakes in Dockerfile Writing

Introduction

The Dockerfile is the blueprint for your containerized application. It’s a simple text file, yet its structure and content critically influence the resulting image's size, security, build time, and, ultimately, the application’s reliability in production. While Docker has streamlined application packaging, many developers and DevOps engineers inadvertently introduce costly mistakes into their Dockerfiles, often leading to slow builds, bloated images, and serious security vulnerabilities that could easily be avoided.

In a continuous delivery pipeline, an inefficient Dockerfile translates directly into wasted time, slow feedback loops, and increased operational costs. A large image takes longer to pull, a vulnerable image poses a security threat, and a poorly structured Dockerfile unnecessarily consumes build resources with every commit. Addressing these issues is fundamental to adopting a successful DevSecOps strategy, ensuring that security and efficiency are baked into the core of your application deployment process.

This comprehensive guide breaks down the 15 most common and impactful mistakes in Dockerfile writing. We'll explore why each mistake is problematic and, most importantly, provide the best practice solution, often relying on core features like multi-stage builds and leveraging the power of Docker's layer caching mechanism. By mastering these best practices, you can significantly optimize your container builds, enhance your application's security posture, and improve the overall efficiency of your CI/CD pipeline, ensuring your deployments are fast, secure, and reliable.

Mistakes in Efficiency and Image Size

Bloated Docker images are slow to build, slow to deploy, and consume unnecessary bandwidth and storage. Many mistakes related to image size stem from misunderstanding Docker's layer caching mechanism and failing to clean up temporary files efficiently. Optimizing the build process is a direct win for team productivity and release cadence.

1. Not Using Multi-Stage Builds

The Mistake: Using a single-stage Dockerfile that includes all build-time dependencies (compilers, SDKs, test frameworks) in the final production image. This results in unnecessarily large images and a huge attack surface.

The Solution: Implement multi-stage builds. Use a builder stage for compilation and testing, and a separate, minimal final stage that copies only the necessary runtime artifact (e.g., the compiled binary or JAR file) from the builder. This dramatically reduces the final image size and removes development tools.

# Stage 1: The builder
FROM node:18-slim AS builder
# ... install dev dependencies and build app ...

# Stage 2: The final, minimal image
FROM node:18-alpine
COPY --from=builder /app/dist /app
CMD ["node", "/app/dist/main.js"]
        

2. Incorrect Ordering of Instructions

The Mistake: Placing instructions that change frequently (like COPY . .) before instructions that change infrequently (like RUN apt-get update or RUN npm install). This breaks the Docker layer cache unnecessarily, forcing a full rebuild of dependency layers with every single code change, which severely slows down CI/CD pipelines.

The Solution: Order instructions from least frequently changed to most frequently changed. Dependencies (RUN npm install) should come before application code (COPY . .). This allows Docker to use the fast, cached layers for dependencies until the dependency list (e.g., package.json) changes.

3. Not Cleaning Up Dependencies and Cache

The Mistake: Running package installations (apt-get install) and failing to clean up installation caches and temporary files in the same RUN command. Each RUN instruction creates a new layer, and files created in that layer persist, even if you try to rm them in a subsequent layer. Files must be deleted in the same layer they were created.

The Solution: Combine installation and cleanup into a single RUN command using the && operator. For Debian-based systems, this means immediately running rm -rf /var/lib/apt/lists/ after apt-get install to keep the layer small.

4. Using ADD Instead of COPY

The Mistake: Using ADD to transfer local files into the image. ADD has two extra behaviors: it can fetch files from a remote URL and automatically extract compressed archives (tar, gzip). These implicit behaviors can be insecure (fetching untrusted URLs) or non-obvious (unexpected decompression).

The Solution: Almost always use COPY. COPY is transparent, deterministic, and only supports copying local files or directories, making it safer and easier to understand. Reserve ADD only for the rare case where you specifically need its automatic archive extraction feature.

5. Pulling the latest Tag for Base Images

The Mistake: Using a non-specific tag like FROM ubuntu:latest or FROM node:latest. The latest tag is mutable; it changes over time. This means the image you built yesterday may not be the same as the one you build tomorrow, leading to non-reproducible builds and deployment failures.

The Solution: Always use specific, immutable tags for base images, such as FROM python:3.10.12-slim or FROM node:18.12.0-alpine. This guarantees that your environment is always reproducible, which is foundational for reliable Continuous Delivery and simplifies troubleshooting when issues are specific to a version update.

Mistakes in Security and Governance

The number one source of container security risk is the Dockerfile itself. Failure to drop privileges, configure security contexts, and manage operating system dependencies properly leaves your container vulnerable to privilege escalation attacks and container breakouts. Secure Dockerfiles are non-negotiable for DevSecOps and modern production environments.

6. Running as the Root User (A Security Sin)

The Mistake: Running the application process inside the container as the default root user (UID 0). If an attacker manages to exploit a vulnerability in your application, they gain root-level access within the container, which can potentially lead to a container breakout and compromise the underlying host system, bypassing security tools like SELinux.

The Solution: Always use the USER instruction to drop privileges. Create a non-root user inside the container and switch to that user before running your application (USER appuser). For maximum security, use distroless images or implement rootless container execution on the host system.

FROM node:18-alpine

RUN adduser -D appuser
USER appuser

CMD ["node", "app.js"]
        

7. Not Adding Security Tools to the Base Image

The Mistake: Building images without including essential security configurations or audit tools that are needed at runtime or for forensic analysis. Relying solely on external tools for security means you lose visibility inside the container once it's deployed, especially during an incident.

The Solution: Ensure your base images or custom Dockerfiles include necessary security configurations and hardening measures. This includes setting up logging and audit tools. When using enterprise operating systems, leverage built-in features for enhanced security, such as those related to RHEL 10 security enhancements, ensuring the final image inherits a strong security posture from a trusted base.

8. Exposing Sensitive Data via ENV or Logs

The Mistake: Defining secrets (passwords, tokens) using the ENV instruction in the Dockerfile. Environment variables set by ENV are stored as plaintext metadata in the image layer and can be easily viewed by anyone with access to the image (via docker history or inspection). Additionally, secrets are often exposed in build logs.

The Solution: Never use ENV for secrets. Secrets must be injected dynamically at runtime, either via a secret management tool (e.g., Vault, AWS Secrets Manager) or mounted as temporary files/volumes, adhering to the principle of least exposure. Use the --secret flag in Docker BuildKit to securely handle build-time secrets.

9. Running RUN apt-get update Without apt-get install

The Mistake: Separating RUN apt-get update into its own line, only to execute RUN apt-get install in a subsequent layer. If the cache for apt-get update is hit (which happens frequently), the subsequent apt-get install command will install outdated, potentially vulnerable packages without getting the latest security patches.

The Solution: Always combine apt-get update and apt-get install into a single RUN command. This ensures that the installation command always pulls the latest package versions and security fixes available at the time of the build, preventing the use of stale package lists and minimizing the time-to-exploit vulnerability window.

RUN apt-get update && apt-get install -y \
    package-a \
    package-b \
    && rm -rf /var/lib/apt/lists/*
        

10. Copying Too Much Content (COPY . .)

The Mistake: Blindly copying the entire build context (COPY . . or ADD . /app) early in the Dockerfile. This often includes unnecessary files (IDEs configs, documentation, large asset files, .git history) that bloat the image and, more critically, cause the layer cache to break frequently whenever any file changes, slowing the build.

The Solution: Use a .dockerignore file to exclude unnecessary files from the build context (logs, .git directories, .idea/). More importantly, only COPY the specific files needed for the current build layer (e.g., COPY package.json . before RUN npm install, and then COPY . . later). This preserves the cache for dependency steps.

Mistakes in Operation and Reliability

Operational issues often arise from misconfigured startup commands, missing health checks, and incorrect port exposures. A reliable Dockerfile must clearly define the application's entry point and provide the necessary telemetry to confirm its health post-deployment. These practices directly impact system stability and the efficiency of incident management.

11. Misunderstanding CMD vs. ENTRYPOINT

The Mistake: Confusing the roles of CMD and ENTRYPOINT. Using CMD for the main application executable and then finding that running the container with an argument (e.g., docker run image ls -l) completely overrides the application startup, causing runtime errors.

The Solution: Use ENTRYPOINT to set the executable (e.g., /usr/bin/java, node, or a shell script wrapper) that should always run. Use CMD to provide default arguments to that executable. Using the exec form (["executable", "param1"]) is preferred over the shell form (CMD executable param1) for better signal handling and integration with release cadence processes.

ENTRYPOINT ["java", "-jar", "/app/app.jar"]
CMD ["--server.port=8080"]
# Running 'docker run image --debug' executes:
# java -jar /app/app.jar --debug
        

12. Forgetting Health Checks

The Mistake: Failing to include a HEALTHCHECK instruction. Without a health check, the container orchestrator (e.g., Kubernetes, Docker Swarm) only knows if the process is running, not if the application inside is actually ready to serve traffic (e.g., database connection established, configuration loaded). This can cause load balancers to route traffic to an unhealthy service, leading to 5xx errors.

The Solution: Always include a HEALTHCHECK instruction that periodically runs a command (often curl or a custom script) to check the application's readiness. This enables orchestrators to accurately assess the service's health and reliably route traffic only to responsive instances, which is crucial for high availability.

13. Not Leveraging .dockerignore

The Mistake: Similar to mistake 10, but specifically forgetting the .dockerignore file altogether. This causes the Docker daemon to send the entire project directory (including .git, node_modules, logs) as the build context to the build host, wasting network bandwidth and time even if the files are not copied to the final image.

The Solution: Always create a .dockerignore file and list all files and directories that are not needed for the build. This optimizes the initial build context transfer, significantly speeding up the start of the build process, especially in remote or cloud-based CI/CD environments.

14. Over-Configuring Environment Variables

The Mistake: Using a long list of ENV instructions for configuration that could be better managed at runtime via configuration files, volume mounts, or secrets management. Excessive environment variables clutter the container environment and make debugging complex.

The Solution: Use ENV only for immutable, necessary environment settings (e.g., paths, non-sensitive default ports). Rely on configuration files (loaded at startup) or dynamic injection via orchestration tools for sensitive or environment-specific values. This simplifies debugging and management, particularly when trying to trace issues using observability pillars data.

15. Relying on Old/Outdated Distros

The Mistake: Using very old or unsupported Linux distributions (e.g., CentOS 6, Ubuntu 14.04) as base images. These images often have known, unpatched vulnerabilities and lack modern security features or necessary package dependencies, creating compliance and security nightmares.

The Solution: Use actively maintained, modern, and minimal distributions like Alpine, Debian Slim, or enterprise-supported images like RHEL UBI (Universal Base Image). Modern distributions ensure you have access to the latest security features and patches, keeping your application secure and simplifying compliance and vulnerability scanning efforts, which is a core tenet of proactive security management.

Conclusion

The Dockerfile is a foundational contract between your application code and the production environment. By actively avoiding these 15 common mistakes, you move beyond merely containerizing your application to building truly cloud-native, production-ready containers. The adoption of multi-stage builds and strict clean-up practices significantly reduces image size and accelerates build times, directly enhancing your productivity and pipeline throughput. Implementing security best practices—such as running as a non-root user and properly managing secrets—fortifies your application against common attacks.

Ultimately, a reliable Dockerfile contributes to a reliable application. Consistency in tagging, correct use of ENTRYPOINT and CMD, and the inclusion of explicit HEALTHCHECK instructions ensure that your application starts correctly and reports its operational status accurately to orchestrators. This discipline is essential for maximizing the efficiency of your CI/CD process and minimizing operational risk. Make these practices standard across your team, and your Dockerfiles will become not just blueprints, but robust pillars of your overall DevOps strategy.

The best practice is always to keep your Dockerfiles minimal, intentional, and secure. Continuously audit them with automated tools to catch security issues and enforce consistency. By focusing on these principles, you ensure your containers are ready for any environment, supporting high-velocity, reliable, and secure software delivery, proving that efficiency and security are mutually achievable goals in the modern era.

Frequently Asked Questions

What is the benefit of using Multi-Stage Builds?

Multi-stage builds reduce the final image size by discarding build-time dependencies (compilers, SDKs) and copying only the essential runtime artifacts into a minimal final image, saving deployment time and disk space.

Why is running a container as root a security risk?

If an application is compromised while running as root, the attacker gains root-level privileges inside the container, increasing the risk of a container breakout and compromise of the underlying host system, bypassing security controls like SELinux.

Why must I combine apt-get update and apt-get install into one RUN command?

Combining them ensures that the installation always uses the most recent package list, preventing the installation of outdated, potentially vulnerable packages from a cached, stale package list.

How does incorrect instruction ordering break the layer cache?

Placing frequently changing instructions (like application code COPY) before infrequently changing ones (like dependency RUN) invalidates the cache for all subsequent layers, forcing the pipeline to rebuild slow dependency steps unnecessarily with every code change.

Should I use ADD or COPY in my Dockerfile?

You should almost always use COPY because it is deterministic and safer, supporting only local file copies. Reserve ADD only for cases where automatic archive extraction is specifically required.

What is the purpose of the HEALTHCHECK instruction?

The HEALTHCHECK instruction tells the orchestrator (e.g., Kubernetes) how to verify that the application inside the container is actually ready to serve traffic, preventing load balancers from routing requests to an unhealthy instance, which is crucial for Continuous Delivery reliability.

Why is it important to use a specific tag instead of latest for base images?

Using a specific tag (e.g., python:3.10-alpine) guarantees reproducible builds, as the latest tag is mutable and can change unexpectedly, leading to non-deterministic behavior and errors in the CI/CD pipeline.

How can I secure secrets in a Dockerfile?

Never use ENV. Use dedicated secrets management tools (like Vault or AWS Secrets Manager) to inject secrets dynamically at runtime, or use Docker BuildKit's --secret flag for build-time secrets, ensuring they are never stored in the final image or build logs.

How does using .dockerignore improve the build process?

The .dockerignore file prevents unnecessary files (like .git, logs, IDE configs) from being sent as the build context to the Docker daemon, significantly reducing network bandwidth consumption and speeding up the start of the build process.

How do RHEL 10 security enhancements apply to containers?

The base image should be built from a supported distribution, like RHEL UBI, to ensure the container inherits and leverages the latest security features, patches, and best practices from the host operating system, reducing the attack surface and simplifying compliance, aligning with RHEL 10 security enhancements best practices.

What is the preferred syntax for ENTRYPOINT and why?

The preferred syntax is the exec form (ENTRYPOINT ["executable", "param1"]), as it ensures proper signal handling, allowing the orchestrator to send termination signals (e.g., SIGTERM) directly to the application process, leading to a graceful shutdown.

How does this topic relate to release cadence?

Efficient Dockerfile writing (small size, good caching) accelerates build times, which minimizes the total lead time for changes, directly supporting a faster and more consistent release cadence in high-velocity environments.

What is the mistake in RUN apt-get update without subsequent installation?

The separated apt-get update will likely be cached, and a subsequent apt-get install will use the stale package list, missing out on the latest security patches available for the packages being installed.

Why is the post-installation checklist important for the host running containers?

The host OS must be securely configured and hardened before running containers to prevent escalation of privileges or breakouts. The checklist ensures the host meets strict security and configuration standards before the containers are launched, a key defense-in-depth strategy, often requiring automation tools to enforce the RHEL 10 post-installation checklist.

How does this practice integrate with continuous threat modeling?

The Dockerfile is the first line of defense; threat modeling identifies risks (e.g., root access, exposed ports), and the Dockerfile practices (e.g., USER, EXPOSE) are the controls implemented to mitigate those identified threats, ensuring security-by-design.