Docker Best Practices

Building and running containers in production requires more than knowing the commands. Following established best practices results in images that are smaller, faster, more secure, and easier to maintain.

Use Minimal Base Images

Every byte in a base image adds to pull time, storage, and attack surface. Prefer minimal bases:

• alpine — tiny (~5 MB), great for compiled binaries
• distroless — no shell at all, minimal OS; ideal for security-sensitive workloads
• slim variants — language-specific images with fewer packages (e.g. node:20-slim)

# Prefer this
FROM node:20-alpine

# Over this
FROM node:20

Run as a Non-Root User

By default, processes in a container run as root. This is a security risk — if an attacker exploits your application, they have root privileges inside the container. Always create and switch to a non-root user:

FROM node:20-alpine

WORKDIR /app
COPY --chown=node:node . .
RUN npm ci --omit=dev

# Switch to the built-in non-root user
USER node

CMD ["node", "src/index.js"]

Pin Image Versions

Never use latest in production Dockerfiles. Use specific version tags so builds are reproducible and upgrades are intentional:

# Bad: unpredictable
FROM postgres:latest

# Good: explicit and reproducible
FROM postgres:16.2-alpine3.19

Minimise Layers and Layer Size

Each RUN instruction creates a layer. Chain related commands with && and clean up in the same layer so the intermediate files are never committed:

# Bad: three layers, apt cache left in the image
RUN apt-get update
RUN apt-get install -y curl
RUN apt-get clean

# Good: one layer, cache cleaned in the same step
RUN apt-get update     && apt-get install -y --no-install-recommends curl     && rm -rf /var/lib/apt/lists/*

Use .dockerignore

A .dockerignore file prevents unnecessary files from being sent to the Docker daemon as the build context, speeding up builds and keeping secrets out of images:

# .dockerignore
.git
node_modules
.env
*.log
dist
coverage
.DS_Store

Health Checks

Define a HEALTHCHECK so Docker (and orchestrators like Kubernetes) know whether your container is actually healthy, not just running:

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3   CMD curl -f http://localhost:3000/health || exit 1

Keep Images Stateless

Containers should be stateless and treat any writable data as temporary. Persist all state in volumes or external services (databases, object storage). This enables containers to be stopped, replaced, and scaled without data loss.