Dockerfile Best Practices: Build Lean, Secure Containers That Survive Production

I've seen a 2GB container crash a Kubernetes node because someone COPY'd the entire node_modules folder into production. Don't be that person. Most Dockerfiles I review are bloated, insecure, and rebuild like molasses. The problem isn't Docker — it's how we write the recipe. After this article, you'll be able to write Dockerfiles that build fast, run securely, and ship images under 100MB. No fluff. Just patterns that survived production.

Layer Ordering: Why Your Builds Take Forever

Every RUN, COPY, and ADD creates a layer. Docker caches each layer. If a layer changes, all subsequent layers rebuild. The classic mistake: putting COPY . early, which invalidates the cache for every subsequent RUN. Fix: order layers from least to most frequently changing. Start with OS packages, then language-specific dependencies, then application code. This way, you only rebuild the slow parts when dependencies change, not on every code commit.

# io.thecodeforge — DevOps tutorial

# BAD: COPY . early invalidates cache
FROM node:18-alpine
WORKDIR /app
COPY . .  # changes on every commit
RUN npm install  # rebuilds every time

# GOOD: order by change frequency
FROM node:18-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install  # cached unless deps change
COPY . .  # only app code changes

Multi-Stage Builds: Drop the Build Tools

Why ship a compiler to production? Multi-stage builds let you use one image to compile and a second, minimal image to run. The classic use case: Go or Rust binaries where you compile in a full SDK image, then copy the binary to alpine. For interpreted languages, you can still separate dev dependencies from runtime. Example: Python — install all deps in build stage, then copy only the site-packages you need.

# io.thecodeforge — DevOps tutorial

# Build stage
FROM golang:1.20 AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app/myapp .

# Runtime stage
FROM alpine:3.18
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
COPY --from=builder /app/myapp /usr/local/bin/myapp
USER appuser
CMD ["myapp"]

Security: Stop Running as Root

By default, containers run as root. If an attacker exploits your app, they have root inside the container. With host PID or volume mounts, they can escape. Always create a non-root user. Use adduser (Debian) or adduser (Alpine). Set USER before CMD. Also: use specific base image tags (not latest), scan images for vulnerabilities, and avoid installing unnecessary packages.

# io.thecodeforge — DevOps tutorial

FROM node:18-alpine
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
WORKDIR /app
COPY package.json ./
RUN npm install --production
COPY . .
RUN chown -R appuser:appgroup /app
USER appuser
EXPOSE 3000
CMD ["node", "server.js"]

Layer Caching: The Art of Not Rebuilding

Docker caches each layer. To maximize cache hits: separate dependency installation from code copy. Use COPY package.json and RUN npm install before COPY .. For apt-get, combine updates and installs in one RUN to avoid stale cache. Use --no-install-recommends to reduce size. For Python, use pip install --no-cache-dir.

# io.thecodeforge — DevOps tutorial

FROM python:3.11-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]

Minimizing Image Size: Every Megabyte Counts

Large images slow down deployments and increase attack surface. Use alpine variants where possible. Remove package manager caches. Combine RUN commands. Use --no-cache for apk. For Python, use pip install --no-cache-dir. For Node, use npm ci --only=production. Use .dockerignore to exclude logs, tests, and CI files.

# io.thecodeforge — DevOps tutorial

FROM node:18-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production && npm cache clean --force
COPY . .
CMD ["node", "index.js"]

Using .dockerignore: Stop Leaking Secrets

Without .dockerignore, every file in the build context gets sent to the Docker daemon. This includes .env files, .git, node_modules, and CI configs. This slows builds and leaks secrets. Always create a .dockerignore file. At minimum, exclude node_modules, .git, .env, and any large data directories.

# io.thecodeforge — DevOps tutorial

.git
node_modules
.env
*.log
test
coverage
.gitignore
Dockerfile
.dockerignore

Health Checks: Let Orchestrators Know When You're Dead

Kubernetes and Docker Swarm use health checks to restart unhealthy containers. Without them, your app can be in a broken state but still receive traffic. Add HEALTHCHECK instruction. Use a simple command like curl --fail http://localhost:8080/health || exit 1. Make sure the health endpoint is lightweight and doesn't depend on external services.

# io.thecodeforge — DevOps tutorial

FROM node:18-alpine
# ... app setup ...
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
CMD ["node", "server.js"]

ENTRYPOINT vs CMD: Know the Difference

ENTRYPOINT defines the executable. CMD provides default arguments. If you only use CMD, users can override the entire command with docker run myimage bash. If you use ENTRYPOINT, they can only pass arguments. Best practice: use ENTRYPOINT for the binary and CMD for default flags. This makes your image behave like a CLI tool.

# io.thecodeforge — DevOps tutorial

FROM alpine:3.18
RUN apk add --no-cache curl
ENTRYPOINT ["curl"]
CMD ["--help"]
# Usage: docker run myimage https://example.com

When Not to Use Multi-Stage Builds

Multi-stage builds add complexity. For small scripts or single-file apps, a single-stage build with a slim base image is fine. If your build stage is trivial (e.g., just copying files), multi-stage adds no benefit. Also, if you need debugging tools in production (like curl, vim), you might prefer a single stage with those tools. But consider using a debug sidecar instead.

# io.thecodeforge — DevOps tutorial

# Simple static file server — single stage is fine
FROM nginx:alpine
COPY static/ /usr/share/nginx/html/
# No need for multi-stage here

Production Debugging: What to Do When Your Container Fails

Containers fail. Common issues: missing dependencies, wrong permissions, config errors. Use docker logs <container> to see stderr. Use docker exec -it <container> sh to inspect. For images, use docker run --entrypoint sh myimage to override entrypoint. Check layer sizes with docker history. Use docker image inspect to see env vars and cmd.

# io.thecodeforge — DevOps tutorial

# Check logs
docker logs mycontainer

# Interactive shell
docker exec -it mycontainer sh

# Override entrypoint to debug
docker run --entrypoint sh myimage

# See layer sizes
docker history --no-trunc myimage

# Inspect image config
docker image inspect myimage | jq '.[0].Config'