Dockerfile Best Practices – Write Leaner, Safer, and Faster Images

Introduction – Why Dockerfile Best Practices Matter

“A clean Dockerfile is a happy Dockerfile.” — Every DevOps Engineer Ever

Creating a Dockerfile may seem like a simple task, but every line impacts security, performance, and image size. As containers scale in production, poorly written Dockerfiles can slow you down and create vulnerabilities.

In this article, you’ll learn:

• The top 10 best practices for writing Dockerfiles
• How to reduce image size and speed up build time
• Key security tips for safe container environments
• FAQs to clarify common Dockerfile mistakes

1. Choose a Small and Efficient Base Image

Why it matters:
Smaller base images lead to faster downloads, smaller footprints, and improved security.

Best Practice:
Use minimal images like alpine, debian:slim, or gcr.io/distroless.

FROM alpine:latest

Pro Tip:
Test binary compatibility with Alpine to avoid runtime issues.

Additional Tip:
Consider using official language-specific slim variants (e.g., python:3.10-slim) for better compatibility.

2. Clean Up After Installing Packages

Why it matters:
Leftover cache files bloat your image unnecessarily.

Best Practice:
Combine installation and cleanup in a single RUN command.

RUN apk add --no-cache curl && \
    rm -rf /var/cache/apk/*

Note: Multiple RUN layers increase image size. Combine wisely.

Additional Tip:
Use tools like docker-slim to automatically shrink and optimize built images.

3. Combine Commands Using &&

Why it matters:
Each RUN instruction creates a new layer. Excess layers = larger image.

Best Practice:

RUN apt-get update && apt-get install -y nginx && apt-get clean

This keeps your image compact and reduces intermediate layers.

Additional Tip:
Always verify commands using && to catch errors early and prevent silent failures.

4. Use a .dockerignore File

Why it matters:
Prevents Docker from copying unnecessary files into the build context.

Best Practice:

Add a .dockerignore file containing:

node_modules
.git
*.log
.env
tests/
build/

Result: Faster build time and smaller images.

Additional Tip:
Regularly audit .dockerignore entries during CI updates to prevent leakage of sensitive or bulky files.

5. Don’t Run as Root Inside the Container

Why it matters:
Containers running as root are more vulnerable to exploits.

Best Practice:

RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

Security First: Always use the principle of least privilege.

Additional Tip:
Map volumes with proper access permissions to avoid permission denied errors.

6. Set a Working Directory

Why it matters:
Defines a default directory for all file operations and commands.

Best Practice:

WORKDIR /app

Bonus Tip: Be consistent with your path structures.

Additional Tip:
Avoid relative paths (./folder) in COPY if WORKDIR is already defined. Stick to absolute structure.

7. Use Multi-Stage Builds to Keep It Clean

Why it matters:
Separates build tools from the final production image.

Best Practice:

# Stage 1: Build
FROM node:18 AS builder
WORKDIR /app
COPY . .
RUN npm install && npm run build

# Stage 2: Final image
FROM nginx:alpine
COPY --from=builder /app/build /usr/share/nginx/html

Result: Smaller, production-ready images without dev dependencies.

Additional Tip:
You can have more than two stages (e.g., builder, tester, runtime) to streamline large pipelines.

8. Use COPY Instead of ADD (Most of the Time)

Why it matters:
ADD has side-effects like extracting archives or fetching URLs.

Best Practice:

COPY ./src /app/src

Rule of Thumb: Use ADD only when needed.

Additional Tip:
Always validate .tar auto-extraction behavior of ADD to avoid confusion.

9. Add Labels for Metadata

Why it matters:
Labels help automate tools, organize metadata, and provide clarity.

Best Practice:

LABEL maintainer="you@domain.com" \
      version="1.0" \
      description="My production-ready container"

Pro Tip: Use Label Schema standards for consistency.

Additional Tip:
Label image creation time using build arguments.

10. Pin Version Numbers

Why it matters:
Pinning avoids accidental updates and ensures consistent builds.

Best Practice:

FROM node:18.16.0

Avoid using:

FROM node:latest

It could change tomorrow and break your build.

Additional Tip:
Use docker pull --quiet and digest pinning (@sha256) for immutable builds.

Summary – Recap & Next Steps

Well-written Dockerfiles make your containers faster, leaner, and more secure. By applying these 10 best practices, you’ll reduce image size, avoid vulnerabilities, and create production-ready containers effortlessly.

Top Takeaways:

• Start with a small base image (alpine, slim, etc.)
• Combine RUN statements and clean up after installs
• Use .dockerignore to avoid copying junk
• Drop root privileges inside the container
• Leverage multi-stage builds for cleaner images

Next Steps:
Practice creating your own Dockerfiles, audit existing ones for improvements, and automate image builds using CI/CD tools.

Frequently Asked Questions (FAQs)

Why is image size such a big deal?
Smaller images reduce:

• Build and push time
• Bandwidth usage
• Deployment latency

What’s the difference between ADD and COPY?
COPY is predictable and simpler.
ADD has extra features like extracting .tar files or fetching from URLs.
Use COPY unless you need ADD.

Should I always use Alpine?
Alpine is great for minimal images.
But test compatibility—some binaries may not work well with it.

What happens if I don’t use .dockerignore?
🚨 Docker might copy:

• Git history
• Build artifacts
• Secrets like .env files

This leads to bloated images and security risks.

Is multi-stage build really worth it?
Yes. It helps:

• Keep final images clean
• Remove unnecessary build tools
• Reduce attack surface