Docker en Docker Compose installeren op Debian en Ubuntu

Docker installeren duurt vijf minuten. Docker zo installeren dat de server een jaar later nog actuele beveiligingsupdates krijgt, dat de systeemschijf niet volloopt en dat niet per ongeluk elke gebruiker met rootrechten rondloopt, duurt iets langer. Dit artikel behandelt de tweede variant, getest op Debian 13 (Trixie), Debian 12 (Bookworm), Ubuntu 24.04 (Noble) en Ubuntu 22.04 (Jammy).

docker.io of Docker CE: het verschil dat bijna niemand eerlijk uitlegt

Er zijn twee manieren om aan Docker te komen. Het pakket docker.io komt uit de pakketbronnen van de distributie en wordt door Debian respectievelijk Ubuntu gebouwd en onderhouden. Het pakket docker-ce komt uit de repository van Docker zelf. Beide bevatten dezelfde software, maar van heel verschillende leeftijd.

Dit zijn de versies die op dit moment in de distributiebronnen staan (nagemeten met apt-cache policy in verse containers):

Daar draait het werkelijk om, en in bijna alle handleidingen wordt dat teruggebracht tot één algemeen advies. De werkelijkheid ligt genuanceerder:

• Ubuntu 24.04 en 22.04: docker.io staat op 29.1.3 en daarmee vrijwel gelijk met de actuele upstream-versie. Wie geen bijzondere eisen heeft, kan hier met een gerust hart het distributiepakket nemen. Beveiligingsupdates komen dan via het normale Ubuntu-kanaal.
• Debian 13: 26.1.5 is bruikbaar, maar loopt een flink stuk achter op upstream. Voor de meeste toepassingen volstaat het.
• Debian 12: 20.10.24 is het probleemgeval. Deze tak is upstream al jaren aan het einde van zijn levenscyclus. Debian voert weliswaar beveiligingspatches door, maar veel moderne functies ontbreken domweg, onder andere een actuele BuildKit-versie en een deel van de Compose-compatibiliteit.

Daar komt een praktisch verschil bij: docker-ce levert Buildx en Compose mee als eigen plug-inpakketten die bij de engine passen. Bij docker.io moet u die onderdelen los bij elkaar zoeken uit docker-buildx en docker-compose-v2, en docker-compose-v2 zit uitsluitend in de Ubuntu-bronnen: onder Debian bestaat dat pakket helemaal niet.

Wat niet kan: allebei naast elkaar. Het pakket containerd.io uit de Docker-repository conflicteert met het pakket containerd uit de distributie. U moet kiezen.

Vuistregel: op Ubuntu is docker.io een legitieme keuze. Op Debian 12 niet. Voor servers die Compose-stacks met actuele syntaxis draaien, is Docker CE overal de betere beslissing.

Oude pakketten verwijderen voordat er iets anders gebeurt

Staat er al een Docker in welke vorm dan ook op het systeem, dan moet die eraf, anders loopt de installatie stuk op pakketconflicten. De volgende lus verwijdert alle gebruikelijke verdachten en vangt daarbij pakketten af die helemaal niet geïnstalleerd zijn of in uw distributie niet eens bestaan:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove -y $pkg || true; done

De || true in de lus is geen schoonheidsfoutje, maar noodzaak. Op Debian breekt apt-get bij de vermelding docker-compose-v2 af met E: Unable to locate package docker-compose-v2 en exitcode 100, want dat pakket bestaat uitsluitend in de Ubuntu-bronnen, niet in bookworm of trixie (en ook niet in bullseye, waar bovendien podman-docker ontbreekt). De lus draait weliswaar door, maar laat een exitcode ongelijk aan 0 achter, en precies daarop sneuvelt een script met set -e of een aaneenschakeling met &&. Meldingen in de trant van "Unable to locate package" zijn op dit punt dus normaal en mogen genegeerd worden, ook de officiële Docker-documentatie houdt het daarop.

Belangrijk om te weten: daarbij gaat niets verloren. Uw images, containers en volumes staan in /var/lib/docker, en die map raakt apt-get remove niet aan. Na de installatie van Docker CE zijn uw containers er weer. Pas sudo rm -rf /var/lib/docker wist echt, en dat is onomkeerbaar.

De sleutel goed neerzetten: apt-key is verleden tijd

Veel handleidingen op internet bevatten nog deze regel:

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -

Op geen van de vier hier behandelde systemen werkt dat nog zinvol. apt-key is afgeschaft en op Debian 13 zelfs helemaal niet meer aanwezig. De reden is geen cosmetica: een sleutel in /etc/apt/trusted.gpg ondertekent alle repositories, niet alleen die waarvoor hij bedoeld was. Een gecompromitteerde mirrorserver zou u daarmee willekeurige pakketten kunnen aansmeren.

Correct is een eigen keyring onder /etc/apt/keyrings/, die via Signed-By aan precies één pakketbron wordt gekoppeld.

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings

Het volgende commando haalt de juiste sleutel op en werkt zowel op Debian als op Ubuntu, omdat het de distributie-ID uit /etc/os-release leest:

sudo curl -fsSL "https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg" -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

En dan nu de stap die vrijwel niemand beschrijft: controleer de vingerafdruk voordat u de sleutel uw systeem toevertrouwt.

gpg --show-keys /etc/apt/keyrings/docker.asc

De uitvoer moet de vingerafdruk 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88 en de aanduiding Docker Release (CE deb) <docker@docker.com> bevatten. Komt dat niet overeen, breek dan af. Er klopt dan iets niet met uw verbinding of met de bron.

Docker CE installeren, met één snippet voor alle vier de systemen

De officiële documentatie toont gescheiden blokken voor Debian en Ubuntu. Dat is niet nodig. Het volgende blok schrijft de pakketbron in het moderne deb822-formaat en bepaalt distributie, codenaam en architectuur zelf:

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Twee details die tijd besparen. Ten eerste ${UBUNTU_CODENAME:-$VERSION_CODENAME}: op Ubuntu-afgeleiden zoals Linux Mint staat in VERSION_CODENAME de naam van de afgeleide distributie en niet die van Ubuntu. Ten tweede de regel Architectures: zonder die regel klaagt apt op systemen waar i386 als vreemde architectuur is geactiveerd, met een lange waarschuwing over ontbrekende pakketlijsten.

Controleer het resultaat voordat u verdergaat:

cat /etc/apt/sources.list.d/docker.sources

In Suites moet trixie, bookworm, noble of jammy staan. Staat daar iets anders, dan loopt de volgende stap op een fout uit. Daarna volgen de update en de installatie:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

De vijf pakketten zijn: de daemon, het commandoregelprogramma, de containerruntime, de moderne image-builder en Compose.

Controleren of het echt draait

Dat apt-get zonder fouten is doorgelopen, betekent alleen dat er bestanden op de schijf staan. De volgende vier controles laten zien of het systeem daadwerkelijk werkt.

Ten eerste: bereikt de client de daemon?

docker version

Doorslaggevend is niet het blok Client, maar dat daaronder een blok Server: Docker Engine - Community met een versienummer verschijnt. Ontbreekt dat, dan draait de daemon niet of hebt u geen toegang tot de socket.

Ten tweede: welke storage driver is actief?

docker info --format '{{.Driver}}'
docker info --format '{{.CgroupVersion}}'

Hier schuilt een vernieuwing die veel oudere handleidingen verkeerd beantwoorden. Sinds Docker Engine 29 staat bij nieuwe installaties de containerd-image-store standaard aan. De driver heet dan overlayfs en niet meer overlay2. Beide waarden zijn in orde. Wat u niet wilt zien, is vfs: deze nooddriver kopieert elke laag volledig, verbruikt een veelvoud aan schijfruimte en is tergend traag. Hij duikt meestal op wanneer Docker draait in een omgeving zonder passende kernelondersteuning. De cgroup-versie moet op alle vier de systemen 2 opleveren.

Hebt u een bestaand systeem bijgewerkt en lijken plotseling alle images verdwenen: ze zijn niet gewist. Bij een wissel van image-store wordt de voorraad van de andere opslag alleen verborgen, en die komt bij het terugschakelen weer tevoorschijn. Terugschakelen gaat via /etc/docker/daemon.json:

{
  "features": {
    "containerd-snapshotter": false
  }
}

Ten derde: draait er werkelijk een container?

docker run --rm hello-world

Ten vierde: werken netwerk en naamresolutie in de container? Deze test ontbreekt in bijna elke handleiding, terwijl juist hier de meeste vervolgproblemen ontstaan:

docker run --rm alpine:3 ping -c 2 1.1.1.1
docker run --rm alpine:3 nslookup deb.debian.org

Antwoordt de ping wel, maar mislukt de naamresolutie, dan ligt het meestal aan een DNS-server die alleen op 127.0.0.53 luistert. Vanuit de container is dat adres niet bereikbaar. Een vermelding in /etc/docker/daemon.json met "dns": ["9.9.9.9"] plus een herstart van de daemon lost dat op.

Compose is een plug-in, geen apart programma meer

Het oude docker-compose met koppelteken was een apart Python-programma. Het is uitgefaseerd en wordt niet meer meegeleverd. De opvolger is een in Go geschreven plug-in die als subcommando van de Docker-CLI wordt aangeroepen, dus docker compose met een spatie.

docker compose version

Nog een opmerking over het versienummer, omdat dat regelmatig voor verwarring zorgt: de term "Compose V2" slaat op de herbouw in Go, niet op het versienummer. De uitvoer toont tegenwoordig een versie uit de 5-tak. Dat klopt en is beslist geen ander product.

Bij de overstap vallen twee dingen op. Ten eerste is de sleutel version: aan het begin van docker-compose.yml overbodig geworden en levert die een waarschuwing op:

WARN[0000] docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion

Verwijder die regel gewoon. Ten tweede verandert de naamgeving: Compose leidt de projectnaam af van de mapnaam en maakt containers met een koppelteken in plaats van een underscore, dus mijnproject-web-1 in plaats van mijnproject_web_1. Scripts die containers via vaste namen aanspreken, sneuvelen daardoor. Leg de projectnaam in zulke gevallen expliciet vast via name: in het Compose-bestand of via -p.

Wilt u bewust bij de distributiepakketten blijven, dan heet het passende pakket docker-compose-v2 en levert dat hetzelfde subcommando. Het is echter alleen in de Ubuntu-bronnen beschikbaar. Controleer vooraf welke versie er klaarstaat:

apt-cache policy docker-compose-v2

Op Ubuntu 24.04 en 22.04 verschijnt een tabel met de geïnstalleerde versie en de kandidaat. Op Debian 13 en Debian 12 geeft het commando helemaal niets terug, een lege uitvoer met exitcode 0. Dat is geen fout, maar het antwoord: onder Debian bestaat dit pakket niet, daar loopt de weg naar Compose via docker-compose-plugin uit de Docker-repository.

De groep docker is root, alleen via een omweg

Om een gewone gebruiker Docker zonder sudo te laten bedienen, wordt die doorgaans in de groep docker opgenomen:

sudo groupadd -f docker
sudo usermod -aG docker $USER

Het groepslidmaatschap wordt pas actief nadat u opnieuw hebt ingelogd. Daarna controleert u dat met id -nG. Wie niet opnieuw wil inloggen, start met newgrp docker een shell met de nieuwe groep.

Nu volgt het deel dat u echt begrepen moet hebben: lidmaatschap van de groep docker staat gelijk aan rootrechten op de hele server. Dat is geen theoretisch oordeel, maar een direct gevolg van de werking. Wie met de Docker-socket mag praten, mag de daemon (die als root draait) willekeurige opdrachten geven. Eén enkel commando volstaat:

docker run -it -v /:/hostfs alpine:3 chroot /hostfs sh

Het resultaat is een rootshell op het hostsysteem, zonder sudo, zonder dat er om een wachtwoord wordt gevraagd, zonder vermelding in de sudo-logging. /etc/shadow lezen, SSH-sleutels neerzetten, diensten vervangen: alles kan. De Docker-documentatie formuleert het kort en ondubbelzinnig: "The docker group grants root-level privileges to the user."

Praktische gevolgen voor een server op het internet:

• Neem uitsluitend accounts in de groep op die u toch al root zou toevertrouwen.
• De gebruiker waaronder een webapplicatie of een CI-runner draait, hoort daar niet bij. Een inbraak in de applicatie zou anders automatisch een inbraak in de server zijn.
• Hebt u traceerbaarheid nodig, sla de groep dan over en roep Docker aan via sudo docker. Dan verschijnt de aanroep tenminste in het logboek.
• Voor echte scheiding is er de rootless-modus. Die wordt ingericht via het pakket docker-ce-rootless-extras en de tool dockerd-rootless-setuptool.sh install en heeft daarnaast uidmap nodig. De prijs: poorten onder 1024 zijn zonder extra configuratie niet te bezetten, en enkele netwerkfuncties gedragen zich anders.

Autostart: de valkuil heet docker.socket

Het standaardcommando is bekend:

sudo systemctl enable --now docker.service
sudo systemctl enable --now containerd.service

Minder bekend is waarom uitschakelen vaak niet werkt. Docker levert naast docker.service ook een docker.socket mee. Die unit luistert op de socket en start de daemon bij de eerste toegang automatisch. Wie dus systemctl disable docker.service uitvoert en daarna vaststelt dat Docker toch draait, heeft geen spoken gezien: de eerste docker ps heeft de daemon via de socket-unit opnieuw gestart. Voor volledig uitschakelen horen ze er allebei bij:

sudo systemctl disable --now docker.service docker.socket

De toestand controleert u met systemctl is-enabled docker.service, dat enabled moet teruggeven.

Het tweede punt betreft uw containers. Of een container na een herstart terugkomt, bepaalt niet systemd, maar de restart policy. Daarbij zit een verschil dat regelmatig verrast: always start een container ook weer op wanneer u die vóór de herstart bewust hebt gestopt. unless-stopped respecteert uw handmatige stop over de herstart heen. Voor servers is unless-stopped vrijwel altijd de juiste keuze:

services:
  web:
    image: nginx:stable
    restart: unless-stopped

De test daarvoor is niet docker ps, maar een echte herstart van de server met een controle achteraf.

Logrotatie: de meest voorkomende oorzaak van een volle systeemschijf

Docker schrijft de uitvoer van elke container standaard naar een JSON-bestand onder /var/lib/docker/containers/. Dat bestand groeit standaard ongelimiteerd. Een spraakzame reverse proxy kan zo over maanden tientallen gigabytes verzamelen, tot de server met no space left on device stilvalt. De schuldige is dan lastig te vinden, omdat du in de applicatiemap niets opvallends laat zien.

De oplossing hoort op elke server thuis, en wel voordat het eerste probleem zich voordoet:

sudo mkdir -p /etc/docker

sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

Bestaat er al een daemon.json, dan overschrijft dit commando die. Kijk eerst wat erin staat en voeg de sleutels zo nodig met de hand toe. Daarna:

sudo systemctl restart docker

Drie punten waarop het toch nog misgaat:

• De waarden moeten als tekenreeksen tussen aanhalingstekens staan. "max-file": 3 zonder aanhalingstekens zorgt ervoor dat de daemon niet meer start.
• De instelling geldt alleen voor nieuw aangemaakte containers. Bestaande behouden hun oude configuratie tot ze opnieuw worden aangemaakt, bij Compose dus via docker compose up -d --force-recreate.
• Een overgelopen logbestand met rm verwijderen levert geen schijfruimte op, omdat de daemon het bestand nog geopend houdt. Gebruik in plaats daarvan sudo truncate -s 0 <pad>.

Of de instelling bij een concrete container aanslaat, controleert u zo:

docker inspect --format '{{json .HostConfig.LogConfig}}' mijncontainer

Opruimen met docker system prune, zonder gegevens te verliezen

Ongebruikte images, afgebroken builds en de BuildKit-cache stapelen zich op. Kijk eerst waar de ruimte naartoe gaat:

docker system df
docker system df -v

Het standaardcommando om op te ruimen verwijdert gestopte containers, ongebruikte netwerken, images zonder naam en de build-cache:

docker system prune

Twee schakelaars verdienen respect. -a wist daarnaast alle images die op dat moment door geen enkele container worden gebruikt, dus ook zorgvuldig onderhouden basis-images. Op een server met een smalle uplink kan het opnieuw ophalen daarna lang duren. Duidelijk gevaarlijker is --volumes: die schakelaar verwijdert benoemde volumes zonder bijbehorende container. Is uw databasecontainer net verwijderd terwijl het volume de gegevens nog bevat, dan zijn die daarna weg. Er is geen prullenbak.

Gebruik --volumes nooit in een automatische opruimtaak.

Zinvol is een respijtperiode, zodat alleen echt oud materiaal verdwijnt:

docker system prune -a --filter "until=168h"
docker builder prune --filter "until=168h"

Als wekelijkse taak volstaat één regel in /etc/cron.d/docker-prune, 's nachts uitgevoerd om de server te ontzien en zonder volumes te wissen:

15 4 * * 0 root /usr/bin/docker system prune -af --filter "until=168h" > /dev/null 2>&1

Het bewijs dat het gelukt is, levert een nieuwe docker system df met een gedaalde kolom "RECLAIMABLE".

Foutmeldingen letterlijk, en wat erachter zit

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
De gebruiker zit niet in de groep docker, of het groepslidmaatschap is in de huidige sessie nog niet actief. Opnieuw inloggen of newgrp docker.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
De daemon draait niet. De oorzaak en de exacte tekst vindt u met systemctl status docker, uitgebreider nog met journalctl -u docker -n 50 --no-pager. Heel vaak zit er een foutieve /etc/docker/daemon.json achter. Dat bestand moet geldige JSON zijn, één komma te veel is al genoeg.

docker: 'compose' is not a docker command.
De plug-in ontbreekt. Installeer alsnog docker-compose-plugin uit de Docker-repository of, alleen onder Ubuntu, docker-compose-v2 uit de distributie.

E: Conflicting values set for option Signed-By regarding source https://download.docker.com/linux/debian/ trixie: /etc/apt/keyrings/docker.asc != /etc/apt/keyrings/docker.gpg
De klassieker na het doorwerken van meerdere handleidingen: er bestaan tegelijk een oude /etc/apt/sources.list.d/docker.list en de nieuwe docker.sources. Verwijder het oude bestand en herhaal sudo apt-get update. Verschaf uzelf met ls -l /etc/apt/sources.list.d/ een overzicht.

The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 8D81803C0EBFCD88
De sleutel staat niet waar Signed-By hem verwacht, of het gedownloade bestand is onvolledig (bijvoorbeeld omdat een proxy een HTML-foutpagina heeft geleverd). gpg --show-keys /etc/apt/keyrings/docker.asc laat meteen zien of er wel een sleutel in zit.

E: The repository 'https://download.docker.com/linux/debian trixie Release' does not have a Release file.
De codenaam past niet bij de bron. Dat gebeurt op afgeleide distributies en wanneer handleidingen voor Debian en Ubuntu door elkaar worden gehaald. Controleer de regels URIs en Suites in docker.sources.

Bind for 0.0.0.0:80 failed: port is already allocated
Een andere dienst bezet de poort, vaak een rechtstreeks geïnstalleerde webserver. sudo ss -tulpn | grep :80 noemt de veroorzaker.

Docker en de firewall: een woord over veiligheid

Een eigenaardigheid die op een publiek bereikbare server duur kan uitpakken: Docker zet zijn doorstuurregels in de NAT-tabel en omzeilt daarmee de regels die u in ufw hebt ingesteld. Een container die met -p 5432:5432 is gestart, is vanaf het internet bereikbaar, ook als ufw status die poort nergens toestaat. Dat blijft gelden, ook al heeft Docker Engine 28 het netwerkgedrag in het algemeen gehard en de toegang van buitenaf tot niet gepubliceerde poorten geblokkeerd.

De eenvoudigste en betrouwbaarste tegenmaatregel is om diensten die alleen lokaal nodig zijn, uitdrukkelijk aan het loopback-adres te binden:

services:
  db:
    image: postgres:17
    ports:
      - "127.0.0.1:5432:5432"
    restart: unless-stopped

Nog beter: publiceer zulke poorten helemaal niet en laat de containers via een gedeeld Docker-netwerk met elkaar praten. Het resultaat controleert u het best vanaf een tweede machine, want een test vanaf de server zelf beantwoordt de doorslaggevende vraag niet.

Kort samengevat

Neem op Debian 12 in elk geval Docker CE, op Ubuntu mag u kiezen tussen docker.io en Docker CE. Voeg de repository toe met een eigen keyring en een gecontroleerde vingerafdruk, niet met apt-key. Gebruik docker compose met een spatie. Behandel de groep docker alsof u daarmee root weggeeft, want dat is precies wat er gebeurt. En richt logrotatie plus een wekelijkse prune-taak in voordat de server voor het eerst op een volle schijf vastloopt.

Ook interessant: UFW-firewall op Debian en Ubuntu instellen en Nginx op Debian en Ubuntu installeren.