Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 3: Volumes

Ziel: Postgres als Dienst db mit einem named Volume betreiben, die Daten über down hinweg behalten, sichern und in eine leere Datenbank zurückspielen. · Dauer: ca. 75 min · Voraussetzung: Tag 2

Briefing

  • Ein named Volume gehört Docker, lebt in der Colima-VM und überlebt jeden Container. Compose nennt es <projekt>_<name>, hier notes_pgdata.
  • docker compose down lässt Volumes stehen, down -v löscht sie – samt Datenbank.
  • Postgres 18 legt seine Daten unter /var/lib/postgresql/18/docker ab. Das Volume gehört deshalb auf /var/lib/postgresql, nicht auf …/data.
  • Bind-Mount = Ordner vom Mac im Container, tmpfs = RAM, weg nach dem Neustart.
  • Ein Backup ist erst eins, wenn der Restore geklappt hat.
 Mac ~/compose-lab/tag03          Colima-VM
 ┌──────────────────────┐        ┌───────────────────────────────────────────┐
 │ backup/notes.sql   ◄─┼pg_dump─┤ notes-db-1 (Netz notes_backend)           │
 │                    ──┼─psql──►│   /var/lib/postgresql ◄── Volume          │
 └──────────────────────┘exec -T │                           notes_pgdata    │
                                 └───────────────────────────────────────────┘

Drill 1: Postgres als Dienst

Tagesstart mit dem Stand von Tag 2:

source ~/compose-lab/setup/env.sh
docker compose -p notes down
mkdir -p ~/compose-lab/tag03 && cd ~/compose-lab/tag03
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag02/notes/." .

Neu sind der Dienst db, die DB-URL für api und das Top-Level-volumes::

cat > compose.yaml <<'EOF'
# compose.yaml – Stand Ende Tag 3
name: notes

services:
  api:
    build: notes-api
    environment:
      NOTES_API_KEY: ${NOTES_API_KEY}
      NOTES_DB_URL: postgres://notes:${POSTGRES_PASSWORD}@db:5432/notes
    ports:
      - "127.0.0.1:${API_PORT:-8080}:8080"
    networks: [frontend, backend]
    depends_on:
      - db

  worker:
    build: notes-worker
    environment:
      NOTES_API_URL: http://api:8080
      NOTES_API_KEY: ${NOTES_API_KEY}
    depends_on:
      - api
    networks: [backend]

  web:
    build: notes-web
    environment:
      NOTES_API_URL: http://api:8080
      NOTES_API_KEY: ${NOTES_API_KEY}
    ports:
      - "127.0.0.1:${WEB_PORT:-3000}:3000"
    depends_on:
      - api
    networks: [frontend]

  db:
    image: postgres:18.6-alpine
    environment:
      POSTGRES_USER: notes
      POSTGRES_DB: notes
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql
    networks: [backend]

networks:
  frontend: {}
  backend:
    internal: true

volumes:
  pgdata: {}
EOF
docker compose config -q; echo "Exit: $?"

Erwartet:

Exit: 0

db hängt nur am internen backend und hat keine ports: – vom Mac aus ist Postgres nicht erreichbar, nur für api (Tag 2). Jetzt nur die Datenbank starten und warten:

docker compose up -d db
until docker compose exec db pg_isready -h 127.0.0.1 -U notes -d notes; do
  sleep 1
done
docker volume ls --filter label=com.docker.compose.project=notes

Erwartet (gekürzt, Zeiten weichen bei dir ab):

 Volume notes_pgdata Created
 Network notes_backend Created
 Container notes-db-1 Started
127.0.0.1:5432 - no response
127.0.0.1:5432 - accepting connections
DRIVER    VOLUME NAME
local     notes_pgdata

Warum -h 127.0.0.1? Beim ersten Start initialisiert Postgres zuerst mit einem temporären Server, der nur auf dem Unix-Socket lauscht. Erst der Test über TCP sagt, dass api sich verbinden kann.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Tabelle anlegen, Stack starten

Die Tabelle legt notes-api migrate an. Als Einmal-Container mit run --rm:

docker compose run --rm api migrate
docker compose up -d
sleep 3
docker compose ps --format '{{.Service}}\t{{.Status}}'
curl -s -X POST localhost:8080/notes -H 'X-API-Key: lab-api-key-123' \
  -H 'Content-Type: application/json' -d '{"text":"Tag 3 liegt im Volume"}'; echo
docker compose logs api

Erwartet (gekürzt, IDs und Zeiten weichen ab):

 Container notes-api-run-00c7ed8bac49 Created
time=… level=INFO msg="migration complete" table=notes
 Container notes-worker-1 Started
 Container notes-web-1 Started
api Up 3 seconds (healthy)
db  Up 16 seconds
web Up 3 seconds
worker  Up 3 seconds
{"id":"07acfbc9-…","text":"Tag 3 liegt im Volume"}
api-1  | time=… level=INFO msg="api key loaded" source=env
api-1  | time=… level=INFO msg="store ready" store=postgres
api-1  | time=… level=INFO msg=listening addr=:8080 version=dev pid=1

run baut das Image, falls es fehlt, startet depends_on-Dienste mit, veröffentlicht keine Ports und ersetzt das Kommando: aus /notes-api wird /notes-api migrate. migrate ist idempotent, ein zweiter Aufruf schadet nicht.

Achtung: Die Reihenfolge – erst db, warten, migrate, dann der Rest – steht bis Tag 5 nur in diesem Kapitel. Startet api, bevor Postgres Verbindungen annimmt, endet sie mit Exit 1 (database unreachable), genau wie in der Challenge von Tag 0.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Ins Volume geschaut

docker compose volumes
docker volume inspect notes_pgdata
docker compose exec db printenv PGDATA
docker compose exec db ls /var/lib/postgresql
docker compose exec db du -sh /var/lib/postgresql

Erwartet (gekürzt):

DRIVER    VOLUME NAME
local     notes_pgdata
[
    {
        "CreatedAt": "2026-10-29T21:41:20+01:00",
        "Driver": "local",
        "Labels": {
            "com.docker.compose.config-hash": "311194ae…",
            "com.docker.compose.project": "notes",
            "com.docker.compose.version": "5.6.0",
            "com.docker.compose.volume": "pgdata"
        },
        "Mountpoint": "/var/lib/docker/volumes/notes_pgdata/_data",
        "Name": "notes_pgdata",
        "Options": null,
        "Scope": "local"
    }
]
/var/lib/postgresql/18/docker
18
46.4M   /var/lib/postgresql
  • Die Labels verraten den Besitzer: Projekt notes, Volume pgdata. Daran erkennst du beim Aufräumen, was ins Labor gehört.
  • Mountpoint liegt in der Colima-VM, nicht auf dem Mac. An die Dateien kommst du nur über einen Container.
  • PGDATA zeigt in den Unterordner 18/docker. Ein einziger Mount darüber erlaubt später pg_upgrade --link von einem Versionsordner in den nächsten.

Fortschritt speichern? Kostenlos registrieren

Drill 4: down und down -v

docker compose down
docker volume ls --filter label=com.docker.compose.project=notes
docker compose up -d db
until docker compose exec db pg_isready -h 127.0.0.1 -U notes -d notes >/dev/null; do
  sleep 1
done
docker compose up -d
docker compose exec db psql -U notes -d notes -c 'SELECT text FROM notes'

Erwartet (gekürzt):

 Container notes-web-1 Removed
 Container notes-worker-1 Removed
 Container notes-api-1 Removed
 Container notes-db-1 Removed
 Network notes_frontend Removed
 Network notes_backend Removed
DRIVER    VOLUME NAME
local     notes_pgdata
 Container notes-db-1 Started
 Container notes-web-1 Started
         text
-----------------------
 Tag 3 liegt im Volume
(1 row)

Container und Netze sind weg, das Volume nicht – die Notiz ist noch da. Mit vorhandenem Volume startet Postgres in rund einer Sekunde; im Test klappte auch ein direktes docker compose up -d. Verlassen kannst du dich darauf nicht.

Befehl Container, Netze named Volumes anonyme Volumes
docker compose down entfernt bleiben bleiben
docker compose down -v entfernt gelöscht gelöscht
docker compose rm -sfv db nur db bleiben von db gelöscht

down -v benutzt du in Drill 7 – mit Backup.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Die Postgres-18-Falle

Viele Anleitungen mounten noch auf /var/lib/postgresql/data. Probier es aus:

docker compose down
sed -i.bak 's#pgdata:/var/lib/postgresql$#pgdata:/var/lib/postgresql/data#' \
  compose.yaml
grep -n 'pgdata:/' compose.yaml
docker compose up -d db
sleep 3
docker compose ps -a --format '{{.Service}}\t{{.Status}}' db
docker compose logs --no-log-prefix db | head -9

Erwartet (gekürzt):

43:      - pgdata:/var/lib/postgresql/data
 Container notes-db-1 Started
db  Exited (1) 4 seconds ago
Error: in 18+, these Docker images are configured to store database data in a
       format which is compatible with "pg_ctlcluster" (specifically, using
       major-version-specific directory names).  This better reflects how
       PostgreSQL itself works, and how upgrades are to be performed.

       See also https://github.com/docker-library/postgres/pull/1259

       Counter to that, there appears to be PostgreSQL data in:
         /var/lib/postgresql/data (unused mount/volume)

Das Image weigert sich, weil seine Daten unter /var/lib/postgresql/18/docker liegen würden – außerhalb deines Volumes. Und es gibt eine zweite Spur:

docker container inspect notes-db-1 \
  | jq -c '.[0].Mounts[] | {Type, Name, Destination}'

Erwartet (gekürzt, IDs weichen ab):

{"Type":"volume","Name":"notes_pgdata","Destination":"/var/lib/postgresql/data"}
{"Type":"volume","Name":"d3fa5ff65b66…","Destination":"/var/lib/postgresql"}

Das Image deklariert VOLUME /var/lib/postgresql. Ist dort nichts gemountet, legt Docker ein anonymes Volume an – ohne Namen, ohne Compose-Labels. Zurück zum richtigen Pfad, rm -v nimmt das anonyme Volume mit:

mv compose.yaml.bak compose.yaml
docker compose rm -sfv db
docker compose up -d db
until docker compose exec db pg_isready -h 127.0.0.1 -U notes -d notes >/dev/null; do
  sleep 1
done
docker compose up -d
sleep 3
curl -s localhost:8080/notes; echo

Erwartet (gekürzt):

Going to remove notes-db-1
 Container notes-db-1 Removed
 Container notes-db-1 Started
 Container notes-worker-1 Started
[{"id":"07acfbc9-…","text":"Tag 3 liegt im Volume"}]

Fortschritt speichern? Kostenlos registrieren

Drill 6: Backup mit pg_dump

pg_dump läuft im Container, die Ausgabe landet per Umleitung auf dem Mac:

mkdir -p backup
docker compose exec -T db pg_dump -U notes notes > backup/notes.sql
ls -l backup
grep -E 'CREATE TABLE|COPY|Tag 3|PostgreSQL database dump' backup/notes.sql
printf '# Datenbank-Backups (Tag 3)\nbackup/\n' >> .gitignore

Erwartet (gekürzt, IDs und Zeiten weichen ab):

-rw-r--r--@ 1 du  staff  1377 Oct 29 21:43 notes.sql
-- PostgreSQL database dump
CREATE TABLE public.notes (
COPY public.notes (id, text, created_at) FROM stdin;
07acfbc9-…  Tag 3 liegt im Volume   2026-10-29 20:41:37.000827+00
-- PostgreSQL database dump complete

-T schaltet das Pseudo-Terminal ab, das exec sonst anlegt. Ohne Terminal kommen die Bytes unverändert in der Datei an, und in Drill 7 kann exec von stdin lesen.

Sicherheit: Ein Dump enthält alle Daten im Klartext. Deshalb steht backup/ ab jetzt in .gitignore.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Restore in eine leere Datenbank

Jetzt mit Absicht: Volume löschen, leere Datenbank starten, Backup einspielen.

docker compose down -v
docker compose up -d db
until docker compose exec db pg_isready -h 127.0.0.1 -U notes -d notes >/dev/null; do
  sleep 1
done
docker compose exec db psql -U notes -d notes -c '\dt'
docker compose exec -T db psql -U notes -d notes -v ON_ERROR_STOP=1 \
  < backup/notes.sql
docker compose up -d
sleep 3
curl -s localhost:8080/notes; echo

Erwartet (gekürzt):

 Volume notes_pgdata Removed
 Network notes_frontend Removed
 Volume notes_pgdata Created
 Container notes-db-1 Started
Did not find any tables.
SET
…
CREATE TABLE
ALTER TABLE
COPY 1
ALTER TABLE
 Container notes-worker-1 Started
[{"id":"07acfbc9-…","text":"Tag 3 liegt im Volume"}]

Ein migrate war nicht nötig: Der Dump enthält das CREATE TABLE. ON_ERROR_STOP=1 lässt psql beim ersten Fehler mit Exit-Code 3 abbrechen, statt still weiterzulaufen.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Bind-Mount und tmpfs

Zum Vergleich hängst du db vorübergehend zwei weitere Mounts an. Sicherung zuerst:

cp compose.yaml compose.yaml.bak

Ergänze im Dienst db (Editor), danach steht dort:

    volumes:
      - pgdata:/var/lib/postgresql
      - ./backup:/backup
    tmpfs:
      - /scratch:size=16m
    networks: [backend]
docker compose up -d db
sleep 2
docker compose exec db df -h /var/lib/postgresql /backup /scratch
docker compose exec db pg_dump -U notes -f /backup/notes-bind.sql notes
ls -l backup

Erwartet (gekürzt, Größen weichen ab):

 Container notes-db-1 Recreated
 Container notes-db-1 Started
Filesystem                Size      Used Available Use% Mounted on
/dev/root                18.3G     10.3G      8.0G  56% /etc/resolv.conf
lima-a33ada9020d2b328
                        228.3G    220.3G      8.0G  97% /backup
tmpfs                    16.0M         0     16.0M   0% /scratch
total 16
-rw-r--r--  1 du  staff  1377 Oct 29 21:44 notes-bind.sql
-rw-r--r--@ 1 du  staff  1377 Oct 29 21:43 notes.sql
  • Volume: Platte der Colima-VM (/dev/root; BusyBox-df nennt den ersten Einhängepunkt dieser Platte).
  • Bind-Mount: die Mac-Freigabe von Colima (lima-…). Der Dump, im Container als root geschrieben, gehört auf dem Mac dir. Ein relativer Pfad gilt ab dem Ordner der compose.yaml – und nur unter $HOME (Tag 0).
  • tmpfs: RAM, hier auf 16 MB begrenzt.
docker compose exec db sh -c 'echo hallo > /scratch/notiz && ls /scratch'
docker compose restart db
docker compose exec db ls -A /scratch | wc -l

Erwartet:

notiz
 Container notes-db-1 Started
       0

Nach dem Neustart ist tmpfs leer – gut für Temp-Dateien und Sockets, nie für Daten. Zurück zum Stand des Tages:

mv compose.yaml.bak compose.yaml
docker compose up -d db

Erwartet:

 Container notes-db-1 Recreated
 Container notes-db-1 Started

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Das Volume hängt an /var/lib/postgresql:

cd ~/compose-lab/tag03
docker compose config --format json | jq '.services.db.volumes'

Erwartet:

[
  {
    "type": "volume",
    "source": "pgdata",
    "target": "/var/lib/postgresql",
    "volume": {}
  }
]

db veröffentlicht keinen Port, nur 5432/tcp ohne -> zum Host:

docker compose ps db --format '{{.Ports}}'

Erwartet:

5432/tcp

api speichert in Postgres:

docker compose logs api | grep -o 'store=[a-z]*'

Erwartet:

store=postgres

Notizen in der Datenbank:

docker compose exec db psql -U notes -d notes -tAc 'SELECT count(*) FROM notes'

Erwartet (Zahl kann abweichen):

1

Das Backup und sein Eintrag in .gitignore:

grep -c 'CREATE TABLE public.notes' backup/notes.sql
grep -x 'backup/' .gitignore

Erwartet:

1
backup/

Challenge

Schütze die Datenbank gegen ein versehentliches docker compose down -v: Das Volume soll notes-pgdata-keep heißen (ohne Projektpräfix), deine Notiz enthalten und down -v überleben.

Hinweis: Im Top-Level-volumes: gibt es external: true und name:; ein externes Volume legst du selbst an – mit Label lab=compose-lab, damit du es beim Aufräumen findest.

Lösung

cp compose.yaml compose.yaml.bak
docker compose down

Den Block volumes: am Dateiende ersetzen (ganze Datei: code/tag03/challenge/compose.yaml):

volumes:
  pgdata:
    external: true          # Compose legt es nicht an und löscht es nie
    name: notes-pgdata-keep # Name ohne Projektpräfix
docker compose up -d db
docker volume create --label lab=compose-lab notes-pgdata-keep
docker compose up -d db
until docker compose exec db pg_isready -h 127.0.0.1 -U notes -d notes >/dev/null; do
  sleep 1
done
docker compose exec -T db psql -q -U notes -d notes < backup/notes.sql >/dev/null
docker compose down -v
docker volume ls --filter name=notes
docker compose up -d db
sleep 3
docker compose exec db psql -U notes -d notes -tAc 'SELECT text FROM notes'

Erwartet (gekürzt):

external volume "notes-pgdata-keep" not found
notes-pgdata-keep
 Container notes-db-1 Started
 Container notes-db-1 Removed
 Network notes_backend Removed
DRIVER    VOLUME NAME
local     notes-pgdata-keep
local     notes_pgdata
 Container notes-db-1 Started
Tag 3 liegt im Volume

Der erste Start scheitert absichtlich: Compose legt externe Volumes nie selbst an. down -v entfernt nur Container und Netz. Auch notes_pgdata bleibt liegen – es steht gerade nicht mehr in der Datei, also fasst Compose es nicht an. Zurück zum Stand des Tages:

docker compose down
mv compose.yaml.bak compose.yaml
docker volume rm notes-pgdata-keep

Erwartet (gekürzt):

 Container notes-db-1 Removed
 Network notes_backend Removed
notes-pgdata-keep

Das Volume notes_pgdata mit deiner Notiz bleibt für Tag 4 stehen.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • pg_dump ist ein logisches Backup für kleine Datenbanken. Für große Datenbanken und Point-in-Time-Recovery gibt es WAL-Archivierung mit pgBackRest oder WAL-G.
  • Backups verlassen den Host, werden verschlüsselt und regelmäßig in eine leere Instanz zurückgespielt – automatisiert, mit Prüfung wie in Drill 7.
  • Der local-Treiber bindet Daten an einen Host. Netzwerk-Speicher per driver_opts (NFS) ist für Postgres riskant (Locking, Latenz); in Produktion meist eigene Platte oder eine verwaltete Datenbank.
  • Major-Upgrades (18 → 19) laufen über pg_upgrade oder Dump und Restore. Das Layout /var/lib/postgresql/<version>/docker ist genau dafür gedacht.
  • Externe Volumes sind ein Vertrag wie externe Netze (Tag 2): Wer sie anlegt, sichert und löscht, gehört dokumentiert.