Tag 3: Volumes
Ziel: Postgres als Dienst
dbmit einem named Volume betreiben, die Daten überdownhinweg 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>, hiernotes_pgdata. docker compose downlässt Volumes stehen,down -vlöscht sie – samt Datenbank.- Postgres 18 legt seine Daten unter
/var/lib/postgresql/18/dockerab. 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=notesErwartet (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 apiErwartet (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/postgresqlErwartet (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, Volumepgdata. Daran erkennst du beim Aufräumen, was ins Labor gehört. Mountpointliegt in der Colima-VM, nicht auf dem Mac. An die Dateien kommst du nur über einen Container.PGDATAzeigt in den Unterordner18/docker. Ein einziger Mount darüber erlaubt späterpg_upgrade --linkvon 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 -9Erwartet (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; echoErwartet (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' >> .gitignoreErwartet (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; echoErwartet (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.bakErgä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 backupErwartet (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-dfnennt 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 dercompose.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 -lErwartet:
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 dbErwartet:
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/' .gitignoreErwartet:
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 downDen 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äfixdocker 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-keepErwartet (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_dumpist 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 perdriver_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_upgradeoder Dump und Restore. Das Layout/var/lib/postgresql/<version>/dockerist genau dafür gedacht. - Externe Volumes sind ein Vertrag wie externe Netze (Tag 2): Wer sie anlegt, sichert und löscht, gehört dokumentiert.