Dockerfile

Getting Started

FROM - Base Image Selection

Understand base image selection and versioning for Dockerfile foundation

FROM Ubuntu LTS Base Image

Select specific Ubuntu version as base image. Using specific versions ensures reproducibility and security patches.

Code

1
FROM ubuntu:20.04
2
RUN apt-get update && apt-get install -y curl

Execution

$ docker build -t myapp:latest .
Step 1/2 : FROM ubuntu:20.04
 ---> 1d622ef08d5e
Step 2/2 : RUN apt-get update && apt-get install -y curl
 ---> Running in 5f8a9c2b3d4e
Collecting packages...
 ---> 7c9e4f2b3a5d
Successfully built 7c9e4f2b3a5d

Always use specific versions, never just 'ubuntu' or 'latest'
ubuntu:20.04 is LTS and receives security updates longer
First instruction must be FROM

FROM Alpine Lightweight Base

Alpine-based images are minimal and lightweight, ideal for production microservices where size matters.

Code

1
FROM alpine:3.18
2
RUN apk add --no-cache python3 py3-pip

Execution

$ docker build -t lightweight-app:latest .
Step 1/2 : FROM alpine:3.18
 ---> a24bb4aacf12
Step 2/2 : RUN apk add --no-cache python3 py3-pip
 ---> Running in 3f7e2c1a9b5d
 ---> 9c2d4e7f1a3b
Successfully built 9c2d4e7f1a3b

# Final image size: 89MB vs 77MB (Ubuntu) - but lighter for specific apps

Alpine uses musl libc instead of glibc
Package manager is 'apk' not 'apt'
Smallest base images available

FROM Official Python Image

Language-specific official images come with runtime pre-installed, simplifying Dockerfiles.

Code

1
FROM python:3.11-slim
2
WORKDIR /app
3
COPY requirements.txt .
4
RUN pip install -r requirements.txt

Execution

$ docker build -t python-app:latest .
Step 1/4 : FROM python:3.11-slim
 ---> b9ef8f396e26
Step 2/4 : WORKDIR /app
 ---> Running in 3a5f8d2c1e4b
 ---> 6e2a7f9d4c1b
Step 3/4 : COPY requirements.txt .
 ---> c9d4e2f7a1b5
Step 4/4 : RUN pip install -r requirements.txt
 ---> Running in 7f2e4c9a3d1b
Successfully built 8d3f5e2a7c4b

python:3.11 has full Python plus build tools (1.1GB)
python:3.11-slim has minimal dependencies (181MB)
python:3.11-alpine is smallest (51MB)

Image Naming and Tags

Understand Docker image naming conventions and tagging strategies

Tag Image with Domain Registry

Tag images with registry domain and semantic version for private registries and version management.

Code

1
FROM nginx:1.25
2
COPY index.html /usr/share/nginx/html/

Execution

$ docker build -t gcr.io/my-project/web-server:1.0.0 .
Successfully built 4d8e2f5a9c1b

$ docker push gcr.io/my-project/web-server:1.0.0
The push refers to repository [gcr.io/my-project/web-server]
8c3f7e2d4a1b: Pushed
1.0.0: digest: sha256:abc123...

Format: [registry]/repository:tag
gcr.io = Google Container Registry
registry.example.com for self-hosted registries

Multiple Tags for Single Image

Tag same image with multiple names for version management and release strategies.

Code

1
FROM node:18-alpine
2
COPY app.js .
3
CMD ["node", "app.js"]

Execution

$ docker build -t myapp:1.2.3 -t myapp:latest -t myapp:stable .
Successfully built 5f9d3a2c8e1b

$ docker images | grep myapp
myapp         1.2.3        5f9d3a2c8e1b
myapp         latest       5f9d3a2c8e1b
myapp         stable       5f9d3a2c8e1b

Use -t flag multiple times to create multiple tags
All tags reference same image layers (no duplication)
Common tags: latest, stable, v1.2.3, main, rc1

Multi-Stage Dockerfile Overview

Introduction to multi-stage builds for optimized image sizes

Single Stage vs Multi-Stage Comparison

Single stage includes build tools, resulting in large images with unnecessary dependencies.

Code

1
# Inefficient single stage
2
FROM golang:1.21
3
WORKDIR /src
4
COPY . .
5
RUN go build -o /usr/local/bin/app .
6
ENTRYPOINT ["app"]

Execution

$ docker build -t app:single .
Successfully built a2b8f4d7c3e1

$ docker images app:single
REPOSITORY   TAG       IMAGE ID       SIZE
app          single    a2b8f4d7c3e1   1.3GB

golang:1.21 is 1GB+ because it includes compiler and build tools
Binary is only a few megabytes
Extra bloat in production image

Optimized Multi-Stage Build

Multi-stage builds separate compilation from runtime, drastically reducing final image size.

Code

1
FROM golang:1.21 AS builder
2
WORKDIR /src
3
COPY . .
4
RUN go build -o /usr/local/bin/app .
5

6
FROM alpine:3.18
7
RUN apk add --no-cache ca-certificates
8
COPY --from=builder /usr/local/bin/app /usr/local/bin/app
9
ENTRYPOINT ["app"]

Execution

$ docker build -t app:multi .
Step 1/5 : FROM golang:1.21 AS builder
 ---> 2d8c4f1a9e3b
Step 3/5 : RUN go build -o /usr/local/bin/app .
 ---> Running in 4c5f8a2d7e1b
 ---> 7e3f4c6b1a9d
Step 5/8 : FROM alpine:3.18
 ---> a24bb4aacf12
Step 6/8 : COPY --from=builder /usr/local/bin/app /usr/local/bin/app
 ---> c8d2f5a1e7b4
Successfully built 8f2a4e9d3c1b

$ docker images
app          multi      8f2a4e9d3c1b   15MB

builder stage discarded after build
Only Alpine runtime included in final image
1.3GB -> 15MB reduction (1000x smaller)

Copying & Adding Files

COPY - Basic File Operations

Copy files and directories from build context to container

Copy Single File

Copy single file from build context (current directory) into container filesystem.

Code

1
FROM nginx:1.25-alpine
2
COPY index.html /usr/share/nginx/html/

Execution

$ docker build -t web:latest .
Step 1/2 : FROM nginx:1.25-alpine
 ---> a24bb4aacf12
Step 2/2 : COPY index.html /usr/share/nginx/html/
 ---> 5c2f8e1a3d7b
Successfully built 5c2f8e1a3d7b

Source path is relative to build context (docker build . directory)
Destination is absolute path in container
Creates destination directory if it doesn't exist

Copy Multiple Files with Wildcard

Use wildcards to copy multiple files matching pattern into container.

Code

1
FROM python:3.11-slim
2
WORKDIR /app
3
COPY *.py ./
4
COPY requirements.txt .

Execution

$ docker build -t python-app:latest .
Step 1/4 : FROM python:3.11-slim
 ---> b9ef8f396e26
Step 2/4 : WORKDIR /app
 ---> Running in a1b2c3d4e5f6
 ---> 7e2f4c8a1d3b
Step 3/4 : COPY *.py ./
 ---> 3c5f9a2e7d1b
Step 4/4 : COPY requirements.txt .
 ---> 8f4a2c6e9d1b
Successfully built 8f4a2c6e9d1b

Wildcards: * matches any characters, ? matches single character
COPY *.py ./ copies all Python files to current directory

Copy Directory Recursively

Copy entire directories with all subdirectories and files.

Code

1
FROM node:18-alpine
2
WORKDIR /app
3
COPY src ./src
4
COPY public ./public

Execution

$ docker build -t node-app:latest .
Successfully built 9d5e3f2a8c1b

Directories copied recursively by default
Preserves directory structure in container

COPY with Ownership

Copy files and set ownership to non-root user

Copy with User Ownership

Copy files and assign ownership to non-root user for better security.

Code

1
FROM node:18-alpine
2
RUN addgroup -S nodejs && adduser -S nodejs -G nodejs
3
WORKDIR /app
4
COPY --chown=nodejs:nodejs . .
5
USER nodejs
6
CMD ["node", "index.js"]

Execution

$ docker build -t secure-app:latest .
Successfully built 7c3e5f1a2d8b

$ docker run secure-app:latest
# App runs as nodejs user, not root

Format: COPY --chown=user:group source dest
Prevents running container as root
User/group must exist in image

Copy with Numeric User ID

Use numeric user:group IDs for CHOWN (more portable across systems).

Code

1
FROM python:3.11-slim
2
RUN groupadd -r appuser && useradd -r -g appuser appuser
3
WORKDIR /home/appuser/app
4
COPY --chown=1000:1000 . .
5
USER appuser
6
ENTRYPOINT ["python", "main.py"]

Execution

$ docker build -t app:latest .
Successfully built 4b2f7d9a1c5e

Numeric IDs are more reliable than names
1000:1000 common for non-root user

ADD - Advanced File Operations

Add files, directories, or remote URLs with automatic extraction

ADD from Remote URL

Download files from URLs and automatically extract tar archives.

Code

1
FROM ubuntu:20.04
2
ADD https://example.com/app.tar.gz /tmp/
3
WORKDIR /app
4
RUN tar -xzf /tmp/app.tar.gz && rm /tmp/app.tar.gz

Execution

$ docker build -t app:latest .
Step 1/4 : FROM ubuntu:20.04
 ---> 1d622ef08d5e
Step 2/4 : ADD https://example.com/app.tar.gz /tmp/
Downloading [==================================================>] 42MB/42MB
 ---> 8c5f2a1d4e9b
Step 3/4 : WORKDIR /app
 ---> 7e3f4c2a1d8b
Successfully built 7e3f4c2a1d8b

Automatically extracts .tar.* files
Downloads happen during build
Should be followed by cleanup (rm) to remove archive

ADD Automatically Extracts TAR

TAR archive automatically extracted to destination directory.

Code

1
FROM alpine:3.18
2
ADD https://releases.example.com/v1.2.3/app.tar.gz /opt/
3
WORKDIR /opt
4
RUN ls -la

Execution

$ docker build -t app:latest .
Successfully built 3f9e2d5a1c7b

Step 4/4 : RUN ls -la
 ---> Running in 5d8c3f2a1e9b
total 48
drwxr-xr-x    3 root     root          4096 Feb 28 12:00 .
drwxr-xr-x    1 root     root          4096 Feb 28 12:00 ..
-rw-r--r--    1 root     root      12345678 Feb 28 12:00 app
-rw-r--r--    1 root     root        54321 Feb 28 12:00 config.yaml

Only extracts recognized tar formats (.tar.gz, .tar.bz2, .tar)
Regular files copied as-is

Running Commands

RUN - Basic Command Execution

Execute commands during image build

RUN Single Command

Execute shell command during build. Each RUN creates a new layer.

Code

1
FROM ubuntu:20.04
2
RUN apt-get update
3
RUN apt-get install -y curl

Execution

$ docker build -t app:latest .
Step 1/3 : FROM ubuntu:20.04
 ---> 1d622ef08d5e
Step 2/3 : RUN apt-get update
 ---> Running in 5f8a9c2b3d4e
Reading package lists... Done
 ---> 7c9e4f2b3a5d
Step 3/3 : RUN apt-get install -y curl
 ---> Running in 3d7f2a1c8e5b
Setting up curl (7.68.0-1ubuntu4)...
 ---> 8b4f3e2c9a1d
Successfully built 8b4f3e2c9a1d

Each RUN instruction creates separate layer
Inefficient to use multiple RUN for related commands
Command executes in /bin/sh by default

RUN Chain Commands with AND

Chain multiple commands with && to create single layer and improve image efficiency.

Code

1
FROM ubuntu:20.04
2
RUN apt-get update && \
3
    apt-get install -y curl git vim && \
4
    apt-get clean

Execution

$ docker build -t app:latest .
Successfully built 9d5e3f2a8c1b

$ docker history app:latest
IMAGE              CREATED        SIZE
9d5e3f2a8c1b       30 seconds ago 187MB

&& ensures next command runs only if previous succeeded
Backslash continues line in Dockerfile
apt-get clean removes package cache

RUN Install Multiple Packages

Multi-line RUN with backslash for readability while maintaining single layer.

Code

1
FROM debian:12-slim
2
RUN apt-get update && apt-get install -y \
3
    build-essential \
4
    git \
5
    curl \
6
    wget \
7
    && apt-get clean \
8
    && rm -rf /var/lib/apt/lists/*

Execution

$ docker build -t build-tools:latest .
Step 1/2 : FROM debian:12-slim
 ---> 7b2f8e3a9c1d
Step 2/2 : RUN apt-get update && apt-get install -y ...
 ---> Running in 4f9d2c5a1e8b
Processing triggers...
 ---> 8c3f7e2d4a9b
Successfully built 8c3f7e2d4a9b

apt-get clean removes cache (reduces layer size)
rm -rf /var/lib/apt/lists/* also reduces layer

RUN - Exec Form vs Shell Form

Understand differences between exec form and shell form in RUN

Shell Form (Default)

Shell form processes variables and shell syntax (pipes, redirects, etc).

Code

1
FROM alpine:3.18
2
RUN echo "Building application"
3
RUN echo $PATH

Execution

$ docker build -t app:latest .
Step 1/3 : FROM alpine:3.18
 ---> a24bb4aacf12
Step 2/3 : RUN echo "Building application"
 ---> Running in 5f8a9c2b3d4e
Building application
 ---> 7c9e4f2b3a5d
Step 3/3 : RUN echo $PATH
 ---> Running in 3d7f2a1c8e5b
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 ---> 8b4f3e2c9a1d

RUN command will use /bin/sh -c
Environment variables expanded
Pipes and redirects work

Exec Form (JSON Array)

Exec form calls command directly without shell interpretation.

Code

1
FROM alpine:3.18
2
RUN ["apk", "add", "--no-cache", "curl"]
3
RUN ["echo", "Building"]

Execution

$ docker build -t app:latest .
Step 1/3 : FROM alpine:3.18
 ---> a24bb4aacf12
Step 2/2 : RUN ["apk", "add", "--no-cache", "curl"]
 ---> Running in 5f8a9c2b3d4e
Fetching https://dl-cdn.alpinelinux.org/alpine/v3.18/main/x86_64/PACKAGES.gz
(1/2) Installing ca-certificates
 ---> 7c9e4f2b3a5d
Step 3/3 : RUN ["echo", "Building"]
 ---> Running in 3d7f2a1c8e5b
Building
 ---> 8b4f3e2c9a1d

No shell expansion or variable interpolation
Command executed directly (better for signals)
Each array element becomes separate argument

Shell Parameter in RUN

Set default shell with SHELL instruction for all RUN, ENTRYPOINT, CMD instructions.

Code

1
FROM ubuntu:20.04
2
SHELL ["/bin/bash", "-c"]
3
RUN for i in 1 2 3; do echo "Number: $i"; done

Execution

$ docker build -t app:latest .
Successfully built 5c2f8e1a3d7b

Step 2/2 : RUN for i in 1 2 3; do echo "Number: $i"; done
 ---> Running in 4f9d2c5a1e8b
Number: 1
Number: 2
Number: 3
 ---> 8f4a2c6e9d1b

SHELL instruction affects subsequent instructions
Useful for bash-specific syntax (loops, pipes, etc)

Environment & Variables

ENV - Environment Variables

Set environment variables that persist in running containers

Set Single Environment Variable

ENV sets environment variables available during build and in running containers.

Code

1
FROM python:3.11-slim
2
ENV PYTHONUNBUFFERED=1
3
ENV APP_ENV=production
4
RUN echo "Environment: $APP_ENV"

Execution

$ docker build -t app:latest .
Step 1/4 : FROM python:3.11-slim
 ---> b9ef8f396e26
Step 2/4 : ENV PYTHONUNBUFFERED=1
 ---> Running in a1b2c3d4e5f6
 ---> 7e2f4c8a1d3b
Step 3/4 : ENV APP_ENV=production
 ---> Running in 5f8a9c2b3d4e
 ---> 8f4a2c6e9d1b
Step 4/4 : RUN echo "Environment: $APP_ENV"
 ---> Running in 3d7f2a1c8e5b
Environment: production
 ---> 9c2d4e7f1a3b
Successfully built 9c2d4e7f1a3b

Variables persist in running containers
Available in all subsequent build steps
Can be overridden at runtime with -e flag

Multiple Variables and Defaults

Set multiple environment variables with backslash continuation.

Code

1
FROM node:18-alpine
2
ENV NODE_ENV=production \
3
    PORT=3000 \
4
    LOG_LEVEL=info \
5
    DATABASE_URL=postgresql://localhost/db
6
RUN echo "Running in $NODE_ENV mode on port $PORT"

Execution

$ docker build -t app:latest .
Successfully built 5c2f8e1a3d7b

$ docker run app:latest env
NODE_ENV=production
PORT=3000
LOG_LEVEL=info
DATABASE_URL=postgresql://localhost/db

Multiple ENV values on single line with backslash
All variables available in container at runtime

Variable Substitution in Dockerfile

Use variables in subsequent ENV declarations and RUN instructions.

Code

1
FROM ubuntu:20.04
2
ENV APP_VERSION=2.5.1
3
ENV APP_PATH=/opt/app-${APP_VERSION}
4
RUN mkdir -p $APP_PATH && echo "App path: $APP_PATH"
5
LABEL version="${APP_VERSION}"

Execution

$ docker build -t app:2.5.1 .
Step 4/5 : RUN mkdir -p $APP_PATH && echo "App path: $APP_PATH"
 ---> Running in 5f8a9c2b3d4e
App path: /opt/app-2.5.1
 ---> 7c9e4f2b3a5d
Successfully built 7c9e4f2b3a5d

${VAR} syntax substitutes variable values
Variables only available from that line onward

ARG - Build Arguments

Define build-time arguments that don't persist in final image

ARG for Build-Time Configuration

ARG defines build-time arguments passed via --build-arg flag, not persisted in image.

Code

1
FROM python:3.11-slim
2
ARG BUILD_DATE
3
ARG VCS_REF
4
ENV BUILD_DATE=${BUILD_DATE}
5
ENV VCS_REF=${VCS_REF}
6
RUN echo "Built on: $BUILD_DATE from commit: $VCS_REF"

Execution

$ docker build --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
               --build-arg VCS_REF=$(git rev-parse --short HEAD) \
               -t app:latest .
Step 1/5 : FROM python:3.11-slim
 ---> b9ef8f396e26
Step 5/5 : RUN echo "Built on: $BUILD_DATE from commit: $VCS_REF"
 ---> Running in 5f8a9c2b3d4e
Built on: 2026-02-28T12:00:00Z from commit: abc123xyz
 ---> 8f4a2c6e9d1b
Successfully built 8f4a2c6e9d1b

Build arguments only available during build
Not included in final image
Use ENV to persist values

ARG with Default Values

ARG with default values that can be overridden at build time.

Code

1
FROM node:18-alpine
2
ARG NODE_ENV=development
3
ARG VERSION=1.0.0
4
ARG PORT=3000
5
ENV NODE_ENV=${NODE_ENV} \
6
    VERSION=${VERSION} \
7
    PORT=${PORT}
8
RUN echo "Building v$VERSION for $NODE_ENV on port $PORT"

Execution

$ docker build -t app:latest .
Step 5/5 : RUN echo "Building v$VERSION for $NODE_ENV on port $PORT"
 ---> Running in 5f8a9c2b3d4e
Building v1.0.0 for development on port 3000
 ---> 7c9e4f2b3a5d

$ docker build --build-arg NODE_ENV=production \
               --build-arg VERSION=2.0.0 \
               -t app:2.0.0 .
Step 5/5 : RUN echo "Building v$VERSION for $NODE_ENV on port $PORT"
 ---> Running in 3d7f2a1c8e5b
Building v2.0.0 for production on port 3000
 ---> 8b4f3e2c9a1d

Defaults used if no --build-arg provided
Can be overridden per build

Variable Substitution and Defaults

Advanced variable substitution patterns in Dockerfile

Variable Expansion with Defaults

Use variables in FROM and subsequent instructions for flexible builds.

Code

1
ARG UBUNTU_VERSION=20.04
2
FROM ubuntu:${UBUNTU_VERSION}
3
ARG APP_PATH=/opt/app
4
ARG APP_USER=appuser
5
RUN mkdir -p ${APP_PATH} && \
6
    useradd -r -m -d ${APP_PATH} ${APP_USER}

Execution

$ docker build -t app:focal .
Successfully built 7c9e4f2b3a5d

$ docker build --build-arg UBUNTU_VERSION=22.04 \
               -t app:jammy .
Step 1/4 : FROM ubuntu:22.04
 ---> 6790c6674aaa
Successfully built 4b2f7d9a1c5e

ARG before FROM available in FROM instruction
Base image variant changes based on ARG

Build-Stage Variables

ARG declared at different stages for multi-stage build flexibility.

Code

1
ARG GOLANG_VERSION=1.21
2
FROM golang:${GOLANG_VERSION} AS builder
3
ARG VERSION=1.0.0
4
WORKDIR /src
5
RUN echo "Building with Go $GOLANG_VERSION, version $VERSION"
6

7
FROM alpine:3.18
8
ARG VERSION=1.0.0
9
COPY --from=builder /src /app
10
ENV VERSION=${VERSION}

Execution

$ docker build --build-arg GOLANG_VERSION=1.22 \
               --build-arg VERSION=2.0.0 \
               -t app:2.0.0 .
Step 1/6 : ARG GOLANG_VERSION=1.21
 ---> Running in 5f8a9c2b3d4e
Step 2/6 : FROM golang:1.22
 ---> 2d8c4f1a9e3b
Step 3/6 : ARG VERSION=1.0.0
 ---> Running in 3d7f2a1c8e5b
Successfully built 5c2f8e1a3d7b

ARG before FROM is global
ARG in stage is local to that stage
Each stage can redefine ARG

Working Directory & Volumes

WORKDIR - Working Directory

Set working directory for subsequent instructions

WORKDIR Basic Usage

WORKDIR sets current working directory for COPY, RUN, CMD, and ENTRYPOINT.

Code

1
FROM python:3.11-slim
2
WORKDIR /app
3
COPY . .
4
RUN ls -la

Execution

$ docker build -t app:latest .
Step 1/4 : FROM python:3.11-slim
 ---> b9ef8f396e26
Step 2/4 : WORKDIR /app
 ---> Running in a1b2c3d4e5f6
 ---> 7e2f4c8a1d3b
Step 3/4 : COPY . .
 ---> 3c5f9a2e7d1b
Step 4/4 : RUN ls -la
 ---> Running in 5f8a9c2b3d4e
total 48
drwxr-xr-x  8 root root    4096 Feb 28 12:00 .
-rw-r--r--  1 root root    1234 Feb 28 12:00 main.py
-rw-r--r--  1 root root     234 Feb 28 12:00 requirements.txt
 ---> 8f4a2c6e9d1b
Successfully built 8f4a2c6e9d1b

Creates directory if it doesn't exist
Subsequent COPY/ADD use this as destination
RUN commands execute in this directory

Multiple WORKDIR Instructions

Multiple WORKDIR instructions change directory progressively.

Code

1
FROM node:18-alpine
2
WORKDIR /app
3
COPY package.json .
4
RUN npm install
5
WORKDIR /app/src
6
COPY src .

Execution

$ docker build -t app:latest .
Successfully built 5c2f8e1a3d7b

Each WORKDIR is cumulative (relative paths work)
/app and /app/src are different working directories

WORKDIR with Variables

Use ARG/ENV variables in WORKDIR for flexible directory paths.

Code

1
FROM ubuntu:20.04
2
ARG APP_HOME=/usr/local/app
3
ENV APP_HOME=${APP_HOME}
4
WORKDIR ${APP_HOME}
5
RUN echo "Application home: $(pwd)"

Execution

$ docker build --build-arg APP_HOME=/opt/application \
               -t app:latest .
Step 4/5 : WORKDIR /opt/application
 ---> Running in 5f8a9c2b3d4e
 ---> 7c9e4f2b3a5d
Step 5/5 : RUN echo "Application home: $(pwd)"
 ---> Running in 3d7f2a1c8e5b
Application home: /opt/application
 ---> 8b4f3e2c9a1d

Variables interpolated at build time

VOLUME - Data Persistence Points

Define mount points for persistent data

VOLUME for Database Storage

VOLUME declares mount points for persistent data that survives container removal.

Code

1
FROM postgres:15-alpine
2
VOLUME ["/var/lib/postgresql/data"]
3
EXPOSE 5432
4
CMD ["postgres"]

Execution

$ docker build -t postgres-custom:latest .
Successfully built 7c9e4f2b3a5d

$ docker run -d postgres-custom:latest
4f8e2c7a3b1d

$ docker inspect 4f8e2c7a3b1d --format='{{json .Mounts}}'
[{"Type":"volume","Name":"abc123def456","Source":"...","Destination":"/var/lib/postgresql/data"...}]

Creates anonymous volume if not specified
Data persists even if container is deleted
Can be mounted by other containers

Multiple Volumes

Multiple VOLUME instructions create separate mount points for different data.

Code

1
FROM mysql:8.0
2
VOLUME ["/var/lib/mysql", "/var/log/mysql"]
3
EXPOSE 3306
4
ENV MYSQL_ROOT_PASSWORD=secret
5
CMD ["mysqld"]

Execution

$ docker run -d mysql-custom:latest
5f9d3a2c8e1b

$ docker volume ls | grep mysql
volumes     abc123def456        (database files)
volumes     def789ghi012        (log files)

Each VOLUME is independent
Can mount to named volumes with -v flag

Exposing Ports

EXPOSE - Port Declarations

Document which ports the application listens on

EXPOSE Single Port

EXPOSE documents which ports container listens on (does not actually publish).

Code

1
FROM nginx:1.25-alpine
2
EXPOSE 80
3
EXPOSE 443
4
COPY index.html /usr/share/nginx/html/

Execution

$ docker build -t web-server:latest .
Successfully built 5c2f8e1a3d7b

$ docker inspect web-server:latest --format='{{json .ExposedPorts}}'
{"80/tcp":{},"443/tcp":{}}

EXPOSE is declarative and informational
Does NOT actually publish ports
Use -p flag at runtime to publish

EXPOSE Multiple Ports

Multiple EXPOSE declarations for application and debug ports.

Code

1
FROM node:18-alpine
2
EXPOSE 3000 3001 9229
3
COPY . .
4
RUN npm install
5
CMD ["npm", "start"]

Execution

$ docker build -t node-app:latest .
Successfully built 7c9e4f2b3a5d

3000: application port
3001: alternative service
9229: Node.js debugger port

EXPOSE with Port Range

EXPOSE range of ports for applications using dynamic port allocation.

Code

1
FROM ubuntu:20.04
2
EXPOSE 8000-8100
3
RUN apt-get update && apt-get install -y netcat
4
CMD ["nc", "-l", "-p", "8000"]

Execution

$ docker build -t range-app:latest .
Successfully built 8b4f3e2c9a1d

$ docker run -p 8000-8100:8000-8100 range-app:latest

Useful for services with multiple instances
Port range notation: START-END

Entry Points & Commands

CMD - Default Command

Specify default command to run when container starts

CMD Shell Form

CMD shell form executes command through shell, allowing variable expansion.

Code

1
FROM python:3.11-slim
2
COPY . /app
3
WORKDIR /app
4
RUN pip install -r requirements.txt
5
CMD python app.py

Execution

$ docker build -t python-app:latest .
Successfully built 5c2f8e1a3d7b

$ docker run python-app:latest
Starting application...
App is running

Runs via /bin/sh -c
Can use environment variables
Same as typing command in shell

CMD Exec Form (JSON)

CMD exec form calls command directly without shell, better for signals.

Code

1
FROM node:18-alpine
2
COPY . /app
3
WORKDIR /app
4
RUN npm install
5
CMD ["node", "server.js"]

Execution

$ docker build -t node-app:latest .
Successfully built 7c9e4f2b3a5d

$ docker run node-app:latest
Server listening on port 3000

No shell interpretation
Each element becomes separate argument
Signals (SIGTERM) properly delivered

Override CMD at Runtime

CMD can be overridden by providing command at docker run time.

Code

1
FROM python:3.11-slim
2
COPY . /app
3
WORKDIR /app
4
RUN pip install -r requirements.txt
5
CMD ["python", "app.py"]

Execution

$ docker run python-app:latest
Running app.py...

$ docker run python-app:latest python -m pytest tests/
Running tests...
test_app.py::test_main PASSED

Container image has default CMD
Passing command at runtime overrides it

ENTRYPOINT - Entry Point

Configure container as executable with ENTRYPOINT

ENTRYPOINT with Exec Form

ENTRYPOINT with exec form makes container behave as executable.

Code

1
FROM python:3.11-slim
2
COPY entrypoint.sh /usr/local/bin/
3
RUN chmod +x /usr/local/bin/entrypoint.sh
4
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
5
CMD ["python", "app.py"]

Execution

$ docker build -t app:latest .
Successfully built 5c2f8e1a3d7b

$ docker run app:latest
Setup: Creating database...
Starting application...

$ docker run app:latest python -c "import sys; print(sys.version)"
Setup: Creating database...
3.11.2

ENTRYPOINT is the wrapper script
CMD provides default arguments
Useful for setup before main app

ENTRYPOINT with Shell Script

ENTRYPOINT executes shell script as main process.

Code

1
FROM alpine:3.18
2
RUN apk add --no-cache bash curl
3
COPY health-check.sh /usr/local/bin/health-check
4
RUN chmod +x /usr/local/bin/health-check
5
ENTRYPOINT ["bash", "/usr/local/bin/health-check"]

Execution

$ docker build -t health-checker:latest .
Successfully built 7c9e4f2b3a5d

$ docker run health-checker:latest api.example.com
Checking health of api.example.com
Status: OK

Script runs as PID 1 in container
Must handle signals properly
Can accept arguments from docker run

ENTRYPOINT with CMD

ENTRYPOINT + CMD combination where tini manages signals properly.

Code

1
FROM ubuntu:20.04
2
RUN apt-get update && apt-get install -y curl tini
3
COPY . /app
4
WORKDIR /app
5
ENTRYPOINT ["tini", "--"]
6
CMD ["./app", "start"]

Execution

$ docker build -t tini-app:latest .
Successfully built 8b4f3e2c9a1d

$ docker run tini-app:latest
Starting app with tini init system...

tini is lightweight init system for containers
Ensures proper signal handling
CMD provides default arguments to ENTRYPOINT

CMD and ENTRYPOINT Interaction

Understand how CMD and ENTRYPOINT work together

ENTRYPOINT as Wrapper with CMD Arguments

ENTRYPOINT and CMD together allow flexible command execution with wrapper.

Code

1
FROM python:3.11-slim
2
COPY wrapper.sh /usr/local/bin/
3
COPY app.py .
4
RUN chmod +x /usr/local/bin/wrapper.sh
5
ENTRYPOINT ["/usr/local/bin/wrapper.sh"]
6
CMD ["python", "app.py"]

Execution

$ docker build -t wrapped-app:latest .
Successfully built 5c2f8e1a3d7b

$ docker run wrapped-app:latest
[WRAPPER] Starting application...
App is running

$ docker run wrapped-app:latest python -c "print('test')"
[WRAPPER] Starting...
test

CMD becomes arguments to ENTRYPOINT
Can override CMD at runtime
Wrapper executes first, then CMD

Pure ENTRYPOINT (No CMD)

ENTRYPOINT alone without CMD for single-purpose containers.

Code

1
FROM golang:1.21-alpine
2
WORKDIR /src
3
COPY . .
4
RUN go build -o /app .
5
ENTRYPOINT ["/app"]

Execution

$ docker build -t go-app:latest .
Successfully built 7c9e4f2b3a5d

$ docker run go-app:latest --help
Usage: app [OPTIONS]

Container is tool-like (always runs binary)
Can still pass arguments
No default command

Build Optimization

Layer Caching Strategy

Understand Docker layer caching to speed up builds

Inefficient Layer Caching

Copying all files early invalidates cache when any file changes, forcing reinstall.

Code

1
FROM python:3.11-slim
2
COPY . .
3
RUN pip install -r requirements.txt
4
RUN python app.py

Execution

$ docker build -t app:latest .
Step 1/4 : FROM python:3.11-slim
 ---> b9ef8f396e26
Step 2/4 : COPY . .
 ---> 7e2f4c8a1d3b
Step 3/4 : RUN pip install -r requirements.txt
 ---> Running in 5f8a9c2b3d4e
Collecting requests...
 ---> 8f4a2c6e9d1b  (3 min 45 sec)
Step 4/4 : RUN python app.py
 ---> Running in 3d7f2a1c8e5b
 ---> 9c2d4e7f1a3b

# After changing app.py
$ docker build -t app:latest .
Step 1/4 : FROM python:3.11-slim
 ---> b9ef8f396e26
Step 2/4 : COPY . .
 ---> (invalidated by changed app.py)
Step 3/4 : RUN pip install -r requirements.txt
 ---> Running in 5f8a9c2b3d4e (runs again!)
Collecting requests...
 ---> 8f4a2c6e9d1b  (3 min 45 sec - WASTED TIME)

COPY . . invalidates all subsequent layers on any change
Python packages reinstalled unnecessarily

Optimized Layer Caching

Copy stable files (dependencies) first, changing files last to preserve cache.

Code

1
FROM python:3.11-slim
2
COPY requirements.txt .
3
RUN pip install -r requirements.txt
4
COPY . .
5
CMD ["python", "app.py"]

Execution

$ docker build -t app:latest .
Step 1/5 : FROM python:3.11-slim
 ---> b9ef8f396e26
Step 2/5 : COPY requirements.txt .
 ---> 7e2f4c8a1d3b
Step 3/5 : RUN pip install -r requirements.txt
 ---> Running in 5f8a9c2b3d4e
Collecting requests...
 ---> 8f4a2c6e9d1b  (3 min 45 sec)
Step 4/5 : COPY . .
 ---> 9d5e3f2a8c1b
Step 5/5 : CMD ["python", "app.py"]
 ---> 5c2f8e1a3d7b

# After changing app.py
$ docker build -t app:latest .
Step 1/5 : FROM python:3.11-slim
 ---> b9ef8f396e26 (cached)
Step 2/5 : COPY requirements.txt .
 ---> 7e2f4c8a1d3b (cached)
Step 3/5 : RUN pip install -r requirements.txt
 ---> 8f4a2c6e9d1b (cached) - REUSED!
Step 4/5 : COPY . .
 ---> (invalidated by changed app.py)
Step 5/5 : CMD ["python", "app.py"]
 ---> 5c2f8e1a3d7b
Total time: 5 seconds vs 3 min 50 sec

Stable: requirements.txt, package.json rarely change
Volatile: app.py, src files change frequently
Saves significant build time

Cache with External Mounts

Cache mounts preserve package manager caches across builds.

Code

1
FROM node:18-alpine
2
WORKDIR /app
3
COPY package.json package-lock.json .
4
RUN --mount=type=cache,target=/root/.npm \
5
    npm ci --prefer-offline --no-audit
6
COPY . .
7
RUN npm run build

Execution

$ docker build --build-context=. \
               --progress=plain \
               -t app:latest .
Step 1/6 : FROM node:18-alpine
 ---> 52f389ea4d15
Step 4/6 : RUN --mount=type=cache,target=/root/.npm ...
 ---> Running in 5f8a9c2b3d4e
added 1200 packages in 45s

# Second build
$ docker build -t app:latest .
Step 4/6 : RUN --mount=type=cache,target=/root/.npm ...
 ---> Running in 3d7f2a1c8e5b
up to date (cached packages reused!)
added 1200 packages in 2s

npm/yarn/pip cache reused
Requires BuildKit (DOCKER_BUILDKIT=1)
Dramatically speeds up dependency installation

.dockerignore File

Exclude files from build context to speed up builds

Basic .dockerignore

.dockerignore filters out unnecessary files before sending to Docker daemon.

Code

1
# .dockerignore content
2
.git
3
.gitignore
4
.github
5
node_modules
6
.env
7
.env.local
8
dist
9
build
10
__pycache__
11
*.log
12
.DS_Store
13
.vscode
14
.idea
15
npm-debug.log
16
.npm
17
coverage

Dramatically reduces build context size
Speeds up build (less data to transfer)
Similar to .gitignore syntax

Comprehensive .dockerignore

Comprehensive .dockerignore excludes all unnecessary files from context.

Code

1
# .dockerignore with multiple patterns
2
# Version control
3
.git
4
.gitignore
5
.github
6
.gitlab-ci.yml
7

8
# Dependencies (often excluded from repo)
9
node_modules
10
venv
11
vendor
12
.bundle
13

14
# Development files
15
.env
16
.env.*.local
17
.vscode
18
.idea
19
.DS_Store
20
*.swp
21
*.swo
22
*~
23

24
# Build artifacts
25
dist
26
build
27
*.tmp
28
coverage
29

30
# Logs
31
*.log
32
logs
33

34
# Docker
35
Dockerfile
36
compose.yml
37
.dockerignore
38

39
# CI/CD
40
.circleci
41
.travis.yml
42
Jenkinsfile
43

44
# Documentation
45
docs
46
README.md
47

48
# Testing
49
tests
50
__pycache__
51
.pytest_cache
52
.coverage

Execution

$ docker build -t app:latest .
# Context drastically reduced

Reduces build context from 500MB to 11MB
Speeds up docker build command significantly

Multi-Stage Build Optimization

Advanced multi-stage patterns for minimal images

Multi-Stage Node.js Build

Multi-stage Node.js avoids dev dependencies in final image.

Code

1
FROM node:18-alpine AS builder
2
WORKDIR /src
3
COPY package*.json ./
4
RUN npm ci --only=production
5

6
FROM node:18-alpine
7
WORKDIR /app
8
COPY --from=builder /src/node_modules ./node_modules
9
COPY . .
10
USER nobody
11
CMD ["node", "server.js"]

Execution

$ docker build -t node-app:latest .
Step 1/8 : FROM node:18-alpine AS builder
 ---> 52f389ea4d15
Step 2/8 : WORKDIR /src
 ---> Running in 5f8a9c2b3d4e
Step 4/8 : RUN npm ci --only=production
 ---> Running in 3d7f2a1c8e5b
added 120 packages in 30s
 ---> 7c9e4f2b3a5d
Step 5/8 : FROM node:18-alpine
 ---> 52f389ea4d15
Step 8/8 : CMD ["node", "server.js"]
 ---> Running in 2f5c8e1a3d7b
Successfully built 5f9d3a2c8e1b

$ docker images node-app:latest
REPOSITORY   TAG       IMAGE ID       SIZE
node-app     latest    5f9d3a2c8e1b   156MB

Builder stage includes all dependencies
Final stage has only production dependencies
Size reduction: devDependencies excluded

Multi-Stage Rust Build

Rust compiler (2GB) not in final image, only binary (2-5MB).

Code

1
FROM rust:1.75 AS builder
2
WORKDIR /usr/src/app
3
COPY . .
4
RUN cargo build --release
5

6
FROM debian:12-slim
7
COPY --from=builder /usr/src/app/target/release/app /usr/local/bin/
8
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
9
USER nobody
10
ENTRYPOINT ["app"]

Execution

$ docker build -t rust-app:latest .
Step 1/6 : FROM rust:1.75
 ---> f7d8c1e2a9b3
Step 3/6 : RUN cargo build --release
 ---> Running in 5f8a9c2b3d4e
Compiling app v1.0.0
 ---> 7c9e4f2b3a5d (5 min 30 sec)
Step 4/6 : FROM debian:12-slim
 ---> 5f8a9c2b3d4e
Step 5/6 : COPY --from=builder /usr/src/app/target/release/app /usr/local/bin/
 ---> Running in 3d7f2a1c8e5b
 ---> 4b2f7d9a1c5e
Successfully built 4b2f7d9a1c5e

$ docker images rust-app:latest
REPOSITORY   TAG       IMAGE ID       SIZE
rust-app     latest    4b2f7d9a1c5e   45MB

Builder: rust:1.75 (2GB with compiler)
Final: debian:12-slim + binary (45MB total)
2GB -> 45MB reduction!

Metadata & Advanced

LABEL - Image Metadata

Add metadata labels to Docker images

Common Docker Labels

LABEL adds metadata to image for documentation and organization.

Code

1
FROM python:3.11-slim
2
LABEL maintainer="devops@example.com"
3
LABEL version="1.2.3"
4
LABEL description="Python API application for order processing"
5
LABEL org.opencontainers.image.source="https://github.com/org/repo"
6
LABEL org.opencontainers.image.created="2026-02-28T00:00:00Z"

Execution

$ docker build -t order-api:1.2.3 .
Successfully built 7c9e4f2b3a5d

$ docker inspect order-api:1.2.3 --format='{{json .Config.Labels}}'
{
  "maintainer":"devops@example.com",
  "version":"1.2.3",
  "description":"Python API...",
  "org.opencontainers.image.source":"https://github.com/org/repo",
  "org.opencontainers.image.created":"2026-02-28T00:00:00Z"
}

Labels appear in docker inspect output
Useful for filtering and organizing images
No size impact

Multi-line Labels

Multiple labels using backslash continuation for readability.

Code

1
FROM node:18-alpine
2
LABEL maintainer="platform-team@company.com" \
3
      org.opencontainers.image.title="Web Server" \
4
      org.opencontainers.image.description="Production Node.js web server" \
5
      org.opencontainers.image.version="2.1.0" \
6
      org.opencontainers.image.authors="John Doe, Jane Smith"

Execution

$ docker build -t web-server:2.1.0 .
Successfully built 5c2f8e1a3d7b

Backslash extends single instruction across lines
Each label can be queried independently

USER - Container User

Specify user to run container as instead of root

Run as Created User

Create dedicated user and switch to it before running application.

Code

1
FROM ubuntu:20.04
2
RUN apt-get update && apt-get install -y nodejs
3
RUN groupadd -r appuser && useradd -r -g appuser appuser
4
WORKDIR /home/appuser/app
5
COPY --chown=appuser:appuser . .
6
USER appuser
7
CMD ["node", "server.js"]

Execution

$ docker build -t app:latest .
Successfully built 5c2f8e1a3d7b

$ docker run app:latest
(running as appuser, not root)

$ docker run app:latest id
uid=100(appuser) gid=101(appuser) groups=101(appuser)

Root user is dangerous in containers
appuser has no shell (better security)
Works with CMD/ENTRYPOINT

Run as Numeric UID

Use numeric UID instead of username for better portability.

Code

1
FROM python:3.11-slim
2
RUN groupadd -r app && useradd -r -u 1001 -g app app
3
WORKDIR /app
4
COPY --chown=1001:1000 . .
5
USER 1001
6
CMD ["python", "app.py"]

Execution

$ docker build -t app:latest .
Successfully built 7c9e4f2b3a5d

$ docker run app:latest whoami
# Returns: 1001 (numeric ID)

1001 common for first non-system user
More portable across systems

HEALTHCHECK - Container Health

Define health check to determine if container is running properly

HTTP Endpoint Health Check

Check container health by making HTTP request to application.

Code

1
FROM nginx:1.25-alpine
2
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
3
  CMD curl -f http://localhost/ || exit 1
4
COPY index.html /usr/share/nginx/html/

Execution

$ docker build -t web-server:latest .
Successfully built 5c2f8e1a3d7b

$ docker run -d web-server:latest
4f8e2c7a3b1d

$ sleep 10 && docker inspect 4f8e2c7a3b1d --format='{{.State.Health.Status}}'
healthy

interval=30s: check every 30 seconds
timeout=3s: health check must complete in 3 seconds
start-period=5s: grace period before checks start
retries=3: 3 failed checks = unhealthy

Application-Specific Health Check

Use application-specific tools for health checks.

Code

1
FROM postgres:15-alpine
2
HEALTHCHECK --interval=10s --timeout=5s --start-period=10s --retries=5 \
3
  CMD ["pg_isready", "-U", "postgres"]

Execution

$ docker build -t postgres-custom:latest .
Successfully built 7c9e4f2b3a5d

$ docker run -d postgres-custom:latest
5f9d3a2c8e1b

$ docker container ls
CONTAINER ID   IMAGE                 STATUS
5f9d3a2c8e1b   postgres-custom:latest   Up 15s (healthy)

pg_isready for PostgreSQL
redis-cli PING for Redis
mysql -e "SELECT 1" for MySQL

Script-Based Health Check

Custom script for complex health checks.

Code

1
FROM node:18-alpine
2
COPY health-check.js /usr/local/bin/
3
HEALTHCHECK --interval=15s --timeout=5s --retries=3 \
4
  CMD node /usr/local/bin/health-check.js
5
COPY . .
6
CMD ["node", "server.js"]

Execution

$ docker build -t app:latest .
Successfully built 8b4f3e2c9a1d

Exit code 0 = healthy
Exit code 1 = unhealthy
Script can hit any endpoint

Dockerfile Shell Form

Control shell behavior with

Use Bash Instead of /bin/sh

Change default shell from /bin/sh to /bin/bash for bash-specific features.

Code

1
FROM ubuntu:20.04
2
SHELL ["/bin/bash", "-c"]
3
RUN apt-get update && apt-get install -y curl
4
RUN <<EOF
5
for i in {1..5}; do
6
  echo "Iteration: $i"
7
done
8
EOF

Execution

$ docker build -t app:latest .
Step 1/3 : FROM ubuntu:20.04
 ---> 1d622ef08d5e
Step 2/3 : SHELL ["/bin/bash", "-c"]
 ---> Running in 5f8a9c2b3d4e
 ---> 7c9e4f2b3a5d
Step 3/3 : RUN <<EOF
 ---> Running in 3d7f2a1c8e5b
Iteration: 1
Iteration: 2
Iteration: 3
Iteration: 4
Iteration: 5
Successfully built 8b4f3e2c9a1d

SHELL must appear early in Dockerfile
Affects all RUN, CMD, ENTRYPOINT, COPY --chown
Alpine Linux doesn't have bash by default

Multi-Line RUN with Heredoc

Heredoc syntax for multi-line RUN commands without backslash continuation.

Code

1
FROM python:3.11-slim
2
RUN <<EOF
3
  apt-get update
4
  apt-get install -y curl git vim
5
  apt-get clean
6
  rm -rf /var/lib/apt/lists/*
7
EOF

Execution

$ docker build -t app:latest .
Step 1/2 : FROM python:3.11-slim
 ---> b9ef8f396e26
Step 2/2 : RUN <<EOF
 ---> Running in 5f8a9c2b3d4e
Reading package lists...
Processing triggers...
 ---> 8f4a2c6e9d1b
Successfully built 8f4a2c6e9d1b

Available in Docker 23.09+
Cleaner than backslash continuation
Each line individual command (not chained)

Dockerfile

Getting Started

FROM - Base Image Selection

Accessibility

Best Practices

Common Errors

Keywords

FROM Ubuntu LTS Base Image

FROM Alpine Lightweight Base

FROM Official Python Image

Image Naming and Tags

Accessibility

Best Practices

Common Errors

Keywords

Tag Image with Domain Registry

Multiple Tags for Single Image

Multi-Stage Dockerfile Overview

Accessibility

Best Practices

Common Errors

Keywords

Single Stage vs Multi-Stage Comparison

Optimized Multi-Stage Build

Copying & Adding Files

COPY - Basic File Operations

Accessibility

Best Practices

Common Errors

Keywords

Copy Single File

Copy Multiple Files with Wildcard

Copy Directory Recursively

COPY with Ownership

Accessibility

Best Practices

Common Errors

Keywords

Copy with User Ownership

Copy with Numeric User ID

ADD - Advanced File Operations

Accessibility

Best Practices

Common Errors

Keywords

ADD from Remote URL

ADD Automatically Extracts TAR

Running Commands

RUN - Basic Command Execution

Accessibility

Best Practices

Common Errors

Keywords

RUN Single Command

RUN Chain Commands with AND

RUN Install Multiple Packages

RUN - Exec Form vs Shell Form

Accessibility

Best Practices

Common Errors

Keywords

Shell Form (Default)

Exec Form (JSON Array)

Shell Parameter in RUN

Environment & Variables

ENV - Environment Variables

Accessibility

Best Practices

Common Errors

Keywords

Set Single Environment Variable

Multiple Variables and Defaults

Variable Substitution in Dockerfile

ARG - Build Arguments

Accessibility

Best Practices

Common Errors

Keywords

ARG for Build-Time Configuration

ARG with Default Values