What Is a Dockerfile?
A Dockerfile is a plain-text script of instructions that docker build reads sequentially to assemble an image, one layer per instruction. Each instruction begins with an uppercase keyword such as FROM, RUN, or COPY, followed by arguments.
Cricket analogy: A Dockerfile is like a fixed pre-match warm-up checklist read top to bottom -- stretch, throw-downs, catching drills -- where each step is a labeled instruction the team runs through in strict sequence to build up match readiness.
The FROM Instruction
Every Dockerfile (except one built entirely FROM scratch) must start with a FROM instruction that specifies the base image to build on top of. Choosing a minimal, well-maintained base image (such as an 'alpine' or 'slim' variant) reduces final image size and attack surface.
Cricket analogy: Every training plan must start from a chosen base fitness level -- you can't build a fast bowler's program from scratch without first picking a foundation (club-level vs. international-level base), and picking a lean, well-conditioned starting point reduces injury risk.
Core Build-Time Instructions
RUN executes a command during the build and commits the result as a new layer, commonly used for installing packages. COPY copies files from the build context into the image; ADD does the same but also supports remote URLs and automatic tar extraction, so COPY is generally preferred for clarity. WORKDIR sets the working directory for subsequent instructions. ENV sets environment variables available both at build time and in the running container.
Cricket analogy: RUN is like executing a specific fielding drill during practice that permanently improves a player's reflexes (a new layer of skill); COPY is like transferring a specific training video into the player's kit for review, and WORKDIR is like setting which net they train in for the rest of the session; ENV is like fixed team rules (jersey number, batting position) that apply both in training and on matchday.
Runtime Instructions: CMD and ENTRYPOINT
CMD specifies the default command to run when a container starts, and can be overridden by arguments passed to docker run. ENTRYPOINT configures the container to run as an executable, and any CMD or docker run arguments are appended to it rather than replacing it. A common pattern is to use ENTRYPOINT for the fixed executable and CMD for default arguments.
Cricket analogy: CMD is like a default batting order that gets used unless the captain overrides it before the toss; ENTRYPOINT is like the fixed decision to always send in an opener first, with CMD just specifying which opener by default -- the fixed role stays, only the specific player is appended or swapped.
# Example Dockerfile for a Node.js web service
FROM node:20-alpine
WORKDIR /app
# Copy only manifest files first to leverage layer caching
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
# Now copy the rest of the application source
COPY . .
ENV NODE_ENV=production
EXPOSE 3000
# Run as a non-root user for better security
USER node
ENTRYPOINT ["node"]
CMD ["server.js"]Use the exec form (JSON array syntax, e.g. CMD ["node", "server.js"]) rather than the shell form (CMD node server.js) whenever possible. The exec form avoids wrapping the process in /bin/sh -c, which ensures signals like SIGTERM reach your application directly for clean shutdowns.
EXPOSE, USER, and Metadata Instructions
EXPOSE documents which network ports the container listens on; it is purely informational and does not actually publish the port (that requires docker run -p). USER switches the effective user for subsequent RUN, CMD, and ENTRYPOINT instructions — running as a non-root user is a security best practice. LABEL attaches arbitrary key-value metadata to the image, such as maintainer or version information.
Cricket analogy: EXPOSE is like a scoreboard listing which gates the stadium has, purely informational until the turnstiles (docker run -p) are actually opened for fans to enter; USER is like requiring the groundskeeper rather than the captain to handle maintenance tasks, a safety best practice; LABEL is like the plaque noting the stadium's architect and year built.
Avoid running containers as root unless absolutely necessary. If your base image doesn't already define a non-root user, create one explicitly and switch to it with USER before your application starts.
Building the Image
The docker build command reads a Dockerfile (by default named 'Dockerfile' in the current directory) and a build context (the set of files sent to the daemon, typically the current directory).
Cricket analogy: docker build reading the Dockerfile and build context is like an umpire reviewing a fixed match-day checklist plus the full kit bag of everything needed (pitch report, team sheets) before certifying the ground ready for play.
# Build an image and tag it
docker build -t myapp:1.0 .
# Build using a Dockerfile with a different name/location
docker build -f docker/Dockerfile.prod -t myapp:prod .
# Build with a build argument
docker build --build-arg NODE_ENV=production -t myapp:1.0 .- FROM must be the first real instruction and sets the base image.
- RUN executes at build time and creates a new layer; CMD/ENTRYPOINT define what runs at container start.
- CMD arguments are overridden by
docker runarguments; ENTRYPOINT arguments are appended to, not replaced. - Prefer the exec (JSON array) form of CMD/ENTRYPOINT for proper signal handling.
- EXPOSE is documentation only — it does not publish ports; use
-pat run time for that. - Use USER to avoid running application processes as root.
Practice what you learned
1. What is the effect of running `docker run myapp echo hello` if the Dockerfile has `CMD ["node", "server.js"]` and no ENTRYPOINT?
2. Which instruction actually publishes a container's port to the host machine?
3. Why is the exec form `CMD ["nginx", "-g", "daemon off;"]` generally preferred over the shell form `CMD nginx -g "daemon off;"`?
4. What is the primary difference between COPY and ADD in a Dockerfile?
5. In the ENTRYPOINT + CMD pattern `ENTRYPOINT ["node"]` / `CMD ["server.js"]`, what happens if you run `docker run myapp test.js`?
Was this page helpful?
You May Also Like
Docker Images Explained
An introduction to what Docker images are, how they differ from containers, and how their layered, read-only filesystem structure works.
Image Layers and Build Caching
How Docker's layered filesystem and build cache work, and how to order Dockerfile instructions to maximize cache hits and minimize image size.
Multi-Stage Builds
How to use multiple FROM stages in a single Dockerfile to separate build-time tooling from the final runtime image, producing smaller, more secure images.
Environment Variables and Configuration
Learn how to configure containerized applications using environment variables, .env files, and Dockerfile defaults without rebuilding images.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAnsible Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsCI/CD Tools & Pipelines Study Notes
YAML · 37 topics