Dockerfile Basics
Write your first Dockerfile — FROM, RUN, COPY, CMD, EXPOSE, and ENV
Skills taught: docker.dockerfile, docker.from, docker.run, docker.copy, docker.cmd, docker.env, docker.workdir
What is a Dockerfile?
A Dockerfile is a text file of instructions that tells Docker how to build your image. Think of it as a recipe: starting from a base OS, install dependencies, copy your code, configure it, and define how to run it. Every line is an instruction — and each becomes a cached layer.
A complete, production-ready Dockerfile
# ── Stage: use Node 20 on Alpine Linux (smallest production-suitable image) ──
FROM node:20-alpine
# WORKDIR: set the working directory inside the container
# All subsequent commands run from /app
WORKDIR /app
# COPY: copy files from host to container
# Copy package files FIRST (layer cache optimization)
COPY package*.json ./
# RUN: execute a shell command during build
# --production skips devDependencies
RUN npm install --production
# Now copy the rest of the source
COPY . .
# ENV: set environment variables available at runtime
ENV NODE_ENV=production
ENV PORT=3000
# EXPOSE: document which port the app listens on (informational — doesn't publish)
EXPOSE 3000
# CMD: the default command to run when the container starts
# Use exec form (JSON array) — not shell form — so signals work correctly
CMD ["node", "server.js"]
Every instruction explained
# FROM — base image (required, always first)
FROM python:3.12-slim
# WORKDIR — create dir and cd into it
WORKDIR /app
# RUN — run a command during BUILD (installs packages, compiles, etc.)
RUN pip install --no-cache-dir -r requirements.txt
# COPY <src> <dest> — copy from host filesystem into image
COPY requirements.txt ./
COPY src/ ./src/
# ADD — like COPY but also extracts .tar files and supports URLs
# Prefer COPY (more explicit); use ADD only when you need its extras
ADD app.tar.gz /app/
# ENV — environment variable (available at build AND runtime)
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
# ARG — build-time variable only (NOT available at runtime)
ARG BUILD_VERSION=unknown
LABEL version=$BUILD_VERSION
# EXPOSE — document port (does NOT publish — use -p in docker run)
EXPOSE 8000
# USER — switch to non-root user (security best practice)
RUN adduser --disabled-password appuser
USER appuser
# CMD — default command to run (can be overridden in docker run)
CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]
# ENTRYPOINT — like CMD but harder to override (use for main binaries)
ENTRYPOINT ["gunicorn", "app:app"]
# If both ENTRYPOINT and CMD set: CMD becomes arguments to ENTRYPOINT
Building and tagging
# Build from Dockerfile in current directory
docker build -t myapp:1.0 .
# -t = tag in the format name:version
# . = build context (current directory)
# Build from a specific Dockerfile
docker build -f Dockerfile.prod -t myapp:prod .
# Build with a build argument
docker build --build-arg BUILD_VERSION=2.1.0 -t myapp:2.1 .
# Common tags:
docker build -t myapp:latest . # latest (default)
docker build -t myapp:1.2.3 . # semantic version
docker build -t myapp:$(git rev-parse --short HEAD) . # git SHA
# Run your built image
docker run -p 3000:3000 myapp:1.0
Warning: CMD vs RUN — the most common beginner confusion: RUN executes during the image build (installs software, configures the OS). CMD executes when the container starts (runs your application). If you put your app start command in RUN, it runs during build and the result is baked in — which is wrong. CMD is what actually starts your app.
Frequently Asked Questions
What is the difference between CMD and ENTRYPOINT?
ENTRYPOINT sets the main command that always runs (hard to override). CMD provides defaults that can be replaced by arguments to docker run. When both are set, CMD becomes the default arguments to ENTRYPOINT. Example: ENTRYPOINT ["nginx"] and CMD ["-g", "daemon off;"] — run docker run myimage -t to override CMD while keeping nginx as the entrypoint.