Docker & Docker Compose,
explained without the fluff.

services:
  web:
    build: .
    ports:
      - "8080:80"
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

# pull an image
docker pull nginx:latest

# see what's local
docker images

# create + start a container from it
docker run -d --name web -p 8080:80 nginx:latest

# running containers
docker ps

# all containers, including stopped ones
docker ps -a

docker run \
  -d \                  # detached, runs in background
  --name myapp \        # friendly name
  -p 3000:3000 \        # host:container port mapping
  -e NODE_ENV=prod \    # environment variable
  -v $(pwd):/app \      # bind mount current dir into /app
  --restart unless-stopped \
  node:20-alpine

# named volume
docker volume create app-data
docker run -v app-data:/var/lib/data postgres:16

# bind mount
docker run -v /home/me/project:/app -w /app node:20

# shorthand for "current directory"
docker run -v $(pwd):/app -w /app node:20

# tmpfs
docker run --tmpfs /run node:20

# publish container port 80 to host port 8080
docker run -p 8080:80 nginx

# bind to one host interface only
docker run -p 127.0.0.1:8080:80 nginx

docker network ls
docker network inspect bridge

# inline
docker run -e NODE_ENV=production -e PORT=3000 myapp

# from a file
docker run --env-file .env myapp

NODE_ENV=production
PORT=3000
DATABASE_URL=postgres://user:pass@db:5432/app

FROM node:20-alpine        # base image
WORKDIR /app                # cwd for everything after
COPY package*.json ./       # dependency manifests first
RUN npm ci --omit=dev       # cached if package.json unchanged
COPY . .                    # rest of the source
ENV NODE_ENV=production
EXPOSE 3000                 # documents the port, doesn't publish it
USER node                   # drop root
CMD ["node", "server.js"]   # default command

docker build -t myapp:1.0 .
docker build --build-arg VERSION=1.0 -t myapp .

node_modules
.git
.env
*.log
dist
.vscode
Dockerfile
README.md
**/__pycache__

docker history myapp:1.0     # see the layers and their sizes
docker build --no-cache -t myapp .

# build stage
FROM golang:1.22 AS builder
WORKDIR /src
COPY . .
RUN go build -o /out/server .

# runtime stage — no Go toolchain
FROM alpine:3.20
COPY --from=builder /out/server /usr/local/bin/server
USER nobody
CMD ["server"]

# tag format: [registry/]namespace/repo[:tag]
docker build -t myuser/myapp:1.0 .
docker login
docker push myuser/myapp:1.0

# tag + push to a different registry
docker tag myapp:1.0 ghcr.io/myuser/myapp:1.0
docker login ghcr.io -u myuser
docker push ghcr.io/myuser/myapp:1.0

docker pull myuser/myapp:1.0

name: myapp

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    image: myapp-api:dev
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    env_file: .env
    volumes:
      - ./src:/app/src
    depends_on:
      db:
        condition: service_healthy
    networks:
      - backend

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: devpass
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - backend

networks:
  backend:

volumes:
  db-data:

docker compose up              # start, attached — logs in terminal
docker compose up -d           # start, detached
docker compose up --build      # rebuild images first
docker compose down            # stop and remove containers + network
docker compose down -v         # also remove named volumes — destructive
docker compose ps
docker compose logs -f api
docker compose exec api sh
docker compose restart api
docker compose build
docker compose stop / start
docker compose config          # validate & print the resolved config

services:
  api:
    volumes:
      - ./src:/app/src   # live-reload mount, dev only
    environment:
      - DEBUG=true

# stack multiple files explicitly
docker compose -f compose.yaml -f compose.prod.yaml up -d

docker compose --env-file .env.production up -d

services:
  api:
    build: .
  db:
    image: postgres:16

  pgadmin:
    image: dpage/pgadmin4
    profiles: ["debug"]

docker compose up -d                    # pgadmin is skipped
docker compose --profile debug up -d    # pgadmin included

services:
  api:
    build: .
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s

  cache:
    image: redis:7-alpine

notes-api/
├── package.json
├── src/
│   └── server.js
├── Dockerfile
├── .dockerignore
├── .env.example
├── compose.yaml
└── .github/workflows/docker.yml

{
  "name": "notes-api",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "main": "src/server.js",
  "scripts": {
    "start": "node src/server.js"
  },
  "dependencies": {
    "express": "^4.19.2",
    "pg": "^8.11.5"
  }
}

// minimal API — health check + a notes table it creates on first boot
import express from 'express';
import pg from 'pg';

const { Pool } = pg;
const app = express();
app.use(express.json());

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
await pool.query(
  'CREATE TABLE IF NOT EXISTS notes (id SERIAL PRIMARY KEY, body TEXT NOT NULL)'
);

app.get('/health', async (req, res) => {
  try {
    await pool.query('SELECT 1');
    res.json({ status: 'ok' });
  } catch (err) {
    res.status(500).json({ status: 'db unreachable' });
  }
});

app.get('/notes', async (req, res) => {
  const { rows } = await pool.query('SELECT id, body FROM notes ORDER BY id DESC');
  res.json(rows);
});

app.post('/notes', async (req, res) => {
  const { body } = req.body;
  const { rows } = await pool.query(
    'INSERT INTO notes (body) VALUES ($1) RETURNING id, body',
    [body]
  );
  res.status(201).json(rows[0]);
});

const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`notes-api listening on ${port}`));

# build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .

# runtime stage
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm install --omit=dev
COPY --from=builder /app/src ./src
EXPOSE 3000
USER node
HEALTHCHECK --interval=10s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "src/server.js"]

node_modules
.git
.env
*.log
.github

PORT=3000
DATABASE_URL=postgres://app:app@db:5432/notes
POSTGRES_USER=app
POSTGRES_PASSWORD=app
POSTGRES_DB=notes

name: notes-api

services:
  api:
    build: .
    image: notes-api:dev
    ports:
      - "3000:3000"
    env_file: .env
    depends_on:
      db:
        condition: service_healthy
    networks:
      - backend

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - backend

networks:
  backend:

volumes:
  db-data:

cp .env.example .env
docker compose up -d --build
curl http://localhost:3000/health

name: Build and Push
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

docker volume inspect app-data
docker volume ls -f dangling=true
docker volume rm app-data

# read-only bind mount
docker run -v $(pwd)/config:/etc/app:ro myapp

services:
  db:
    volumes:
      - db-data:/var/lib/postgresql/data
volumes:
  db-data:
    driver: local

docker run --rm -v app-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/app-data-backup.tar.gz -C /data .

# custom bridge network — containers on it get name-based DNS,
# unlike the default bridge
docker network create app-net
docker run -d --name db --network app-net postgres:16
docker run -d --name api --network app-net -e DB_HOST=db myapp
# 'api' now reaches 'db' by hostname, no IP needed

docker network connect app-net some-container
docker network inspect app-net

docker run --memory=512m --cpus=1.5 --restart unless-stopped myapp

services:
  api:
    image: myapp
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: "1.5"
          memory: 512M
        reservations:
          memory: 256M

services:
  api:
    image: myapp
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

docker logs -f --tail 100 mycontainer

# other drivers: local, syslog, journald, gelf, fluentd, awslogs, splunk, none
docker run --log-driver=syslog myapp

docker buildx create --name multi --use
docker buildx inspect --bootstrap

docker buildx build --platform linux/amd64,linux/arm64 \
  -t myuser/myapp:1.0 --push .

# syntax=docker/dockerfile:1
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci

docker buildx build --secret id=npmrc,src=$HOME/.npmrc -t myapp .

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci

docker swarm init
docker swarm join-token worker    # run the output on other machines

docker stack deploy -c compose.yaml mystack
docker stack services mystack
docker service scale mystack_api=4
docker stack rm mystack

# non-root user, Debian-based
RUN useradd -m appuser
USER appuser

# non-root user, Alpine-based
RUN adduser -D appuser
USER appuser

# read-only root filesystem at runtime
docker run --read-only --tmpfs /tmp myapp

# drop all capabilities, add back only what's needed
docker run --cap-drop=ALL --cap-add=NET_BIND_SERVICE myapp

docker scout cves myapp:1.0

curl -fsSL https://get.docker.com/rootless | sh

services:
  api:
    image: myapp
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

name: Build and Push
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

docker inspect <container>         # mounts, network, env, state
docker stats                        # live CPU / memory / network
docker top <container>              # processes inside it
docker diff <container>             # filesystem changes vs the image
docker events                       # live daemon event stream
docker exec -it <container> sh      # shell in — use sh if bash isn't installed

# container won't start? check exit code + last logs
docker ps -a
docker logs <container>

# debugging a container with no shell at all (distroless / scratch)
docker run -it --rm --pid=container:<container> --net=container:<container> \
  --cap-add SYS_PTRACE busybox sh

docker system df                    # what's using disk space
docker container prune              # remove stopped containers
docker image prune                  # remove dangling images
docker image prune -a                # remove all unused images
docker volume prune                  # remove unused volumes — careful
docker network prune                 # remove unused networks
docker builder prune                 # clear build cache
docker system prune -a --volumes     # everything unused