Dockerfile Basics

When to use

Build a custom image that installs your app’s dependencies on a base image.

Analogy

a Dockerfile is a kitchen recipe: FROM is base ingredients, RUN is cooking, COPY is adding ingredients, CMD is serving the dish.

Data-flow diagram

  FROM python:3.12-slim       # base layer
  WORKDIR /app
  COPY requirements.txt ./    # first (cacheable)
  RUN pip install -r ...      # second
  COPY . .                    # third (changes most often)
  CMD ["python", "app.py"]    # default command

Deep explanation

A Dockerfile is a text file Docker reads top-to-bottom. Each instruction creates a layer; layer caching reuses unchanged layers - order matters for speed. Use small base images (alpine, python:3.12-slim) for size and security. Use multi-stage builds to keep build tools out of the final image. Pin versions (no latest). Prefer exec form CMD ["x", "y"] over shell form CMD x y (which wraps in /bin/sh -c).

Examples

Example 1

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

canonical Python Dockerfile. Two COPY lines let the deps layer cache when only code changes.

Example 2

FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Node.js Dockerfile; npm ci is faster and stricter than npm install for reproducible builds.

Example 3

FROM golang:1.22 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o /out/app
FROM gcr.io/distroless/static
COPY --from=build /out/app /app
CMD ["/app"]

multi-stage: build a Go binary in stage 1, copy binary to distroless static base - final image ~20MB with no shell.

Common mistake

Using a fat base like ubuntu:latest (hundreds of MB); putting COPY . . early (invalidates cache on every file change); forgetting to pin versions.

Key takeaway

Small base; pin versions; separate dependency-copy from source-copy; multi-stage for compiled languages; prefer exec form CMD; treat your Dockerfile as code.

Production Failure Playbook

Failure scenario 1: image-1-6-gb-ubuntu-base

• Symptom: CI build took 6min and registry bandwidth cost was high.
• Detection: docker images size column; build logs.
• Root cause: FROM ubuntu:22.04 included apt cache + tools; image was 1.6GB.
• Mitigation: switch to python:3.12-slim or alpine; multi-stage for compiled parts.
• Prevention: ADR: image size limit (e.g. <200MB); CI check via dive or size-limit.

Failure scenario 2: cache-invalidation-slow-builds

• Symptom: every code change rebuilt dependencies - build time from 30s to 7min.
• Detection: build logs show each RUN pip install runs every time.
• Root cause: Dockerfile did COPY . . BEFORE pip install; source change invalidated deps layer.
• Mitigation: reorder: copy requirements.txt first, install, then copy source.
• Prevention: Dockerfile best-practice linter (hadolint); review checklist.