Writing a Dockerfile
Create efficient Dockerfiles with FROM, RUN, COPY, and best practices for production.
What you'll learn
- The structure and instructions of a Dockerfile
- FROM, RUN, COPY, WORKDIR, and CMD
- Layer caching and build optimization
- Security best practices for Dockerfiles
Concept
Dockerfile Structure
A Dockerfile is a text file with instructions for building a Docker image. Each instruction is on its own line and creates a new layer. The file starts with a FROM instruction that specifies the base image. Then you add instructions to install dependencies, copy source code, and configure the application. The file ends with CMD or ENTRYPOINT, which defines what runs when the container starts.
Core Instructions
FROM node:20-alpine sets the base image. WORKDIR /app sets the working directory for subsequent instructions. COPY package.json . copies files from the build context into the image. RUN npm install executes a shell command during the build. CMD ["node", "server.js"] sets the default command when the container starts. EXPOSE 3000 documents which port the container listens on. ENV NODE_ENV=production sets environment variables in the image.
Layer Caching
Docker caches each layer. If an instruction's inputs haven't changed, Docker reuses the cached layer instead of re-running it. To maximize cache hits, put instructions that change rarely (like installing dependencies) before instructions that change often (like copying source code). A common pattern is to copy package.json and run npm install first, then copy the rest of the source code. This way, changing source code doesn't invalidate the dependency layer.
Security Best Practices
Never run containers as root — create a non-root user with RUN adduser and switch to it with USER. Use minimal base images like alpine or distroless to reduce the attack surface. Don't bake secrets into images — pass them at runtime with environment variables. Use .dockerignore to exclude sensitive files from the build context. Pin base image versions with digests for maximum reproducibility.
Build Context and .dockerignore
The build context is the directory sent to the Docker daemon during docker build. Everything in the context is available for COPY and ADD instructions. Use a .dockerignore file to exclude node_modules, .git, test files, and secrets from the context. A smaller context means faster builds and smaller images. Never include .env files or private keys in the build context — they could end up baked into the image layers, which are accessible to anyone who can pull the image.
Example
# A production-ready Node.js Dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
RUN addgroup -S app && adduser -S app -G app
USER app
EXPOSE 3000
CMD ["node", "dist/server.js"]
This multi-stage Dockerfile builds the app in the first stage, copies only the output to a minimal final image, and runs as a non-root user for security.
Try it
- Dockerfile Generator
Generate production-ready Dockerfiles.
- Docker Compose Generator
Create compose files to run your Dockerfile.
- Gitignore Generator
Generate .dockerignore and .gitignore files.
Common mistakes
The mistake
COPY . . before npm install
The fix
Copy package.json first and install dependencies, then copy source code. This leverages layer caching so dependency installation is skipped when only source code changes.
The mistake
Using large base images like ubuntu:latest
The fix
Use minimal base images like node:20-alpine or distroless. Smaller images have fewer vulnerabilities, faster builds, and quicker deployments.
Practice Writing a Dockerfile
3 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.