A Dockerfile is your image recipe — a plain text file that turns into a reproducible, layered container image. This lesson teaches you to write one from scratch, understand every instruction, and avoid the most common mistakes.

1. What Is a Dockerfile?

A Dockerfile is a text file containing an ordered sequence of instructions. Each instruction creates one layer in the final image. Think of it as a repeatable, version-controllable recipe that tells Docker exactly how to build an image.

• Plain text — no special editor needed, lives in your repo alongside your code.
• Ordered — instructions execute top to bottom; order matters for caching.
• One instruction = one layer — understanding this is key to optimizing builds.
• Deterministic — given the same Dockerfile and context, you get the same image (modulo upstream changes).

2. The Anatomy — A Complete Dockerfile

Here's a production-ready Dockerfile for a Node.js app, line by line:

1  FROM node:20-slim
2  WORKDIR /app
3  COPY package*.json ./
4  RUN npm ci --production
5  COPY . .
6  EXPOSE 3000
7  CMD ["node", "server.js"]

How a Dockerfile Becomes an Image

3. Key Instructions Reference

4. CMD vs ENTRYPOINT

This is the most commonly confused pair in Dockerfile authoring. Here's the mental model:

• ENTRYPOINT = the executable (what always runs)
• CMD = the default arguments (what can be overridden)

# Example: a container that acts like the "curl" command
ENTRYPOINT ["curl"]
CMD ["--help"]

# docker run mycurl             → runs: curl --help
# docker run mycurl example.com → runs: curl example.com
#                                   (CMD is replaced, ENTRYPOINT stays)

Exec Form vs Shell Form

5. Build Context

When you run docker build ., the entire directory (the "build context") is packaged as a tarball and sent to the Docker daemon. This happens BEFORE any instruction executes.

$ docker build .
Sending build context to Docker daemon  245.8MB  ← Ouch!

If your project has node_modules/, .git/, test data, or large assets, they all get sent — even if no COPY instruction references them.

The .dockerignore File

Create a .dockerignore at the project root (same syntax as .gitignore):

node_modules
.git
*.log
dist
coverage
.env
.DS_Store

Benefits:

• Faster builds — less data sent to the daemon
• Smaller images — COPY . . won't include ignored files
• Security — keeps .env files and secrets out of images

6. Building the Image

$ docker build -t myapp:1.0 .

What Happens During Build

1. Docker packages the build context (respecting .dockerignore) and sends it to the daemon.
2. Each instruction is executed in order, creating a new intermediate layer.
3. If a layer hasn't changed since the last build, Docker uses the cache (instant).
4. The final layer stack is saved as an image with the tag you specified.

$ docker build -t myapp:1.0 .
[+] Building 12.4s (10/10) FINISHED
 => [1/5] FROM node:20-slim@sha256:abc...          0.0s (cached)
 => [2/5] WORKDIR /app                             0.0s (cached)
 => [3/5] COPY package*.json ./                    0.1s
 => [4/5] RUN npm ci --production                 10.2s
 => [5/5] COPY . .                                 0.3s
 => exporting to image                             1.8s
 => => naming to docker.io/library/myapp:1.0       0.0s

7. Common Mistakes

❌ Mistake 1: Separate apt-get update and install

# BAD — update layer gets cached, install uses stale index
RUN apt-get update
RUN apt-get install -y curl

# GOOD — single layer, always fresh
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

❌ Mistake 2: Copying everything before installing dependencies

# BAD — any source code change busts the npm install cache
COPY . .
RUN npm ci

# GOOD — deps are cached until package.json changes
COPY package*.json ./
RUN npm ci
COPY . .

❌ Mistake 3: Running as root

# BAD — container runs as root (security risk)
CMD ["node", "server.js"]

# GOOD — create and switch to non-root user
RUN groupadd -r appuser && useradd -r -g appuser appuser
USER appuser
CMD ["node", "server.js"]

Interactive Quizzes

ENTRYPOINT ["python"]
CMD ["app.py"]

FROM ubuntu:22.04
ENV APP_PORT=3000
RUN apt-get update && apt-get install -y curl
COPY . /app
EXPOSE 8080
CMD ["./start.sh"]

Hands-On Tasks

# 1. Create project directory
mkdir flask-app && cd flask-app

# 2. Create app.py
cat > app.py << 'EOF'
from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello from Docker!"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)
EOF

# 3. Create requirements.txt
echo "flask==3.0.0" > requirements.txt

# 4. Write the Dockerfile
cat > Dockerfile << 'EOF'
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 5000
USER nobody
CMD ["python", "app.py"]
EOF

# 5. Build it
docker build -t flask-app:1.0 .

# 6. Run it
docker run -d -p 5000:5000 flask-app:1.0

# 7. Test it
curl http://localhost:5000
# → Hello from Docker!

# In the flask-app directory, simulate a large project:
mkdir -p data && dd if=/dev/zero of=data/bigfile.bin bs=1M count=100

# Build WITHOUT .dockerignore — watch context size:
docker build -t flask-no-ignore:1.0 .
# "Sending build context to Docker daemon  104.9MB"

# Check image size:
docker images flask-no-ignore:1.0 --format '{{.Size}}'
# → ~230 MB (100 MB of junk included!)

# Now create .dockerignore:
cat > .dockerignore << 'EOF'
data/
__pycache__
*.pyc
.git
.env
EOF

# Rebuild:
docker build -t flask-with-ignore:1.0 .
# "Sending build context to Docker daemon  4.096kB"

# Compare sizes:
docker images --format '{{.Repository}}:{{.Tag}} → {{.Size}}' | grep flask
# flask-no-ignore:1.0  → ~230 MB
# flask-with-ignore:1.0 → ~130 MB