Dockerfile Instructions
| Instruction | Purpose |
|---|---|
FROM | Base image to start from |
WORKDIR | Set the working folder inside the image |
COPY | Copy files from your project into the image |
RUN | Run a command at build time (install packages) |
ENV | Set environment variables that stay in the image |
ARG | Build-time variable only |
EXPOSE | Documents the port the app listens on |
USER | Switch to a non-root user |
CMD | Default command when the container starts |
ENTRYPOINT | Fixed executable; CMD becomes its default arguments |
HEALTHCHECK | Command Docker runs to check the app is healthy |
A First Dockerfile (Python)
Layer Caching: Order Matters
Docker reuses a cached layer if the instruction and everything before it are unchanged. Put things that change rarely first (dependencies) and things that change often last (source code).
.dockerignore
Exclude files that should never go into the build context: faster builds, smaller images and no leaked secrets.
CMD vs ENTRYPOINT
["cmd", "arg"]. With the shell form CMD cmd arg, Docker wraps your app in /bin/sh -c, and docker stop may not reach it, causing slow 10-second shutdowns.
Multi-Stage Builds
Compilers and build tools are needed to build, but not to run. A multi-stage Dockerfile uses one stage to build and a second, tiny stage to run. Only the final stage is shipped.
Node.js example
Java example
Go example (tiny final image)
A Go app can shrink from over 800 MB (build image) to about 10 to 20 MB (distroless final image).
Security Best Practices
- Run as a non-root user (
USER) - Use small trusted bases:
-slim,alpine, distroless, or hardened images - Pin versions and, for strict reproducibility, digests:
FROM python:3.13-slim@sha256:... - Never put secrets in
ENV,ARGorCOPY. They remain in image layers - Scan images (Trivy, Docker Scout) in CI
- Keep images updated and rebuild regularly for security patches
- Use read-only root filesystem and drop capabilities at runtime when possible
Passing Secrets at Build Time Safely
BuildKit Cache Mounts
BuildKit is the default builder in current Docker. It builds stages in parallel and supports secrets, cache mounts and multi-platform builds.
Healthcheck
In Kubernetes you use liveness and readiness probes instead, but a Docker healthcheck is useful with Compose and plain Docker.
Checking Image Size
| Technique | Effect |
|---|---|
| Multi-stage build | Removes compilers and build tools |
| Slim or distroless base | Removes shell, package manager and many CVEs |
Combine RUN commands and clean caches | apt-get update && apt-get install -y x && rm -rf /var/lib/apt/lists/* |
.dockerignore | Smaller context and faster builds |
npm ci --omit=dev or pip --no-cache-dir | Skips dev dependencies and caches |
Practice Tasks
- Containerize a small Flask or Express app and measure build time before and after reordering
COPY - Convert it to a multi-stage build and compare image sizes
- Make it run as non-root and prove it with
docker exec ... id - Add a
.dockerignoreand a healthcheck - Build a multi-platform image with
buildx
Conclusion
A good Dockerfile is ordered for cache hits, built in stages, runs as a non-root user and ships only what is needed to run. Small images start faster, cost less and have fewer vulnerabilities.

