What is a Dockerfile and how do you write one?

Question

Accepted Answer

A **Dockerfile** is a text file with instructions for **building a Docker image** — it describes the base image, dependencies, files to copy, and how to run the application. It makes image builds reproducible and version-controllable.

## A basic Dockerfile

```dockerfile
# FROM — the base image to build on
FROM node:20-alpine

# WORKDIR — set the working directory inside the image
WORKDIR /app

# COPY dependency files first (for better layer caching)
COPY package*.json ./
# RUN — execute a command during the BUILD (install dependencies)
RUN npm install

# COPY the rest of the application code
COPY . .

# EXPOSE — document the port the app listens on
EXPOSE 3000

# CMD — the command to run when a CONTAINER starts
CMD ["node", "server.js"]
```

## Key instructions

```text
FROM     → the base image (starting point) — REQUIRED, usually first
WORKDIR  → set the working directory for subsequent instructions
COPY/ADD → copy files from the host into the image
RUN      → execute a command at BUILD time (install packages, compile) → creates a layer
ENV      → set environment variables
EXPOSE   → document which port(s) the container listens on
CMD      → the default command to run when the container STARTS (one per Dockerfile)
ENTRYPOINT → the executable that runs (CMD provides default args to it)
ARG      → build-time variables
```

## RUN vs CMD vs ENTRYPOINT (commonly confused)

```text
RUN        → runs at BUILD time (builds the image — e.g. install dependencies)
CMD        → runs at CONTAINER START (the default command; overridable at run)
ENTRYPOINT → the main executable at start (CMD becomes its default arguments)
→ RUN builds the image; CMD/ENTRYPOINT define what runs when it starts.
```

## Why it matters

Understanding the Dockerfile is essential because it's how Docker images are built, so writing one is a fundamental, everyday Docker skill.

A Dockerfile provides **reproducible, version-controllable image builds** — describing in code exactly how to construct an image (the base image, dependencies, files, configuration, and run command), so anyone can build the same image consistently, which is central to Docker's value of reproducibility.

Understanding the **key instructions** — `FROM` (the base image), `WORKDIR`, `COPY` (bringing files in), `RUN` (executing build-time commands like installing dependencies), `ENV`, `EXPOSE`, and `CMD`/`ENTRYPOINT` (defining what runs when the container starts) — is necessary to write effective Dockerfiles for real applications.

A particularly important and commonly-confused distinction is **`RUN` vs `CMD` vs `ENTRYPOINT`**: `RUN` executes at **build time** (constructing the image, e.g. installing packages), while `CMD`/`ENTRYPOINT` define what runs at **container start** (the application command) — understanding this prevents common mistakes.

Knowing practical patterns (like copying dependency files before code for better layer caching) reflects writing efficient Dockerfiles.

Since building images is fundamental to using Docker (every Docker workflow involves images, and the Dockerfile is how custom images are built), and since understanding the instructions and the build-time-vs-runtime distinction is necessary to create correct, efficient images, understanding the Dockerfile is essential, frequently-applied Docker knowledge — a core skill for anyone using Docker, the mechanism that turns Docker's reproducibility promise into practice and a near-universal requirement for containerizing applications.