Containers and Docker

   VIRTUAL MACHINES                    CONTAINERS
 ┌─────┬─────┬─────┐               ┌─────┬─────┬─────┐
 │ app │ app │ app │               │ app │ app │ app │
 ├─────┼─────┼─────┤               ├─────┴─────┴─────┤
 │ libs│ libs│ libs│               │      libs       │  (per image, small)
 ├─────┼─────┼─────┤               ├─────────────────┤
 │ OS  │ OS  │ OS  │  ← GBs each   │ container engine│
 ├─────┴─────┴─────┤               ├─────────────────┤
 │    hypervisor   │               │   host kernel   │  ← ONE kernel, shared
 ├─────────────────┤               ├─────────────────┤
 │    hardware     │               │    hardware     │
 └─────────────────┘               └─────────────────┘
   boot: 30s–2min                    start: < 1 second
   image: gigabytes                  image: tens of MB
   isolation: strongest              isolation: strong, but shared kernel

docker run hello-world                  # pull + run, prove it works
docker run -it --rm ubuntu bash         # interactive shell, deleted on exit
docker run -d -p 8080:80 --name web nginx
#          │   │            └ a name you can type instead of a hash
#          │   └ HOST port : CONTAINER port  (host side comes first)
#          └ detached: run in the background

docker ps                               # running containers
docker ps -a                            # including stopped ones
docker logs -f web                      # follow its output
docker exec -it web sh                  # get a shell INSIDE a running container
docker stop web && docker rm web        # SIGTERM, then remove
docker images                           # what is on disk
docker stats                            # live CPU/memory per container
docker system df                        # where has my disk gone?
docker system prune -a                  # reclaim it (careful: removes unused images)

FROM node:20-alpine                 # small, pinned base. never :latest

# a non-root user: if the app is compromised, it is not root
RUN addgroup -S app && adduser -S app -G app

WORKDIR /app

# dependencies FIRST — this is the cache trick, see next topic
COPY package*.json ./
RUN npm ci --omit=dev

# then the source, which changes on every commit
COPY --chown=app:app . .

ENV NODE_ENV=production
ENV PORT=3000
EXPOSE 3000                         # documentation; does not publish anything

USER app                            # drop privileges before running

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
  CMD wget -qO- http://localhost:3000/health || exit 1

CMD ["node", "server.js"]           # exec form: your app becomes PID 1 and
                                    # receives SIGTERM directly (chapter 02)

node_modules
.git
.env
*.log
dist
coverage
Dockerfile
README.md

# ✗ SLOW — source copied before install
COPY . .                 # any code change invalidates this layer…
RUN npm ci               # …so dependencies reinstall every single time (~90s)

# ✓ FAST — manifest first
COPY package*.json ./    # changes only when dependencies change
RUN npm ci               # CACHED on almost every build
COPY . .                 # cheap layer, changes constantly

docker build -t notes-api:v1 .
=> [2/5] COPY package*.json ./     CACHED
=> [3/5] RUN npm ci                CACHED   ← 90s saved
=> [4/5] COPY . .                  0.2s

docker build --no-cache -t notes-api:v1 .   # force a cold build to compare
docker history notes-api:v1                 # size of every layer — find the fat

# ---------- stage 1: build ----------
FROM node:20 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci                      # includes devDependencies
COPY . .
RUN npm run build               # produces /app/dist

# ---------- stage 2: run ----------
FROM node:20-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=build /app/dist ./dist    # ONLY the built output crosses over
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

# named volume: Docker manages it, ideal for databases
docker volume create pgdata
docker run -d --name db -v pgdata:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret postgres:16

# bind mount: a host folder, ideal for local development
docker run -d -p 3000:3000 -v "$PWD:/app" -w /app node:20 npm run dev
# ↑ edit files on your laptop, the container sees them instantly

docker volume ls
docker volume inspect pgdata
docker volume rm pgdata          # this deletes the data. no undo.

docker network create appnet
docker run -d --name db --network appnet -e POSTGRES_PASSWORD=secret postgres:16
docker run -d --name api --network appnet -p 3000:3000 \
  -e DATABASE_URL=postgres://postgres:secret@db:5432/postgres notes-api:v1
#                                                    ↑ "db" is the container name

docker exec -it api sh -c 'nc -zv db 5432'     # prove they can talk
docker network inspect appnet

services:
  api:
    build: .                       # build from the Dockerfile here
    ports: ["3000:3000"]
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/app
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy  # wait for READY, not just "started"
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10

  cache:
    image: redis:7-alpine

volumes:
  pgdata:

docker compose up -d            # build if needed, start everything
docker compose ps
docker compose logs -f api      # logs of one service
docker compose exec api sh
docker compose down             # stop and remove containers + network
docker compose down -v          # …and delete the volumes (data gone)
docker compose up -d --build    # rebuild after changing the Dockerfile

docker login ghcr.io -u YOUR_USER --password-stdin < token.txt
docker build -t ghcr.io/your-user/notes-api:a91f3c .
docker push ghcr.io/your-user/notes-api:a91f3c
docker pull ghcr.io/your-user/notes-api:a91f3c

# tag the same image twice: an immutable SHA tag plus a moving one
docker tag ghcr.io/your-user/notes-api:a91f3c ghcr.io/your-user/notes-api:v2

docker ps -a                    # status + exit code. 0 = clean exit,
                                # 137 = SIGKILL/OOM, 1 = app error
docker logs --tail 100 api      # what did it say before dying?
docker inspect api | less       # the full truth: env, mounts, network, cmd
docker exec -it api sh          # poke around inside (if it is still running)

# it exits instantly and you cannot exec in: override the entrypoint
docker run -it --rm --entrypoint sh notes-api:v1
# then run your CMD by hand and read the real error

docker stats api                # is it being throttled or starved?
docker diff api                 # what has it written to its writable layer?