Docker Complete Guide 2025: From Container Basics to Multi-stage Builds, Compose, and Production Deployment

# Example: limiting memory to 256MB with cgroup
sudo cgcreate -g memory:mycontainer
echo 268435456 | sudo tee /sys/fs/cgroup/memory/mycontainer/memory.limit_in_bytes

┌─────────────────────────────────────────────────────────────┐
│               Container Architecture                         │
├──────────┬──────────┬──────────┬──────────┐                 │
│  App A   │  App B   │  App C   │  App D   │                 │
├──────────┼──────────┼──────────┼──────────┤                 │
│  Bins/   │  Bins/   │  Bins/   │  Bins/   │                 │
│  Libs    │  Libs    │  Libs    │  Libs    │                 │
├──────────┴──────────┴──────────┴──────────┤                 │
│           Container Runtime                │                 │
├────────────────────────────────────────────┤                 │
│              Host OS Kernel                │                 │
├────────────────────────────────────────────┤                 │
│              Infrastructure                │                 │
└────────────────────────────────────────────┘                 │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                   VM Architecture                            │
├──────────┬──────────┬──────────┬──────────┐                 │
│  App A   │  App B   │  App C   │  App D   │                 │
├──────────┼──────────┼──────────┼──────────┤                 │
│  Bins/   │  Bins/   │  Bins/   │  Bins/   │                 │
│  Libs    │  Libs    │  Libs    │  Libs    │                 │
├──────────┼──────────┼──────────┼──────────┤                 │
│ Guest OS │ Guest OS │ Guest OS │ Guest OS │                 │
├──────────┴──────────┴──────────┴──────────┤                 │
│              Hypervisor                    │                 │
├────────────────────────────────────────────┤                 │
│              Host OS                       │                 │
├────────────────────────────────────────────┤                 │
│              Infrastructure                │                 │
└────────────────────────────────────────────┘                 │
└─────────────────────────────────────────────────────────────┘

┌─────────────┐     REST API     ┌─────────────────────┐
│   Docker     │ ──────────────> │   Docker Daemon      │
│   CLI        │                 │   (dockerd)          │
│              │                 │                      │
│  docker run  │                 │  ┌─────────────────┐ │
│  docker build│                 │  │   containerd    │ │
│  docker pull │                 │  │                 │ │
└─────────────┘                 │  │  ┌───────────┐  │ │
                                │  │  │   runc    │  │ │
                                │  │  └───────────┘  │ │
                                │  └─────────────────┘ │
                                └─────────────────────┘

# Image management commands
docker images                    # List local images
docker pull nginx:1.25-alpine    # Download an image
docker image inspect nginx       # Image details
docker image prune               # Clean unused images

# Running and managing containers
docker run -d --name my-nginx -p 8080:80 nginx:1.25-alpine
docker ps                        # List running containers
docker logs my-nginx             # View logs
docker exec -it my-nginx /bin/sh # Access container shell
docker stop my-nginx             # Stop
docker rm my-nginx               # Remove

# Creating and using volumes
docker volume create my-data
docker run -d -v my-data:/app/data my-app
docker run -d -v /host/path:/container/path my-app  # Bind mount

# Creating and managing networks
docker network create my-network
docker run -d --network my-network --name api my-api
docker run -d --network my-network --name db postgres
# The api container can access db at db:5432

# Select base image
FROM node:20-alpine

# Add metadata
LABEL maintainer="dev@example.com"
LABEL version="1.0"

# Build-time variable (only available during build)
ARG NODE_ENV=production

# Environment variable (available at runtime too)
ENV NODE_ENV=$NODE_ENV
ENV PORT=3000

# Set working directory
WORKDIR /app

# Copy files (COPY is recommended)
COPY package*.json ./

# Execute command
RUN npm ci --only=production

# Copy source code
COPY . .

# Document port (does not actually open the port)
EXPOSE 3000

# Container health check
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# Switch to non-root user (security)
USER node

# Command to run when container starts
ENTRYPOINT ["node"]
CMD ["server.js"]

# CMD only - can be fully overridden at docker run
CMD ["python", "app.py"]
# docker run my-image python test.py  (CMD replaced with test.py)

# ENTRYPOINT only - always executes
ENTRYPOINT ["python"]
# docker run my-image app.py  (runs python app.py)

# ENTRYPOINT + CMD combination (most flexible)
ENTRYPOINT ["python"]
CMD ["app.py"]
# docker run my-image         -> python app.py
# docker run my-image test.py -> python test.py

# ARG: exists only during build (not at runtime)
ARG BUILD_VERSION=1.0
RUN echo "Building version: $BUILD_VERSION"

# ENV: exists during build + runtime
ENV APP_VERSION=1.0
# APP_VERSION is available when container runs

# Bad: npm install re-runs on every source change
COPY . .
RUN npm install

# Good: npm install only re-runs when package.json changes
COPY package*.json ./
RUN npm ci
COPY . .

# Bad: Creates 3 layers
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*

# Good: Creates 1 layer + cleans cache
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

# .dockerignore
node_modules
.git
.env
*.md
Dockerfile
docker-compose*.yml
.github
coverage
dist

# Stage 1: Build environment
FROM node:20 AS builder
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# Stage 2: Production environment
FROM node:20-alpine AS production
WORKDIR /app

# Install production dependencies only
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force

# Copy only build artifacts
COPY --from=builder /app/dist ./dist

# Security: non-root user
USER node

EXPOSE 3000
CMD ["node", "dist/server.js"]

# Stage 1: Build
FROM golang:1.22-alpine AS builder
WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/server .

# Stage 2: Minimal image
FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /app/server /server

EXPOSE 8080
ENTRYPOINT ["/server"]

# Stage 1: Build
FROM eclipse-temurin:21-jdk AS builder
WORKDIR /app

COPY gradlew build.gradle settings.gradle ./
COPY gradle ./gradle
RUN ./gradlew dependencies --no-daemon

COPY src ./src
RUN ./gradlew bootJar --no-daemon

# Stage 2: Runtime
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app

COPY --from=builder /app/build/libs/*.jar app.jar

RUN addgroup -S spring && adduser -S spring -G spring
USER spring:spring

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

# Stage 1: Dependency build
FROM python:3.12-slim AS builder
WORKDIR /app

RUN pip install --no-cache-dir poetry
COPY pyproject.toml poetry.lock ./
RUN poetry export -f requirements.txt -o requirements.txt --without-hashes
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# Stage 2: Runtime
FROM python:3.12-slim
WORKDIR /app

COPY --from=builder /install /usr/local
COPY . .

RUN useradd --create-home appuser
USER appuser

EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "app.main:app"]

# docker-compose.yml
version: '3.9'

services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://postgres:secret@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    healthcheck:
      test: ['CMD', 'wget', '--spider', 'http://localhost:3000/health']
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped
    networks:
      - app-network

  db:
    image: postgres:16-alpine
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./init-scripts:/docker-entrypoint-initdb.d
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secret
    ports:
      - '5432:5432'
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - app-network

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes --maxmemory 256mb
    volumes:
      - redis-data:/data
    ports:
      - '6379:6379'
    networks:
      - app-network

  nginx:
    image: nginx:1.25-alpine
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
    depends_on:
      - api
    networks:
      - app-network

volumes:
  postgres-data:
    driver: local
  redis-data:
    driver: local

networks:
  app-network:
    driver: bridge

# Using .env files
services:
  api:
    env_file:
      - .env
      - .env.production

# Docker Secrets (Swarm mode)
services:
  api:
    secrets:
      - db_password
      - api_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    external: true

# Start services (background)
docker compose up -d

# View service logs
docker compose logs -f api

# Scale services
docker compose up -d --scale api=3

# Rebuild + restart services
docker compose up -d --build

# Stop and clean up resources
docker compose down

# Delete everything including volumes
docker compose down -v

# Restart specific service
docker compose restart api

# Check running service status
docker compose ps

# docker-compose.yml (shared)
services:
  api:
    build: ./api

# docker-compose.override.yml (development - auto-loaded)
services:
  api:
    volumes:
      - ./api:/app    # Mount for hot reload
    environment:
      - DEBUG=true
    command: npm run dev

# docker-compose.prod.yml (production)
services:
  api:
    environment:
      - NODE_ENV=production
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 512M
          cpus: "0.5"

# Development (auto-loads override file)
docker compose up

# Production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# Create custom network
docker network create my-app

# Run containers on the same network
docker run -d --name api --network my-app my-api-image
docker run -d --name db --network my-app postgres

# From inside the api container, access db container
# Hostname "db" is automatically resolved
curl http://db:5432

# Specific port mapping
docker run -p 8080:80 nginx

# Bind to specific interface only
docker run -p 127.0.0.1:8080:80 nginx

# Random host port assignment
docker run -p 80 nginx

# Multiple port mappings
docker run -p 80:80 -p 443:443 nginx

# Automatic service discovery in Docker Compose
services:
  api-gateway:
    image: nginx
    depends_on:
      - user-service
      - order-service

  user-service:
    image: my-user-service
    # Accessible from api-gateway at http://user-service:3000

  order-service:
    image: my-order-service
    # Accessible from api-gateway at http://order-service:3000

# Node.js - use built-in node user
FROM node:20-alpine
WORKDIR /app
COPY --chown=node:node . .
RUN npm ci --only=production
USER node
CMD ["node", "server.js"]

# Custom user creation
FROM python:3.12-slim
RUN groupadd -r appgroup && useradd -r -g appgroup appuser
WORKDIR /app
COPY --chown=appuser:appgroup . .
USER appuser
CMD ["python", "app.py"]

docker run --read-only --tmpfs /tmp --tmpfs /var/run my-app

# In Docker Compose
services:
  api:
    read_only: true
    tmpfs:
      - /tmp
      - /var/run

# Scan vulnerabilities with Trivy
trivy image my-app:latest

# Filter by severity
trivy image --severity HIGH,CRITICAL my-app:latest

# Docker Scout (built into Docker Desktop)
docker scout cves my-app:latest
docker scout recommendations my-app:latest

# Snyk
snyk container test my-app:latest

# NEVER do this
ENV API_KEY=sk-1234567890
COPY .env /app/.env

# Correct approach: mount secrets during build (BuildKit)
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci

# Pass secrets during build
DOCKER_BUILDKIT=1 docker build --secret id=npmrc,src=.npmrc -t my-app .

# Install Docker in rootless mode
dockerd-rootless-setuptool.sh install

# Verify
docker info | grep -i rootless
# Security Options: rootless

# Enable Docker Content Trust
export DOCKER_CONTENT_TRUST=1

# Only signed images can be pulled
docker pull my-registry/my-app:latest  # Fails without signature

# Sign images with Cosign (Sigstore)
cosign sign my-registry/my-app:latest
cosign verify my-registry/my-app:latest

[Security Checklist]
- Run as non-root user (USER directive)
- Use minimal base images (Alpine, distroless, scratch)
- Regularly scan images for vulnerabilities (Trivy, Snyk, Scout)
- NEVER include secrets/credentials in Dockerfile
- Use read-only filesystem
- Minimize network exposure
- Set resource limits (memory, CPU)
- Enable Docker Content Trust
- Regularly update base images
- Remove unnecessary packages/tools

# .github/workflows/docker-build.yml
name: Docker Build and Push

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: my-org/my-app

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: my-username
          password: my-token

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/my-org/my-app
          tags: |
            type=ref,event=branch
            type=sha,prefix=
            type=semver,pattern=v{{version}}

      - name: Build and Push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: steps.meta.outputs.tags
          labels: steps.meta.outputs.labels
          cache-from: type=gha
          cache-to: type=gha,mode=max
          platforms: linux/amd64,linux/arm64

# Create Buildx builder
docker buildx create --name multiarch --use

# Build and push for multiple platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag my-registry/my-app:latest \
  --push .

# GitHub Actions Cache
- name: Build with cache
  uses: docker/build-push-action@v5
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max

# Registry-based cache
- name: Build with registry cache
  uses: docker/build-push-action@v5
  with:
    cache-from: type=registry,ref=ghcr.io/my-org/my-app:buildcache
    cache-to: type=registry,ref=ghcr.io/my-org/my-app:buildcache,mode=max

# Set container log driver
docker run -d \
  --log-driver=json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  my-app

# Syslog driver
docker run -d \
  --log-driver=syslog \
  --log-opt syslog-address=tcp://logserver:514 \
  my-app

# Logging in Docker Compose
services:
  api:
    logging:
      driver: json-file
      options:
        max-size: '10m'
        max-file: '3'

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - '9090:9090'

  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
    ports:
      - '8080:8080'

  grafana:
    image: grafana/grafana:latest
    volumes:
      - grafana-data:/var/lib/grafana
    ports:
      - '3000:3000'
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

volumes:
  grafana-data:

# Memory limit: 512MB (OOM Kill on exceed)
docker run -m 512m my-app

# CPU limit: 1.5 cores
docker run --cpus="1.5" my-app

# Combined
docker run -m 512m --cpus="1.5" --memory-swap=1g my-app

# In Docker Compose
services:
  api:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.5'
        reservations:
          memory: 256M
          cpus: '0.5'

// Node.js example
process.on('SIGTERM', async () => {
  console.log('SIGTERM received. Graceful shutdown...')

  // Reject new requests
  server.close(async () => {
    // Close DB connections
    await db.close()
    // Close Redis connections
    await redis.quit()

    console.log('All connections closed. Exiting.')
    process.exit(0)
  })

  // Force exit after 30 seconds
  setTimeout(() => {
    console.error('Forced shutdown after timeout')
    process.exit(1)
  }, 30000)
})

# Correct ENTRYPOINT format in Dockerfile
# Use exec form (SIGTERM delivered directly to app)
ENTRYPOINT ["node", "server.js"]

# Do NOT use shell form (SIGTERM only delivered to sh)
# ENTRYPOINT node server.js  # Don't do this

# Health check in Dockerfile
HEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

# Health check in Docker Compose
services:
  api:
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  db:
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5

# Nearly identical CLI to Docker
podman run -d -p 8080:80 nginx
podman ps
podman images

# Alias for Docker compatibility
alias docker=podman

# ctr - containerd native CLI (low-level)
ctr images pull docker.io/library/nginx:latest
ctr run docker.io/library/nginx:latest my-nginx

# Same UX as Docker
nerdctl run -d -p 8080:80 nginx
nerdctl compose up -d
nerdctl build -t my-app .

# Extra feature: image encryption
nerdctl image encrypt --recipient jwe:public-key.pem my-app encrypted-app

# Install NVIDIA Container Toolkit
distribution=ubuntu22.04
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

# Install packages
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Configure Docker runtime
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Use all GPUs
docker run --gpus all nvidia/cuda:12.3-base nvidia-smi

# Use specific GPUs only
docker run --gpus '"device=0,1"' my-ml-app

# In Docker Compose

services:
  ml-training:
    image: my-ml-app
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]

# PyTorch model serving Dockerfile
FROM pytorch/pytorch:2.2.0-cuda12.1-cudnn8-runtime

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY model/ ./model/
COPY serve.py .

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

CMD ["python", "serve.py"]

# TensorFlow Serving
services:
  tf-serving:
    image: tensorflow/serving:latest-gpu
    ports:
      - '8501:8501'
    volumes:
      - ./models:/models
    environment:
      - MODEL_NAME=my_model
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  triton-server:
    image: nvcr.io/nvidia/tritonserver:24.01-py3
    ports:
      - '8000:8000'
      - '8001:8001'
      - '8002:8002'
    volumes:
      - ./model-repository:/models
    command: tritonserver --model-repository=/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]