Dockerfile CMD Shell Form — Why SIGTERM Fails

Dockerfiles eliminate environment drift. A Dockerfile is a plain-text script that defines every dependency, runtime, and configuration your application needs. Docker reads it and builds an image — a portable, immutable snapshot that runs identically on any machine.

The layer caching mechanism is the single most important concept. Each instruction creates a cached layer. Changing one instruction invalidates all subsequent layers. Order your instructions from least-likely-to-change to most-likely-to-change to maximize cache hits during development.

Three misconceptions cause the most production issues: CMD without exec form silently breaks graceful shutdown in Kubernetes, ENV and ARG are visible in docker history (never put secrets in them), and .dockerignore is not optional (COPY . . without it bakes secrets and gigabytes of junk into the image).

What Dockerfile CMD Shell Form Actually Does

The Dockerfile CMD instruction defines the default command that runs when a container starts. In shell form — CMD command param1 — Docker wraps it as /bin/sh -c "command param1". That shell process becomes PID 1 inside the container, not your application. This matters because PID 1 in Linux has a unique responsibility: it must handle SIGTERM and other signals sent by docker stop. When you use shell form, your Java app (e.g., java -jar app.jar) runs as a child of sh, not as PID 1. Docker stop sends SIGTERM to PID 1 — the shell — which by default does not forward signals to child processes. Your JVM never sees SIGTERM. After a 10-second grace period, Docker escalates to SIGKILL, killing the JVM abruptly. This means no graceful shutdown: no shutdown hooks, no draining connections, no flushing buffers. In production, this causes dropped requests, corrupted state, and angry users. Use exec form — CMD ["java", "-jar", "app.jar"] — to make your app PID 1 and receive signals directly.

How Docker Builds an Image — Layers Are Everything

Before you write a single Dockerfile instruction, you need a mental model of what Docker is actually doing when it reads your file. Docker doesn't build one monolithic blob. It builds a stack of read-only layers, one per instruction. Each layer is a diff — only the filesystem changes from that step.

Why does this matter? Because Docker caches every layer. If you rebuild an image and nothing changed in a particular step, Docker reuses the cached layer instead of running it again. This turns a 3-minute build into a 4-second build. But the cache is sequential — as soon as one layer is invalidated (because something changed), every layer after it is also invalidated and rebuilt from scratch.

This single insight drives the most important Dockerfile design decision you'll ever make: order your instructions from least-likely-to-change to most-likely-to-change. Your base OS almost never changes. Your system dependencies change occasionally. Your app's package dependencies change sometimes. Your source code changes constantly. Structure your Dockerfile in that order and you'll get near-instant cached rebuilds during development.

Think of layers like a stack of transparent slides on an overhead projector. Each slide adds something. You can swap out the top slide without reprinting all the slides beneath it.

Layer size and the cleanup-in-same-layer rule: Each RUN instruction creates a new layer. If you download a 200MB package in one RUN and delete it in the next RUN, the 200MB still exists in the first layer — layers are additive. The delete only adds a whiteout marker. Always chain download and cleanup in the same RUN with && to avoid bloating the image with phantom files.

# Layer 1 — Base image pulled from Docker Hub.
# This layer is cached after the first pull and almost never changes.
FROM node:20-alpine

# Layer 2 — Set the working directory inside the container.
# All subsequent instructions run relative to this path.
WORKDIR /app

# Layer 3 — Copy ONLY the dependency manifest files first.
# Separating this from the source code is the key cache optimization.
# This layer only rebuilds when package.json or the lockfile changes.
COPY package.json package-lock.json ./

# Layer 4 — Install dependencies.
# Because we copied manifests separately above, npm install only re-runs
# when a dependency actually changes — not every time you edit a .js file.
RUN npm ci --omit=dev

# Layer 5 — Now copy the actual source code.
# This layer changes on every code edit, but that's fine because
# the expensive npm install layer above is still cached.
COPY src/ ./src/

# Layer 6 — Declare the port the app listens on (documentation only —
# EXPOSE does NOT actually publish the port to the host).
EXPOSE 3000

# Layer 7 — The default command to start the application.
# Using the JSON array (exec) form avoids spawning a shell,
# which means SIGTERM signals reach your Node process directly.
CMD ["node", "src/index.js"]

The Instructions That Actually Matter — And What They're Really Doing

There are 18 Dockerfile instructions. In practice, you'll use about 10 of them regularly. Rather than listing all 18 mechanically, let's focus on the ones that cause confusion or have non-obvious behaviour — because those are the ones that bite you in production.

FROM is always first. It picks your starting layer. FROM scratch gives you an empty image — useful for compiled Go or Rust binaries. FROM node:20-alpine gives you Node on Alpine Linux, which is ~7MB versus ~180MB for Debian-based images. Prefer Alpine for production; prefer the fuller images when you need debugging tools.

RUN executes a shell command during the build. Each RUN creates a new layer. Chain related commands with && and clean up in the same RUN to avoid bloating the image with intermediate files that persist in a layer even after you delete them later.

COPY vs ADD: Use COPY almost always. ADD does extra magic — it auto-extracts tar archives and can fetch URLs — but that magic makes builds unpredictable. Use ADD only when you explicitly need its archive extraction feature.

ENV sets environment variables available at both build time and runtime. ARG sets variables available only at build time. Never put secrets in ENV — they're visible in docker inspect and image history. Use runtime secret injection instead.

ENTRYPOINT vs CMD: ENTRYPOINT sets the executable that always runs. CMD provides default arguments to it. When you run docker run my-image --verbose, that --verbose replaces CMD but gets appended to ENTRYPOINT. Together they let you build images that behave like CLI tools.

The HEALTHCHECK instruction: HEALTHCHECK tells Docker how to determine if the container's process is healthy. Without it, Docker only checks if the process is running — not if it is functional. A process that is running but deadlocked appears healthy. HEALTHCHECK runs a command periodically and marks the container as unhealthy if it fails. This is critical for orchestrators like Docker Swarm and Kubernetes that use health status for routing decisions.

# Build-time variable — available only during docker build, not at runtime.
# Pass it with: docker build --build-arg APP_VERSION=2.1.0 .
ARG APP_VERSION=1.0.0

FROM python:3.12-slim

WORKDIR /api

# Runtime environment variable — visible to the running container.
# Safe for non-sensitive config like port numbers or log levels.
ENV LOG_LEVEL=info \
    PORT=8080

# Chain RUN commands with && to keep this as ONE layer.
# The final rm -rf cleans up apt cache IN THE SAME LAYER so it doesn't
# persist and bloat the image. If you ran rm -rf in a separate RUN,
# the cache would still exist in the previous layer — wasted space.
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

# Copy dependency file alone first (cache optimization from section above)
COPY requirements.txt .

# Install Python deps. --no-cache-dir prevents pip from storing
# the download cache inside the image layer — saves ~50MB.
RUN pip install --no-cache-dir -r requirements.txt

# Copy application source code
COPY app/ ./app/

# HEALTHCHECK — tells Docker if the app is actually functional.
# Without this, Docker only checks if the process isinterval=30s --timeout=5s --start-period=10 healthy without a healthcheck.
HEALTH running.
# A deadlocked process appearsCHECK --s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

# ENTRYPOINT sets the fixed executable — this always runs.
# Using exec form (JSON array) so the process receives OS signals directly.
ENTRYPOINT ["python", "-m", "uvicorn"]

# CMD provides the default arguments to ENTRYPOINT.
# You can override these at runtime without changing ENTRYPOINT:
# docker run my-api app.main:app --port 9000
CMD ["app.main:app", "--host", "0.0.0.0", "--port", "8080"]

Multi-Stage Builds — The Pattern That Separates Pros from Beginners

Here's a scenario every developer hits: you need a compiler or build tool to produce your application binary, but you don't need that compiler in the final image running in production. Shipping the compiler anyway means a larger attack surface, a bigger image pulling over the network, and slower startup times in Kubernetes.

Multi-stage builds solve this elegantly. You define multiple FROM blocks in one Dockerfile. Each FROM starts a fresh image context. You build your application in an early 'builder' stage that has all the tools, then you COPY only the compiled output into a final, minimal 'runtime' stage. The builder stage is discarded — it never ships.

This pattern is transformative for compiled languages. A Go application that builds in a 800MB image with all the Go toolchain can ship as a 12MB Alpine or even a 3MB scratch image containing just the binary. But it's equally powerful for JavaScript — build your React app with node_modules in one stage, then copy only the /dist folder into an nginx image.

The key instruction is COPY --from=builder. The name builder is just a label you assign with AS in the FROM line. You can have as many stages as you need, and any stage can copy from any previous stage. You can even reference external images as copy sources with --from=nginx:alpine.

Build-time secrets in multi-stage builds: Multi-stage builds are the correct pattern for handling build-time secrets. Put the secret in the builder stage (using BuildKit --mount=type=secret), use it during compilation, and the secret never appears in the final runtime stage. The builder stage is discarded, and with it any trace of the secret.

Targeting a specific stage: Use docker build --target <stage-name> to build up to a specific stage. This is useful for debugging — build the builder stage and inspect it without building the runtime stage: docker build --target builder -t debug . && docker run --rm -it debug sh.

# ─── Stage 1: Builder ──────────────────────────────────────────────────────
# This stage has the full Go toolchain (~800MB). It compiles our app.
# The 'AS builder' label lets us reference this stage later.
FROM golang:1.22-alpine AS builder

# Install git — needed if any Go modules pull from private repos
RUN apk add --no-cache git

WORKDIR /build

# Copy go module files first for cache optimization
COPY go.mod go.sum ./

# Download dependencies — this layer is cached until go.mod changes
RUN go mod download

# Copy all source code
COPY . .

# Build the binary.
# CGO_ENABLED=0 — statically link everything, no C runtime needed.
# GOOS=linux — compile for Linux even if building on a Mac.
# -ldflags "-w -s" — strip debug info and symbol table (~30% size reduction).
RUN CGO_ENABLED=0 GOOS=linux go build \
    -ldflags="-w -s" \
    -o /build/api-server \
    ./cmd/server

# ─── Stage 2: Runtime ──────────────────────────────────────────────────────
# 'scratch' is a completely empty image — no OS, no shell, nothing.
# The only thing in this final image is our compiled binary.
# This is as lean and secure as it gets.
FROM scratch AS runtime

# Copy TLS certificates from the builder stage so our app can make
# HTTPS calls. Without this, any TLS connection would fail.
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

# Copy ONLY the compiled binary from the builder stage.
# Everything else from the 800MB build environment is discarded.
COPY --from=builder /build/api-server /api-server

EXPOSE 8080

# No shell in scratch, so we must use exec form
ENTRYPOINT ["/api-server"]

Production-Ready Dockerfile — Putting It All Together

Knowing individual instructions is one thing. Knowing how they compose into a secure, efficient, production-grade Dockerfile is what makes the difference in a real project. There are four production concerns beyond 'does it build': image size, security, build speed, and signal handling.

Image size: use a minimal base, chain RUN commands, use multi-stage builds, and add a .dockerignore file — this is the most commonly forgotten file. Without it, COPY . . sends your entire project directory (including node_modules, .git, test fixtures) to the Docker build context, which can make builds take minutes before a single instruction executes.

Security: never run as root. Add a non-root user with RUN addgroup and adduser, then switch to it with USER. If an attacker compromises your app, running as a non-root user limits the blast radius significantly.

Signal handling: always use exec form ["executable", "arg"] for CMD and ENTRYPOINT — not shell form executable arg. Shell form wraps your command in /bin/sh -c, which means your process gets PID 2, not PID 1. Kubernetes and Docker send SIGTERM to PID 1 when stopping a container. If your app isn't PID 1, it never receives the signal and gets hard-killed after the timeout.

Build speed: everything from section one — order layers by change frequency, separate dependency manifests from source code.

The .dockerignore file in detail: The .dockerignore file excludes files from the build context before they are sent to the Docker daemon. Without it, the entire directory (including .git, node_modules, .env, test fixtures) is sent to the daemon, increasing build time and risking secret exposure. Common patterns to exclude: node_modules/, .git/, .env, .log, coverage/, __pycache__/, *.pyc, .dockerignore itself.

# ─── .dockerignore (create this file alongside your Dockerfile) ────────────
# node_modules/
# .git/
# .github/
# coverage/
# *.test.js
# .env*
# README.md
# docker-compose*.yml
# ─────────────────────────────────────────────────────────────────────────────

# ─── Stage 1: Dependency installation ────────────────────────────────────────
FROM node:20-alpine AS deps

# Create a non-root user early — we'll reuse this uid in the runtime stage.
# Using a numeric UID (1001) instead of a name is more portable across images.
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 --ingroup appgroup appuser

WORKDIR /app

# Copy only manifests — cache this expensive layer aggressively
COPY package.json package-lock.json ./

# ci is stricter than install — it fails if lockfile is out of sync,
# which catches dependency drift bugs in CI before they hit production.
RUN npm ci --omit=dev

# ─── Stage 2: Build (for TypeScript/React projects that need transpilation) ──
FROM node:20-alpine AS build

WORKDIR /app

# Copy deps from previous stage (avoids re-installing)
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Run the build step (TypeScript compile, bundling, etc.)
RUN npm run build

# ─── Stage 3: Production runtime ─────────────────────────────────────────────
FROM node:20-alpine AS production

WORKDIR /app

# Copy the non-root user definitions from the deps stage
COPY --from=deps /etc/passwd /etc/passwd
COPY --from=deps /etc/group /etc/group

# Copy only what production needs — nothing from build tools or dev deps
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package.json .

# Switch to non-root user BEFORE the final CMD.
# Everything after this line runs as appuser, not root.
USER appuser

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

EXPOSE 3000

# Exec form — process receives signals directly as PID 1.
# No shell wrapper means clean shutdown when Kubernetes sends SIGTERM.
CMD ["node", "dist/index.js"]

Why Your Dockerfile Needs a .dockerignore — And Most Don't Bother

You've seen it. The build that crawls for 90 seconds, copying node_modules or .git into the image for no reason. That's what happens when you skip a .dockerignore. The build context — everything in your project directory — gets shipped to the Docker daemon. Including your secrets, your 400MB vendor folder, and the cat picture you forgot about.

A .dockerignore works exactly like .gitignore. It tells the build to prune dead weight before the COPY instruction even runs. Smaller context means faster builds. Fewer cache invalidations. And you're not baking your .env file into the final image by accident.

Production teams treat .dockerignore as mandatory. Not optional. Not "nice to have". You don't get to ship a lean image without it.

// io.thecodeforge — devops tutorial

// .dockerignore — ditch the junk before the build starts
node_modules
.git
.env
*.log
build/
dist/
.DS_Store

// Your Dockerfile
FROM node:20-alpine
WORKDIR /app

// Without .dockerignore, this COPY grabs everything
// With .dockerignore, it's just src + package.json
COPY . .
// Simulated log showing build context size
// Wait for output below

How the Build Cache Really Works — Stop Breaking It

Docker doesn't rebuild everything from scratch. It caches layers. When you change a line in your Dockerfile, Docker checks if the previous instruction's layer already exists. If it does, it reuses it. If not, it invalidates the cache — and every layer after it.

The problem? Developers put frequently changing files early in the Dockerfile. COPY the entire source tree before running npm install. Now every code change invalidates the node_modules layer. You pay for a full npm install on every build.

The fix is brutal and effective: order your instructions from least to most volatile. Start with package managers and lockfiles. Install dependencies. Then copy the source code. Docker's cache is dumb — it follows the order you give it. Give it a good order.

This pattern saves minutes per build in CI. If your builds take longer than 60 seconds, your layer ordering is wrong.

// io.thecodeforge — devops tutorial

// WRONG ORDER — every code change busts the whole cache
FROM python:3.12-slim
WORKDIR /app
COPY . .                          // Source changes ALL the time
RUN pip install -r requirements.txt // Rebuilds dependencies EVERY time

// RIGHT ORDER — stable layers first
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .            // Changes rarely
RUN pip install --no-cache-dir -r requirements.txt  // Stable cache hit
COPY src ./src                     // Source changes often — only busts this layer

// Build output showing cache status
// RUN pip install...  --->  Using cache (fast)
// COPY src ./src      --->  Cache busted (slow, but only one layer)

Metadata in Dockerfiles — Labels, EXPOSE, and the Lies You Tell

A Dockerfile isn't just for building. It's for documentation. The instructions that don't affect the filesystem — LABEL, EXPOSE, and ARG — tell anyone who reads the image what it's supposed to do.

LABEL adds metadata as key-value pairs. Use it for maintainer contact, version, and git commit. EXPOSE doesn't actually publish a port. It annotates that the container listens on that port at runtime. It's a contract between the image author and the person running it. If you skip it, you're hiding what the app needs.

ARG defines build-time variables. Use it to pass version numbers or environment-specific configs without hardcoding. But be careful — ARG values persist in the image history. Don't put secrets in ARG unless you want them leaked.

Production workflows read these labels. Registries sort by them. Monitoring tools surface them. If your Dockerfile has zero labels, you're shipping a blank ID card.

// io.thecodeforge — devops tutorial

FROM golang:1.22-alpine AS builder

// Build-time args — NOT for secrets
ARG APP_VERSION
ARG GIT_SHA

LABEL org.opencontainers.image.version=${APP_VERSION}
LABEL org.opencontainers.image.revision=${GIT_SHA}
LABEL org.opencontainers.image.source="https://github.com/yourorg/payments-api"

EXPOSE 8080

// Inspection output for the built image
// docker inspect payments-api:latest shows all labels

Why Every Dockerfile Needs a Clear Explanation of Base Image Choices

Most Dockerfiles start with FROM ubuntu:latest or FROM node:18-alpine without explaining why. That's a trap. The base image you pick directly dictates image size, attack surface, and compatibility. A bloated base like ubuntu:22.04 is 77 MB and includes unnecessary tools — perfect for testing, terrible for production. Alpine images drop to 5 MB but use musl libc, breaking binaries compiled against glibc. Distroless images strip everything but the runtime, reducing CVEs to near zero but making debugging impossible without sidecars. The rule: state your base image rationale in a comment above FROM. 'We use node:18-slim because Alpine's musl breaks our native bcrypt module.' That single line saves the next engineer hours of guessing. Never inherit a base image you can't explain in one sentence.

// io.thecodeforge — devops tutorial

# Rationale: node:18-slim avoids musl issues with bcrypt native bindings
# Alpine would cause runtime segfaults on this specific version
FROM node:18-slim AS builder

# Second stage uses distroless to minimize CVEs
# Only the compiled binary and dependencies are copied
FROM gcr.io/distroless/nodejs18-debian11
COPY --from=builder /app/dist /app
CMD ["/app/server.js"]

Additional Resources That Fix Real Dockerfile Pain Points

Official documentation won't teach you what hurts most: debugging broken cache hits, wrestling with BuildKit secrets, or slimming images without breaking the app. These resources close that gap. For cache debugging, read Docker's 'Optimizing Builds with Cache' docs — but skip the theory and jump to the 'Cache invalidation patterns' section. For multi-stage builds, check out 'Docker Multi-Stage Builds: The Practical Guide' on dev.to by a former Docker engineer — it covers live examples of cross-stage variable passing. For security, use Hadolint (hadolint.github.io) to lint your Dockerfile against 100+ rules, then read Aqua Security's 'Dockerfile Best Practices' for real CVE reduction metrics. These aren't blog fluff — they're the exact resources senior engineers open when their pipeline fails.

// io.thecodeforge — devops tutorial

# Lint your Dockerfile before every commit
# hadolint Dockerfile --ignore DL3008 --trusted-registry docker.io

# Build with cache debugging
# DOCKER_BUILDKIT=1 docker build --progress=plain . 2>&1 | grep "CACHED"

# Security scan after build
# docker scout cves my-image:latest --only-severity high

# Add metadata for traceability
LABEL org.opencontainers.image.source="https://github.com/myorg/repo"