Linux commando: docker

Iemand geeft je een project en zegt "draai het gewoon in Docker". Tien minuten later heb je een container die start en meteen weer stopt, een poort die wel antwoordt op je laptop maar niet vanaf het netwerk, en een map vol bestanden van root die je niet kunt verwijderen. Dat is niet Docker die moeilijk doet. Dat is Docker die precies is wat hij is: een heel dunne schil om een handvol Linux-kernelfuncties heen, met een vriendelijke opdrachtregel eromheen. Zodra je ziet wat eronder zit, houden de verrassingen op.

2. Waar komt de naam vandaan?

Een docker is een havenarbeider: degene op de kade die schepen laadt en lost. De naam is gekozen om de metafoor waar de hele industrie nu op draait.

Voor de jaren vijftig werd lading stuk voor stuk geladen, en elk schip, elke trein en elke vrachtwagen had zijn eigen afhandeling nodig. De intermodale zeecontainer loste dat op door de doos te standaardiseren in plaats van de inhoud. Niemand in de haven hoeft te weten of er bananen of fietsen in een container zitten. De kraan, het schip en de vrachtwagen behandelen allemaal dezelfde standaarddoos op dezelfde standaardmanier.

Software had hetzelfde probleem. Een Python-applicatie, een PHP-applicatie en een Go-binary hadden elk hun eigen uitrolprocedure nodig, hun eigen afhankelijkheden, hun eigen "het werkt op mijn machine"-discussie. Een container-image standaardiseert de doos: wat er ook in zit, de runtime start het op dezelfde manier.

De walvis in het logo heet Moby Dock, een woordgrap op Moby Dick van Herman Melville, en de community koos die naam in een stemming in 2013. In 2017 verplaatste Docker de opensource-engine naar een project met de naam Moby, en hield "Docker" voor de producten die het bedrijf verkoopt. Daarom staat de broncode op GitHub onder moby/moby, en heet de build-engine moby/buildkit.

De rest van het vocabulaire kun je het beste in een keer leren, want elke foutmelding gebruikt het:

image        a read-only stack of filesystem layers plus configuration
layer        one filesystem change set; images are made of these, stacked
container    a process started from an image, with a writable layer on top
registry     a server that stores images (Docker Hub is the default)
repository   one named collection of images in a registry, e.g. "nginx"
tag          a label on one image inside a repository, e.g. "1.27-alpine"
digest       the sha256 hash of an image; unlike a tag, it never moves
volume       Docker-managed storage that outlives the container
bind mount   a host directory pushed into the container at a chosen path
Dockerfile   the recipe used to build an image
context      the directory sent to the builder when you run docker build
ENTRYPOINT   the program a container runs
CMD          the default arguments (or the default program, if no ENTRYPOINT)

Twee daarvan zijn nu al het benoemen waard. Een tag is geen versie, het is een verschuifbaar label, en paragraaf 7 laat zien hoe dat bijt. Een volume is geen bind mount, en paragraaf 5.1 laat zien waarom ze zich anders gedragen op een manier die iedereen precies een keer overkomt.

4. Eenvoudige toepassingen

4.1 Iets draaien en weggooien

De meest onderbenutte Docker-functie is een programma draaien dat je niet geïnstalleerd hebt. Twee opties maken dat prettig:

$ docker run --rm -it alpine:3.20 sh
/ # cat /etc/alpine-release
3.20.10
/ # exit                           # container is gone, nothing left behind

Je wilt bijna altijd -it samen, en daarom typen mensen -it zonder erover na te denken. Gebruik ze als je verwacht te communiceren; laat ze weg in scripts en cronjobs, waar geen terminal is om aan te koppelen.

Dit is een echt nuttige gewoonte. Wil je een DNS-vraag testen met een programma dat je niet geïnstalleerd hebt? Heb je tien seconden PHP 7.4 nodig om iets te controleren? Draai het, gebruik het, en het verdwijnt:

$ docker run --rm alpine:3.20 nslookup petermartin.nl
$ docker run --rm -v "$PWD:/app" -w /app php:7.4-cli php -l index.php

4.2 Iets op de achtergrond draaien

Voor alles wat moet blijven draaien gebruik je -d (afkorting van detached) en geef je het een naam:

$ docker run -d --name web -p 8080:80 nginx:latest
c4f1d0a9b0e2f3a7c1d8e9b2a4f6c8d0e1a3b5c7d9e1f3a5b7c9d1e3f5a7b9c1

Die lange tekenreeks is de container-ID. Je hebt hem bijna nooit nodig, omdat je de container een naam gaf. Geef je containers altijd een naam. Docker verzint er anders zelf een, en hoewel elegant_hopper de eerste keer charmant is, heb je er in een script niets aan.

4.3 Zien wat er draait

$ docker ps                        # running containers only
CONTAINER ID   IMAGE          STATUS         PORTS                    NAMES
c4f1d0a9b0e2   nginx:latest   Up 2 minutes   0.0.0.0:8080->80/tcp     web

$ docker ps -a                     # -a for all: includes stopped ones
$ docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

Draai docker ps -a op een machine die al een tijdje in gebruik is en het resultaat is vaak een schok:

$ docker ps -a --format '{{.Status}}' | grep -c Exited
121

Die 121 gestopte containers draaien niet, maar elk bezit nog steeds zijn schrijfbare laag op schijf. Paragraaf 6.9 gaat daarover.

4.4 De logs lezen

docker logs laat zien wat het hoofdproces van de container naar standaarduitvoer en standaardfout schreef:

$ docker logs web                  # everything so far
$ docker logs -f web               # -f for follow, like tail -f
$ docker logs --tail 50 web        # the last 50 lines
$ docker logs --since 10m web      # only the last ten minutes
$ docker logs -t web               # -t adds timestamps

De belangrijke beperking is makkelijk te missen. Docker vangt alleen de standaarduitvoer en standaardfout van PID 1 op. Alles wat de applicatie naar een logbestand in de container schrijft, is onzichtbaar voor docker logs:

$ docker run -d --name l1 alpine:3.20 sh -c \
    'echo to-stdout; echo to-stderr >&2; echo to-file > /tmp/f.log; sleep 60'

$ docker logs l1
to-stdout
to-stderr                          # both streams appear

$ docker exec l1 cat /tmp/f.log
to-file                            # this never reaches docker logs

Daarom loggen nette container-images naar standaarduitvoer in plaats van naar een bestand. Als je een applicatie in een container zet die per se /var/log/app.log wil schrijven, is de gebruikelijke truc om dat bestand te symlinken naar /dev/stdout. De officiele nginx-image doet precies dat.

4.5 Een shell in een draaiende container

docker exec start een extra proces in een container die al draait:

$ docker exec -it web bash         # a shell, for poking around
$ docker exec web nginx -t         # one command, no terminal needed
$ docker exec -u root -it web sh   # as root, if the image runs as someone else

Twee dingen gaan hier regelmatig mis. Als de image op Alpine gebaseerd is, is er geen bash, alleen sh. En exec werkt alleen op een draaiende container: als de container steeds stopt, is er niets om in te exec-en, en heb je docker logs nodig. Om een kapotte image te bekijken zonder het normale commando te starten, overschrijf je dat:

$ docker run --rm -it --entrypoint sh myimage:latest

4.6 Stoppen, starten, verwijderen

$ docker stop web                  # polite: SIGTERM, then SIGKILL after 10s
$ docker start web                 # start it again, writable layer intact
$ docker restart web
$ docker kill web                  # immediate SIGKILL, no grace period
$ docker rm web                    # delete the container (must be stopped)
$ docker rm -f web                 # stop and delete in one step

Houd stop en rm uit elkaar in je hoofd. stop pauzeert het verhaal: de schrijfbare laag van de container is er nog en docker start pakt de draad op. rm beeindigt het: de schrijfbare laag wordt verwijderd en alles wat de container buiten een volume schreef is voorgoed weg.

De tien seconden in die eerste regel zijn niet willekeurig, en paragraaf 7.2 legt uit waarom bijna elke container die je stopt de volle tien nodig heeft.

4.7 Een poort publiceren

Het netwerk van een container is privé. Een webserver die binnen een container op poort 80 luistert, is niet bereikbaar vanuit je browser tot je de poort publiceert met -p:

$ docker run -d --name web -p 8080:80 nginx:latest
                              ^^^^ ^^
                              host container

De volgorde is eerst de host, dan de container, en die omdraaien is een inwijdingsrite. Controleer wat er echt gebeurd is:

$ docker ps --format 'table {{.Names}}\t{{.Ports}}'
NAMES     PORTS
web       0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/
200

Kijk goed naar 0.0.0.0. Dat betekent elke netwerkinterface, dus iedereen die je machine kan bereiken, kan die container bereiken. Op een laptop op een gedeeld netwerk, of op een server met een publiek IP-adres, is dat meestal niet wat je bedoelde. Je kunt in plaats daarvan aan een adres binden:

$ docker run -d --name web -p 127.0.0.1:8080:80 nginx:latest

$ docker ps --format 'table {{.Names}}\t{{.Ports}}'
NAMES     PORTS
web       127.0.0.1:8080->80/tcp     # localhost only

$ ss -tln | grep 8080
LISTEN 0  4096  127.0.0.1:8080  0.0.0.0:*

Maak 127.0.0.1: je standaard voor alles waar een reverse proxy voor komt te staan. Paragraaf 7.7 legt uit waarom dit meer uitmaakt dan je zou verwachten.

6. Gevorderde toepassingen

6.1 Lagen en de buildcache

Elke RUN, COPY en ADD in een Dockerfile maakt een laag, en docker history laat je de stapel zien:

$ docker history myapp:1
IMAGE          CREATED BY                                      SIZE
a07370c4d5e3   CMD ["cat" "/app/app.txt"]                      0B
<missing>      COPY app.txt /app/app.txt # buildkit            10B
<missing>      RUN /bin/sh -c apk add --no-cache curl          5.41MB
<missing>      CMD ["/bin/sh"]                                 0B
<missing>      ADD alpine-minirootfs-3.20.10-x86_64.tar.gz /   7.81MB

Docker hergebruikt een laag als de instructie en de invoer daarvan niet veranderd zijn. Zodra een laag verandert, moet elke laag daarna opnieuw gebouwd worden. Die ene regel bepaalt de volgorde van je Dockerfile:

$ echo "version 2" > app.txt       # change one file
$ docker build -t myapp:2 .
 => [1/3] FROM docker.io/library/alpine:3.20        DONE
 => [2/3] RUN apk add --no-cache curl               CACHED
 => [3/3] COPY app.txt /app/app.txt                 DONE

De dure apk add kwam uit de cache, omdat er niets boven veranderd was. Stel je nu voor dat de COPY eerst kwam: de pakketinstallatie zou bij elke codewijziging opnieuw draaien. Daarom kopieert de Dockerfile in paragraaf 5.4 eerst composer.json en composer.lock apart, installeert de afhankelijkheden, en kopieert pas daarna de applicatie. Afhankelijkheden veranderen zelden, code voortdurend, dus de trage stap hoort boven de snelle.

De tweede laagregel is degene die raadselachtig enorme images oplevert. Een latere laag kan een eerdere laag niet kleiner maken. Een bestand verwijderen legt alleen een verwijdering vast in de nieuwe laag; de bytes staan nog in de laag eronder:

# Dockerfile.bad: two instructions, two layers
FROM alpine:3.20
RUN dd if=/dev/zero of=/big.bin bs=1M count=100
RUN rm /big.bin

# Dockerfile.good: one instruction, one layer
FROM alpine:3.20
RUN dd if=/dev/zero of=/big.bin bs=1M count=100 && rm /big.bin

$ docker images
layerdemo:bad     113MB
layerdemo:good    7.81MB             # same result, no /big.bin in either

$ docker history layerdemo:bad --format 'table {{.CreatedBy}}\t{{.Size}}'
RUN /bin/sh -c rm /big.bin                      0B      <- the deletion
RUN /bin/sh -c dd if=/dev/zero of=/big.bin ...  105MB   <- still there

Beide images hebben geen /big.bin. Een ervan is vijftien keer groter. Keten het opruimen in dezelfde RUN met &&, en gebruik apt-get clean && rm -rf /var/lib/apt/lists/* of apk add --no-cache in dezelfde instructie die de pakketten installeerde.

6.2 De buildcontext en .dockerignore

Als je docker build . draait, is die punt een map die wordt ingepakt en aan de build-engine gegeven voordat de Dockerfile ook maar gelezen is. Als je project node_modules, een .git-geschiedenis en een map met klantfoto's bevat, wordt dat allemaal meegestuurd, elke keer.

Een .dockerignore-bestand, met dezelfde syntaxis als .gitignore, houdt het buiten:

.git
node_modules
vendor
*.log
*.sql
.env
tmp/
cache/

Het effect is direct, en het geldt ook voor de image, want COPY . /app kan alleen kopieren wat verstuurd is:

$ docker images
ctxdemo:a    91.7MB      # no .dockerignore
ctxdemo:b    7.81MB      # with node_modules excluded

Zet .env op de eerste dag in dat bestand. Een hele projectmap in een image kopieren is de meest voorkomende manier waarop inloggegevens in een registry gepubliceerd worden.

6.3 Multi-stage builds

De meeste applicaties hebben de ene set gereedschappen nodig om te bouwen en een compleet andere, veel kleinere set om te draaien. Een compiler, een pakketbeheerder en een testsuite horen niet thuis in een productie-image. Met multi-stage builds kun je ze gebruiken en daarna achterlaten:

FROM alpine:3.20 AS build              # stage 1: everything you need to build
RUN apk add --no-cache build-base
COPY hello.c /src/hello.c
RUN gcc -static -o /hello /src/hello.c

FROM alpine:3.20                       # stage 2: a clean image
COPY --from=build /hello /usr/local/bin/hello
CMD ["hello"]

Alleen de laatste stage wordt de image. Alles in build wordt weggegooid zodra de uitvoer eruit gekopieerd is:

$ docker images
multidemo:single    230MB              # compiler included
multidemo:multi     7.88MB             # just the binary

$ docker run --rm multidemo:multi
hello

Hetzelfde patroon werkt voor elke stack: node om de bundler te draaien en nginx om het resultaat te serveren, composer om afhankelijkheden op te lossen en php-fpm om ze te draaien, golang om te compileren en scratch om de binary te bewaren. Kleinere images halen sneller binnen, starten sneller, en bevatten veel minder waarin een scanner een CVE kan vinden.

6.4 Draaien als niet-rootgebruiker

Containers draaien als root tenzij je iets anders zegt. Omdat er standaard geen user namespace is, is die root de root van de host met een hoedje op.

Los het op in de image, zodat niemand een optie hoeft te onthouden:

FROM node:22-alpine
WORKDIR /app
COPY --chown=node:node . .
RUN npm ci --omit=dev
USER node                          # everything after this runs as node
CMD ["node", "server.js"]

Of tijdens het draaien, wat de juiste aanpak is voor een ontwikkelopstelling met een bind mount:

$ docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/app" -w /app \
    node:22-alpine npm install

Voeg de andere standaard hardeningsopties toe zodra je je er prettig bij voelt:

$ docker run -d \
    --user 1000:1000 \
    --read-only \                  # the container filesystem is immutable
    --tmpfs /tmp \                 # ... except for a RAM-backed /tmp
    --cap-drop ALL \               # remove every Linux capability
    --security-opt no-new-privileges \
    myapp:1.0

Voor een echt rootloze opstelling kijk je naar Docker's rootless mode, waarbij de daemon zelf als een gewone gebruiker draait, of naar Podman, dat van nature zonder daemon en zonder root werkt.

6.5 Capabilities, seccomp en de valdeur --privileged

Paragraaf 6.4 gebruikte --cap-drop ALL en --security-opt zonder te zeggen waarop die inwerken. Er zijn drie aparte kernelmechanismen bij betrokken, en Docker past er al twee voor je toe.

Capabilities splitsen het oude alles-of-niets-rootrecht op in losse bevoegdheden: een lage poort openen, bestandseigendom wijzigen, een kernelmodule laden, enzovoort. Root in een container is geen volledige root, want Docker houdt er maar veertien van de eenenveertig over:

$ docker run --rm alpine:latest grep CapEff /proc/self/status
CapEff: 00000000a80425fb           # 14 capabilities

$ docker run --rm alpine:latest sh -c 'apk add -q libcap; capsh --print | head -1'
Current: cap_chown,cap_dac_override,cap_fowner,cap_fsetid,cap_kill,cap_setgid,
cap_setuid,cap_setpcap,cap_net_bind_service,cap_net_raw,cap_sys_chroot,
cap_mknod,cap_audit_write,cap_setfcap=ep

$ docker run --rm --cap-drop ALL alpine:latest grep CapEff /proc/self/status
CapEff: 0000000000000000           # none at all

Seccomp filtert welke systeemaanroepen het proces uberhaupt mag doen. Docker past een standaardprofiel toe dat de gevaarlijke blokkeert, en je kunt zien dat het filter actief is:

$ docker run --rm alpine:latest grep Seccomp: /proc/self/status
Seccomp:        2                  # 2 = a filter is loaded

$ docker run --rm alpine:latest mount -t tmpfs none /mnt
mount: permission denied (are you root?)      # it IS root; the filter said no

AppArmor (of SELinux op Red Hat-systemen) legt daar bovenop een verplicht toegangsprofiel, dat beperkt welke bestanden en interfaces het proces mag aanraken, ongeacht zijn gebruikers-ID:

$ docker run --rm alpine:latest cat /proc/self/attr/current
docker-default (enforce)

Alle drie staan standaard aan, en dat is voor een groot deel waarom een container veiliger is dan dezelfde binary als root op de host draaien. Kijk nu wat een enkele optie ermee doet:

$ docker run --rm --privileged alpine:latest grep CapEff /proc/self/status
CapEff: 000001ffffffffff           # all 41 capabilities

$ docker run --rm --privileged alpine:latest grep Seccomp: /proc/self/status
Seccomp:        0                  # the filter is GONE

$ docker run --rm --privileged alpine:latest sh -c 'mount -t tmpfs none /mnt && echo OK'
OK                                 # the call that was refused now works

--privileged geeft niet simpelweg "wat extra rechten". Het geeft elke capability terug en zet seccomp stilletjes uit, en het stelt de apparaten van de host bloot:

$ docker run --rm alpine:latest sh -c 'ls /dev | wc -l'
15                                 # a safe, minimal set

$ docker run --rm --privileged alpine:latest sh -c 'ls /dev | wc -l'
293

$ docker run --rm --privileged alpine:latest ls /dev/ | grep nvme
nvme0
nvme0n1
nvme0n1p1                          # the host's raw disk partitions

Een privileged container kan de schijven van de host rechtstreeks lezen en schrijven, wat de bestandsrechten daarop ook zeggen. Het is in geen enkele betekenisvolle zin een beveiligde container; het is een rootshell met extra stappen. Mensen grijpen ernaar omdat iets faalde met "operation not permitted" en --privileged die fout laat verdwijnen. Bijna altijd is de juiste oplossing een enkele capability:

$ docker run --cap-add NET_ADMIN ...          # manage interfaces and routes
$ docker run --cap-add SYS_PTRACE ...         # run a debugger inside
$ docker run --device /dev/ttyUSB0 ...        # one device, not all of them

Zoek uit welke capability je werkelijk nodig hebt, voeg die ene toe, en laat de andere veertig met rust. Bewaar --privileged voor de echte gevallen, zoals Docker-in-Docker in een CI-runner, en behandel het zoals je het uitdelen van het rootwachtwoord zou behandelen.

6.6 Healthchecks

"Draaien" en "werken" zijn verschillende dingen. Een container waarvan de applicatie vastgelopen is, draait nog prima. Een healthcheck vraagt het aan de applicatie zelf:

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

$ docker ps --format 'table {{.Names}}\t{{.Status}}'
NAMES          STATUS
comp-web-1     Up 8 seconds (healthy)

$ docker inspect -f '{{.State.Health.Status}}' comp-web-1
healthy

--start-period is de optie die mensen vergeten. Zonder die optie wordt een database die veertig seconden nodig heeft om op te komen als ongezond gemarkeerd, lang voordat hij een kans gehad heeft. Fouten tijdens de startperiode tellen niet mee voor het aantal pogingen.

Healthchecks verdienen zichzelf terug in Compose, waar een andere service kan wachten op een echte gereedstatus in plaats van op een gok:

depends_on:
  db:
    condition: service_healthy     # not just "started"

Een kale depends_on: [db] wacht alleen tot de container gestart is, wat voor een database ongeveer het moment is waarop hij aan zijn eigen opstartwerk begint. Dat is de oorzaak van de meeste meldingen van "connection refused bij de eerste start, daarna prima".

6.7 Resourcelimieten

Standaard mag een container elke kern en al het geheugen op de machine gebruiken, wat betekent dat een op hol geslagen proces al het andere op de server kan platleggen:

$ docker run -d --memory=512m --cpus=1.5 --pids-limit=200 myapp:1.0

Dit zijn cgroup-instellingen, en je kunt ze vanuit de container lezen:

$ docker run --rm --memory=64m alpine:3.20 cat /sys/fs/cgroup/memory.max
67108864                           # 64 MB, in bytes

$ docker run --rm alpine:3.20 cat /sys/fs/cgroup/memory.max
max                                # no limit at all

$ docker run --rm --cpus=1.5 alpine:3.20 cat /sys/fs/cgroup/cpu.max
150000 100000                      # 150ms of CPU per 100ms period

Deze bestanden zijn cgroup v2, de verenigde hiërarchie die elke huidige distributie gebruikt. Op een oudere host zou je in plaats daarvan een boom van mappen per controller vinden, zoals /sys/fs/cgroup/memory/. Controleer welke je hebt met docker info | grep "Cgroup Version".

Volg het verbruik live met docker stats. Als een container zijn geheugenlimiet wel raakt, maakt de OOM-killer van de kernel er een einde aan, en het resultaat ziet er zo uit:

$ docker run -d --name oomtest --memory=32m --memory-swap=32m alpine:latest \
      sh -c 'tail /dev/zero'       # allocate until it cannot

$ docker inspect -f 'exit={{.State.ExitCode}} oomkilled={{.State.OOMKilled}}' oomtest
exit=137 oomkilled=true

Vergelijk dat nu met de afsluitcode uit paragraaf 7.2, waar een container die simpelweg SIGTERM negeerde na de respijtperiode van tien seconden gedood werd:

exit=137 oomkilled=false           # SIGKILLed by docker stop
exit=137 oomkilled=true            # SIGKILLed by the kernel, out of memory

Afsluitcode 137 alleen kan je niet vertellen welk van beide gebeurde. Het betekent enkel "gedood door signaal 9", en beide oorzaken eindigen zo. Het veld OOMKilled is het onderscheid, en het is het eerste om te controleren als een container verdwijnt zonder applicatiefout in zijn logs. De kant van de host staat in dmesg of journalctl -k, waar de kernel vastlegt welk proces hij koos en waarom. Een container die onder belasting stilletjes verdwijnt is meestal helemaal niet gecrasht; hij is neergeschoten.

6.8 Waar de logs echt terechtkomen

De standaard logdriver schrijft JSON naar een bestand op de host, een bestand per container:

$ docker inspect -f '{{.LogPath}}' web
/var/lib/docker/containers/ca3b0f8b.../ca3b0f8b...-json.log

$ docker inspect -f '{{json .HostConfig.LogConfig}}' web
{"Type":"json-file","Config":{}}

Kijk naar die lege Config. Er is geen groottelimiet en geen rotatie. Een spraakzame applicatie op een langdraaiende container vult de schijf, en omdat het bestand onder /var/lib/docker staat in plaats van onder /var/log, raakt normale logrotatie het nooit aan. Begrens het:

$ docker run -d --log-opt max-size=10m --log-opt max-file=3 myapp:1.0

Beter nog: stel het een keer in voor de hele machine in /etc/docker/daemon.json en herstart de daemon:

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" }
}

Er zijn andere drivers om logs elders heen te sturen: journald zet containeruitvoer in het systemd-journaal zodat journalctl het kan lezen, syslog stuurt door naar een logserver, en none gooit het weg voor containers waarvan je de uitvoer nooit wilt.

6.9 Opruimen

Docker verwijdert nooit uit zichzelf iets. Gestopte containers, losse images, ongebruikte volumes en buildcache stapelen zich stilletjes op tot een uitrol om twee uur 's nachts faalt met "no space left on device". Vraag wat hij vasthoudt:

$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          276       76        130.1GB   76.81GB (59%)
Containers      124       2         1.925GB   1.925GB (99%)
Local Volumes   60        7         73.07GB   72.25GB (98%)
Build Cache     1452      0         14.08GB   14.08GB

Dat is een echte ontwikkelmachine, en die houdt ruim 160 GB vast die hij niet nodig heeft. De commando's, van veiligst naar meest destructief:

$ docker container prune           # remove all stopped containers
$ docker image prune               # remove dangling (untagged) images
$ docker builder prune             # remove build cache
$ docker system prune              # all of the above, in one go
$ docker system prune -a           # ... plus every image not used by a
                                   #     running container. Re-pull time.
$ docker volume prune              # DANGEROUS: this is your data
$ docker system df -v              # itemised, before you decide

Leer het verschil tussen prune en prune -a voordat je een van beide op een server typt. Een kale prune verwijdert ongetagde restanten. Met -a gaat elke image zonder draaiende container weg, inclusief die welke je gestopte diensten nodig hebben om weer te starten.

En behandel docker volume prune als een aparte categorie. Al het andere kost je downloadtijd. Die ene kost je data. Het is ook waarom docker system prune volumes bewust met rust laat tenzij je --volumes toevoegt.

8. Best practices

• Zet je basisimages vast. FROM php:8.3-fpm-alpine, nooit FROM php. Voor alles wat je uitrolt zet je ook de digest vast, zodat de image niet onder je vandaan kan veranderen tussen twee servers.
• Rol nooit latest uit. Tag met een versie, een datum of een commit-hash. Als er om twee uur 's nachts iets stukgaat moet je weten wat er draait, en latest kan je dat niet vertellen.
• Orden de Dockerfile van minst naar meest waarschijnlijk om te veranderen. Basisimage, systeempakketten, afhankelijkheidsbestanden, installatie van afhankelijkheden, en dan pas de applicatiecode. Elke minuut buildtijd die je bespaart, bespaar je bij elke commit.
• Keten het opruimen in dezelfde RUN. apk add --no-cache, of apt-get install && apt-get clean && rm -rf /var/lib/apt/lists/*. Een aparte RUN rm verwijdert niets uit de image.
• Schrijf een .dockerignore voor je eerste build. Begin met .git, node_modules, vendor, *.log, *.sql en .env.
• Gebruik multi-stage builds. Compilers, testsuites en pakketbeheerders horen in de buildstage, niet in de image die je uitlevert.
• Zet USER in elke Dockerfile. Root is de standaard, en zonder user namespace is die root de root van de host.
• Een zorg per container. Niet "een proces", dat is te streng, maar stop nginx, PHP-FPM en MariaDB niet in een image. Aparte containers schalen, herstarten en worden onafhankelijk vervangen.
• Log naar standaarduitvoer. Dat is wat docker logs, Compose en elke logverzamelaar lezen. Begrens het log met max-size en max-file, bij voorkeur een keer in /etc/docker/daemon.json.
• Zet blijvende data in een named volume, en maak een backup van dat volume. Een container is per ontwerp wegwerpbaar; de data erin mag dat niet zijn.
• Bind gepubliceerde poorten aan 127.0.0.1 tenzij de wereld ze echt nodig heeft. Docker's eigen firewallregels gaan voor die van ufw, dus het adres waaraan je bindt is de echte knop.
• Handel SIGTERM af, of voeg --init toe. Anders duurt elke stop tien seconden en eindigt hij in SIGKILL, wat voor een database een vuile afsluiting betekent.
• Stel een healthcheck in met een start_period, en laat services afhangen van service_healthy in plaats van van een container die enkel gestart is.
• Stel geheugen- en CPU-limieten in op een gedeelde server. Zonder die limieten kan een container al het andere op de machine uithongeren.
• Grijp nooit naar --privileged om een fout te laten verdwijnen. Het geeft elke capability terug en zet seccomp uit. Zoek de ene capability die je nodig hebt en voeg die toe, of geef het enkele --device mee dat je nodig hebt.
• Houd geheimen uit images. Niet met ENV, niet met --build-arg. Gebruik BuildKit secret mounts tijdens de build en een omgevingsbestand of Compose secrets tijdens het draaien.
• Gebruik Compose zodra je twee containers hebt. Het bestand is documentatie, versiebeheer en een herhaalbare opstelling tegelijk.
• Ruim op volgens een schema, niet in paniek. Een wekelijkse docker system prune -f en docker builder prune -f is prima. Bewaar -a en --volumes voor beslissingen die je bewust neemt.
• Lees de documentatie van het ding dat je gaat typen.

$ docker --help                    # top-level command list
$ docker run --help                # the long one; worth reading once
$ docker compose --help
$ man docker-run                   # if the man pages package is installed
$ docker system df -v              # what is actually on this disk
$ docker inspect <name>            # everything Docker knows about it

De online documentatie op docs.docker.com voor de Dockerfile-instructies en het Compose-bestandsformaat zijn de twee pagina's om te bookmarken. Beide veranderen vaker dan een manpagina.

10. Samenvatting

Docker is een dunne, goed ontworpen laag over kernelfuncties die al bestonden. Alles wat er vreemd aan voelt wordt logisch zodra je accepteert dat een container een proces is en geen machine.

• Een container is een Linux-proces, dat via namespaces een privé-beeld van het systeem krijgt en via cgroups een budget. Het deelt jouw kernel; ps op de host ziet het.
• Een image is een alleen-lezen stapel lagen plus configuratie. Een container is een instantie daarvan met een dunne schrijfbare laag. Een registry bewaart images.
• Het commando docker is alleen een client. De daemon doet het werk, via /var/run/docker.sock, als root. Lidmaatschap van de groep docker is daarom roottoegang.
• De naam komt van havenarbeiders, en de metafoor is de zeecontainer: standaardiseer de doos, niet de inhoud. De walvis heet Moby Dock.
• Docker heeft containers niet uitgevonden. Het maakte kernelfuncties uit 2008 bruikbaar in een commando, en de OCI-standaard die het startte zorgt dat je image ook onder Podman, containerd en Kubernetes draait.
• Leer zes commando's en je kunt werken: run, ps, logs, exec, stop, rm. Gebruik --rm -it voor wegwerpwerk en -d --name voor alles wat blijft.
• docker logs laat alleen zien wat PID 1 naar stdout en stderr schreef. Een logbestand in de container is er onzichtbaar voor.
• Bewaar data in een named volume. Een bind mount is voor broncode en configuratie, hij verbergt wat de image op dat pad had, en de bestanden die hij aanmaakt zijn van root tenzij je --user meegeeft.
• Naamsherleiding tussen containers werkt op een zelfgemaakt netwerk, nooit op de standaardbridge. Compose maakt er een voor je, en dat is de halve reden om het te gebruiken.
• Laagvolgorde is buildsnelheid. Afhankelijkheden voor code, en opruimen in dezelfde RUN, want een latere laag kan een eerdere nooit verkleinen: 113 MB tegenover 7,81 MB voor hetzelfde resultaat.
• Een .dockerignore-bestand en een multi-stage build zijn de twee wijzigingen met het grootste effect op de imagegrootte. 230 MB werd 7,88 MB in paragraaf 6.3.
• PID 1 negeert signalen die het niet afhandelt, en daarom duurt docker stop tien seconden en eindigt het in afsluitcode 137. Handel SIGTERM af, of draai met --init, dat ook de zombies opruimt die PID 1 anders laat liggen.
• Geheimen die je met --build-arg meegeeft of met ENV zet, worden door docker history afgedrukt. Gebruik in plaats daarvan een BuildKit --mount=type=secret.
• -p 8080:80 bindt aan 0.0.0.0 en Docker's firewallregels gaan voor die van ufw. Schrijf -p 127.0.0.1:8080:80, of publiceer helemaal niet.
• latest is een label, geen versie. Zet tags vast, en zet digests vast voor alles wat je uitrolt.
• Onder de CLI zitten dockerd, containerd, een shim per container en runc. runc stopt zodra de namespaces bestaan, en de shim valt onder init, en daarom overleeft de stapel de daemon en kon Kubernetes dockershim laten vallen zonder een enkele image te breken.
• Het bestandssysteem is OverlayFS: alleen-lezen lagen onder, een schrijfbare laag erboven, een samengevoegd beeld. Schrijven naar een bestand uit een imagelaag kopieert eerst het hele bestand omhoog, wat op grote bestanden een echte kostenpost is en nog een reden dat data in een volume hoort.
• Docker past al drie beschermingen toe waar je niet om vroeg: 14 van de 41 capabilities, een seccomp-filter, en een AppArmor-profiel. --privileged haalt alle drie tegelijk weg en geeft de schijven van de host uit handen. Voeg liever een capability toe.
• Afsluitcode 137 betekent "gedood door signaal 9" en niets meer. OOMKilled is wat een geheugenlimiet onderscheidt van een niet-afgehandelde docker stop.
• Docker ruimt nooit uit zichzelf op. Draai regelmatig docker system df, ruim bewust op, en onthoud dat --volumes data verwijdert terwijl al het andere alleen een download kost.

Dit is het overzicht dat het bewaren waard is:

RUN AND INSPECT
docker run --rm -it IMAGE sh          throwaway container with a shell
docker run -d --name web -p 127.0.0.1:8080:80 IMAGE
docker ps / docker ps -a              running / all containers
docker logs -f --tail 50 NAME         follow the last 50 lines
docker exec -it NAME sh               shell inside a RUNNING container
docker inspect NAME                   everything Docker knows
docker stats                          live CPU and memory per container
docker top NAME                       its processes, as the host sees them

LIFECYCLE
docker stop NAME                      SIGTERM, then SIGKILL after 10s
docker stop -t 30 NAME                give it 30 seconds instead
docker start / restart / kill NAME
docker rm -f NAME                     stop and delete (writable layer lost)

IMAGES
docker pull IMAGE:TAG                 tags move; pull deliberately
docker build -t app:1.0 .             the "." is the build CONTEXT
docker build --no-cache -t app:1.0 .
docker history --no-trunc IMAGE       every layer, and every secret in one
docker image inspect IMAGE -f '{{json .RepoDigests}}'
docker save IMAGE | gzip > img.tar.gz     move an image without a registry
gunzip -c img.tar.gz | docker load

DATA AND NETWORK
docker volume create|ls|inspect|rm NAME
-v myvol:/var/lib/mysql               named volume: prefilled from the image
-v "$PWD:/app"                        bind mount: HIDES the image's content
--user "$(id -u):$(id -g)"            stop creating root-owned files
docker network create mynet           name resolution needs a user network
--add-host=host.docker.internal:host-gateway     reach the host from inside

COMPOSE
docker compose up -d / down           down keeps named volumes
docker compose down -v                ... and this deletes them
docker compose ps / logs -f SERVICE / exec SERVICE sh
docker compose pull                   actually fetch newer images

HARDENING
--user 1000:1000  --read-only  --tmpfs /tmp
--cap-drop ALL    --security-opt no-new-privileges
--cap-add NET_ADMIN                   add ONE capability, never --privileged
--device /dev/ttyUSB0                 one device, never --privileged
--memory=512m     --cpus=1.5   --pids-limit=200
--init                                real PID 1: reaps zombies, forwards
                                      signals, ends the 10-second stop
--log-opt max-size=10m --log-opt max-file=3

CLEANUP (increasing danger)
docker system df                      what is on this disk
docker container prune                stopped containers
docker image prune                    dangling images only
docker builder prune                  build cache
docker system prune                   the three above
docker system prune -a                every image without a running container
docker volume prune                   YOUR DATA

DIGGING UNDERNEATH
docker inspect -f '{{.State.Pid}}' NAME      its PID on the host
docker inspect -f '{{json .GraphDriver}}' NAME    its overlay2 directories
docker ps -s                          writable-layer size (copy-up shows here)
docker run --rm IMAGE grep CapEff /proc/self/status
docker info | grep -E "Cgroup Version|Live Restore"
sudo nsenter -t PID -a sh             enter it without the Docker daemon
lsns / systemd-cgls / dmesg           namespaces, cgroups, OOM kills

exit 137 = killed by signal 9. Check OOMKilled to learn WHICH:
  oomkilled=false => the 10-second docker stop
  oomkilled=true  => the kernel, out of memory
exit 143 = SIGTERM   |  0.0.0.0 in docker ps = open to the network

Docker beloont een beetje nieuwsgierigheid heel snel. De commando's hierboven dekken bijna alles wat de meeste mensen ooit nodig hebben, en wat er in productie misgaat is bijna altijd een van dezelfde handvol dingen: een poort gebonden aan 0.0.0.0, data die buiten een volume geschreven wordt, een logbestand zonder groottelimiet, of een container die nooit geleerd heeft af te sluiten. Als een site in containers zich gedraagt op een manier die niemand kan verklaren, zijn dat de vier plekken om als eerste te kijken.