Dockerfile Fundamentals: FROM, RUN, COPY, ADD, WORKDIR, ENV, ARG, USER, CMD, and ENTRYPOINT: Configuration, Design Choices, and Tradeoffs

1. Design goal: make the Dockerfile explain intent

A production Dockerfile is reviewed as both source code and a build policy. The best choice is not always the instruction that produces the fewest lines; it is the choice whose lifecycle, security, cache, and runtime consequences are explicit enough to audit and reproduce.

2. COPY versus ADD

Use ADD because you need an ADD capability, not because it is “more powerful.” For remote sources, prefer immutable revisions/checksums where supported and preserve evidence of what was actually fetched.

3. ARG versus ENV

Use ARG for non-secret build parameters: base selection, feature switches, build metadata, or other values consumed while building. Use ENV for a default that should become image/runtime configuration. An ENV can be overridden at container creation; an ARG cannot be expected to appear at runtime unless you intentionally copy its value into ENV or a file.

4. Shell form versus exec form

Shell form is convenient when a shell is the point—for example pipelines, variable expansion, conditional logic, or package-manager command composition in a RUN. Exec form is usually better for ENTRYPOINT/CMD because arguments are explicit and the intended application can be PID 1 directly.

# Shell features are intentional during build
RUN set -eux; mkdir -p /app; printf '%s\n' "$APP_VERSION" > /app/version

# Runtime process boundaries are explicit
ENTRYPOINT ["/app/server"]
CMD ["--foreground"]

Exec form does not perform shell expansion by itself. If you need expansion, invoke a shell explicitly and understand that the shell becomes part of the process model unless it execs the final application.

5. ENTRYPOINT plus CMD versus CMD alone

Use CMD alone when the entire default command is meant to be easy to replace. Use ENTRYPOINT plus CMD when the image represents a stable executable and CMD supplies default arguments. That design makes docker run IMAGE --help or docker run IMAGE alternate-arg intuitive while preserving the executable.

A rigid ENTRYPOINT can be frustrating if users frequently need a diagnostic shell. A totally replaceable CMD can be too loose for purpose-built images. The decision should follow the image's contract, not a universal rule.

6. Root versus non-root runtime user

Many build operations need elevated privileges inside the build environment, but that does not imply the final application process should run as root. Perform package installation and filesystem ownership setup before the final USER instruction, then switch to the least-privileged UID/GID that can read/execute required files and write only intended paths.

Numeric UIDs are portable across images that may not contain a name-service entry, but named users make intent readable when the image defines them. Either way, verify effective UID in a running container and test required write paths rather than assuming the Dockerfile is correct.

7. Absolute WORKDIR versus inherited/relative paths

An explicit absolute WORKDIR /app makes later COPY/RUN/CMD behavior easier to review and protects the build from base-image working-directory changes. Docker's current build checks include a warning for relative WORKDIR patterns that can become surprising when a base image changes.

8. One well-scoped RUN versus opaque command chains

Package managers often require update/install/cleanup actions to be coherent in one build step so cached metadata is not separated from the install it governs. But “combine everything into one RUN” is not a general readability rule. Group operations that share lifecycle/cache semantics, use shell safeguards such as set -eu where appropriate, and keep unrelated concerns separate enough to diagnose.

Instruction order matters: copy stable dependency manifests before frequently changing source when that allows expensive dependency work to stay cached. Chapter 11 will go deeper into cache mounts and cache import/export.

9. Tag convenience versus digest pinning

A versioned tag is useful for human maintenance because it communicates the upstream release line. A digest provides immutable content identity. A common pattern is to record both: busybox:1.37.0 as the upstream name and the resolved @sha256:... as the executable build input. Pinning means you must also own an update process; immutability without maintenance can leave known vulnerabilities frozen indefinitely.

10. Worked decision table

11. Scenario: choose for reproducibility, not just convenience

A team wants a base tag that auto-updates, an API token in ARG, source copied before dependency installation, and a shell-form CMD. The faster short-term design creates four separate risks: mutable source identity, secret exposure, unnecessary cache invalidation, and ambiguous PID 1/signal behavior. A better design records a base digest plus readable tag, moves the token to a secret mount, orders stable dependency inputs before volatile source when valid, and uses exec-form runtime configuration.

Knowledge check

Official references and version notes

• Dockerfile reference — current syntax and semantics for FROM, RUN, COPY, ADD, WORKDIR, ENV, ARG, USER, CMD, ENTRYPOINT, parser directives, and instruction options.
• Building best practices — guidance on reusable images, cache-aware instruction order, package installation, pinning, and non-root design.
• Build variables — lifecycle and scope of ARG and ENV.
• Build secrets — secret and SSH mounts for sensitive build-time input.
• Build checks reference — Dockerfile checks including SecretsUsedInArgOrEnv, JSONArgsRecommended, and WorkdirRelativePath.
• Checking build configuration — running checks with docker build --check and interpreting results.
• Docker Engine 29 release notes — current Engine 29 behavior and packaging updates.
• BuildKit releases — current builder/frontend changes that can affect Dockerfile features.