Skip to content

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

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

Practice Writing a Dockerfile

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors