Docker Compose cheat sheet voor echte servers

De Compose-opdrachten die u daadwerkelijk gebruikt

Docker Compose wordt geleverd met meer dan veertig subopdrachten. Voor dagelijks werk op een server gebruikt u er ongeveer een dozijn. Op deze pagina zijn die gegroepeerd op basis van de taak die u uitvoert. Elke opdracht krijgt een duidelijke reden en verwijst naar de uitgebreide uitleg als de opdracht een valkuil bevat.

Alles op deze pagina gebruikt Compose V2: docker compose met een spatie, niet het oude docker-compose-script. V2 is een Go-plugin die samen met Docker Engine wordt geïnstalleerd. V1 zit niet meer in de huidige pakketten. Daarom is een docker-compose: command not found op een nieuwe Ubuntu-server vanaf juli 2026 verwacht gedrag en geen fout. Controleer dit met docker compose version. Als die opdracht niets uitvoert, installeert u het pakket docker-compose-plugin.

Elke onderstaande opdracht voert u uit vanuit de directory met uw compose.yaml. Compose ontleent de projectnaam aan die directory en zoekt het bestand relatief ten opzichte daarvan. Als u dezelfde opdracht één niveau hoger uitvoert, stopt Compose met no configuration file provided: not found. Als de bestandsindeling zelf nieuw voor u is, begint u met een eerste Compose-bestand op een VPS en komt u daarna hier terug voor de opdrachten.

Levenscyclus: de vier opdrachten die u typt en de opdracht die containers verwijdert

docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose down

up -d maakt het netwerk en de containers aan, start de containers en keert terug. De opdracht keert terug zodra de containers zijn aangemaakt. Daarom mislukt een deployscript dat daarna een curl-controle uitvoert, vaak bij de eerste poging. up -d --wait blokkeert totdat elke service met een healthcheck de status healthy rapporteert. De opdracht eindigt met een niet-nul exitstatus als een service die status nooit bereikt. De vlag is alleen zo betrouwbaar als de controle erachter. Schrijf daarom eerst een healthcheck waarop Compose kan vertrouwen voordat u erop vertrouwt in automatisering.

stop stopt de containers en behoudt ze. start start daardoor dezelfde containers opnieuw met dezelfde schrijfbare laag. down stopt de containers en verwijdert daarna de containers en het projectnetwerk. Alles wat in de container en buiten een volume is geschreven, gaat verloren. Dit is het grootste misverstand over Compose. Het volledige verschil tussen down en stop beschrijft waar dit gevolgen heeft.

restart is geen reload. De opdracht stopt en start dezelfde container met de configuratie die deze al heeft. Een gewijzigde omgevingsvariabele, een nieuwe imagetag of een aangepaste port mapping heeft daarom helemaal geen effect. Als u een wijziging in een bestand wilt toepassen, voert u up -d opnieuw uit. Compose vergelijkt elke service met de actieve container en maakt alleen de containers opnieuw aan waarvan de configuratie is gewijzigd.

Een wijziging toepassen: opnieuw maken, ophalen of opnieuw bouwen

docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build web

up -d doet op zichzelf niets als er niets is gewijzigd. Daardoor kunt u de opdracht herhaaldelijk veilig uitvoeren. --force-recreate negeert deze vergelijking en vervangt elke container, ook als de configuratie identiek is. Dit is de snelste manier om onverwachte status in een container te wissen.

Een image bijwerken vereist 2 opdrachten, omdat deze verschillende taken uitvoeren. pull downloadt de huidige image voor elke tag die in het bestand is opgegeven. up -d stelt vervolgens vast dat de image-ID van de service niet meer overeenkomt met de actieve container en maakt de container opnieuw aan. Als u het ophalen overslaat, blijft up -d de latest van vorige maand uitvoeren zonder foutmelding.

build is van toepassing op services die een sectie build: declareren in plaats van een image:. up -d --build bouwt en start in 1 stap. Dit is de normale werkwijze terwijl u code wijzigt. Gebruik --no-cache alleen wanneer een gecachte laag duidelijk verouderd is, omdat hiermee elke laag opnieuw vanaf nul wordt opgebouwd.

Wat actief is bekijken

docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose ls

ps toont alleen actieve containers. Een service die tijdens het starten is gecrasht, wordt daar pas zichtbaar nadat u -a toevoegt. Een container die ontbreekt in ps terwijl ps -a deze als Exited (1) toont, is dus het normale patroon bij een startfout. Lees de exitcode en lees daarna de logs.

logs -f volgt elke service tegelijk en zet de servicenaam voor elke regel. Dit is de gewenste weergave wanneer services met elkaar communiceren en de volgorde van gebeurtenissen van belang is. Geef een servicenaam op om de uitvoer te beperken. --tail=100 is belangrijk voor een container die een maand actief is, omdat de standaardinstelling de volledige geschiedenis toont en de terminal overspoelt. --since 15m beantwoordt meestal de vraag die u hebt: wat gebeurde er tijdens de herstart die u zojuist uitvoerde?

top toont de processen in elke container. Daarmee kunt u onderscheid maken tussen "de container is actief" en "het proces in de container is actief". ls gaat buiten de huidige directory en toont elk Compose-project op de host met de status ervan. Zo vindt u de stack die u drie maanden geleden hebt gestart.

Een shell openen in een service

docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web sh

exec voert een opdracht uit in een container die al actief is. run start een nieuwe container op basis van dezelfde servicedefinitie. Dat hebt u nodig wanneer de service niet lang genoeg actief blijft om er met exec verbinding mee te maken. Gebruik run altijd samen met --rm. Zonder deze optie laat elke aanroep een gestopte container achter. Deze containers stapelen zich op totdat docker compose ps -a onleesbaar wordt.

Probeer sh voordat u bash gebruikt. Op Alpine gebaseerde images bevatten geen bash. De foutmelding luidt exec: "bash": executable file not found in $PATH. Door --no-deps aan run toe te voegen, slaat u de afhankelijkheden van de service over. Zo voorkomt u dat een snelle configuratiecontrole uw volledige database opstart.

run --rm web env is de snelste manier om te controleren welke omgeving een service daadwerkelijk heeft gekregen, nadat elk .env-bestand, elk environment:-blok en elke shellvariabele is samengevoegd. Als een waarde onjuist is, is de samenvoegvolgorde meestal de oorzaak. hoe Compose env-bestanden en secrets verwerkt legt uit welke bron voorrang krijgt.

Netwerken, poorten en naamresolutie

docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networks

Compose plaatst elke service op één projectnetwerk. Elke servicenaam is daarop een DNS-naam. Als u getent hosts db uitvoert binnen web, wordt het IP-adres van de container weergegeven wanneer de naamresolutie werkt. Er wordt niets weergegeven wanneer dat niet het geval is. Daarmee kunt u in twee seconden controleren of deze containers elkaar kunnen bereiken. Als de naam wordt omgezet, maar de verbinding wordt geweigerd, luistert het proces in db op 127.0.0.1 in plaats van op 0.0.0.0. Het accepteert daardoor geen pakket van een andere container. De rest van dit model wordt beschreven in hoe Compose-netwerken en DNS voor services werken.

port web 80 geeft het hostadres en de poort weer waarop een containerpoort is gepubliceerd. Dat voorkomt giswerk wanneer de toewijzing afkomstig is van een variabele. Door een poort te publiceren wordt ook een firewallregel gemaakt die Docker zelf beheert. Die regel staat vóór uw eigen regels. Daardoor kan een service waarvan u dacht dat deze privé was, toegankelijk zijn vanaf internet. Dit geval wordt beschreven in waarom gepubliceerde Docker-poorten ufw omzeilen.

Volumes en gegevens

docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -v

config --volumes geeft de benoemde volumes weer die het project declareert, één per regel. Die lijst moet u back-uppen. Met cp kopieert u een bestand naar of uit een container zonder een shell te openen. Gebruik daarvoor de notatie service:path aan de kant waarop de container staat.

down -v verwijdert deze benoemde volumes samen met de containers. Dit is het juiste commando om een teststack af te breken, maar het verkeerde voor alles wat gegevens bevat die u wilt behouden. Er is namelijk geen bevestiging en er is geen manier om de bewerking ongedaan te maken. Bind mounts blijven behouden, omdat ze op het bestandssysteem van de host staan. Dat verschil in impactgebied is een van de redenen om bewust te kiezen tussen bind mounts en benoemde volumes.

Opschonen om schijfruimte vrij te maken zonder gegevens te verliezen

docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune

--remove-orphans verwijdert containers die bij het project horen, maar niet meer in het bestand voorkomen. Dat is precies wat gebeurt nadat u een service hebt hernoemd. Zonder deze optie blijven die containers actief, zonder dat ze zichtbaar zijn in docker compose ps.

docker system df toont waar de schijfruimte naartoe is gegaan voordat u iets verwijdert. Hierbij worden images, containers, lokale volumes en de build-cache afzonderlijk weergegeven, met voor elk onderdeel de vrij te maken ruimte. image prune -a verwijdert alle images waarnaar geen tag verwijst. Op een server waarop meerdere versies van een grote image zijn opgehaald, levert dat meestal de meeste ruimtewinst op. builder prune wist de build-cache. Die groeit ongemerkt op elke server waarop images lokaal worden gebouwd.

Geen van deze opdrachten raakt een named volume. Alleen docker volume prune en docker compose down -v doen dat.

Het bestand controleren voordat het problemen veroorzaakt

docker compose config --quiet
docker compose config --services
docker compose --dry-run up -d

config --quiet valideert het bestand en geeft bij succes niets weer. Daarom hoort u deze opdracht in een pre-deploy-stap of git-hook te gebruiken. Met alleen config geeft u het volledig samengevoegde en geïnterpoleerde bestand weer. Zo controleert u of een variabele is opgelost en of een override-bestand op de verwachte manier is toegepast. Een niet-ingestelde variabele verschijnt daar als een lege waarde, naast de waarschuwing The "X" variable is not set. Defaulting to a blank string.

--dry-run is een globale vlag en geen vlag voor een subopdracht. Plaats deze daarom vóór up. De opdracht geeft elke actie weer die Compose zou uitvoeren en wijzigt niets. Die dertig seconden zijn goed besteed voordat u down uitvoert op een belangrijke stack.

Werken met bestanden, profielen en projecten

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -d

Meerdere -f-flags worden in volgorde samengevoegd. Latere bestanden overschrijven eerdere bestanden sleutel voor sleutel. Dit is de standaardmanier om één basisbestand met een kleine productie-override te gebruiken. De regels verschillen echter voor lijsten en maps. Lees daarom eerst hoe Compose meerdere bestanden samenvoegt voordat u een onverwacht resultaat gaat debuggen.

--profile start services met dat profiel naast de services zonder profiel. Zo blijft debugtooling buiten een normale up. -p stelt de projectnaam in. Daardoor kunnen twee exemplaren van dezelfde stack naast elkaar draaien met afzonderlijke netwerken en afzonderlijke volumenamen. De stack na een reboot herstellen doet u niet met een commando dat u handmatig invoert. Daarvoor gebruikt u een unit die dit automatisch uitvoert, zoals beschreven in Compose-stacks bij het opstarten starten.

FAQ

Wat heeft docker-compose met een koppelteken vervangen?

Compose V2, aangeroepen als docker compose met een spatie. Dit is een plugin die met Docker Engine wordt meegeleverd. De V1-tool in Python wordt niet meer geïnstalleerd door huidige pakketten. Als de vorm met een spatie niets weergeeft, installeert u het pakket docker-compose-plugin voor uw distributie. Pas oude scripts aan zodat ze de vorm met een spatie gebruiken, in plaats van een alias toe te voegen. V2 heeft namelijk flags die V1 niet had.

Waarom neemt docker compose restart mijn configuratiewijziging niet over?

restart stopt de bestaande container en start deze opnieuw met de configuratie waarmee de container is gemaakt. Het leest compose.yaml nooit opnieuw. Voor elke wijziging in omgevingsvariabelen, poorten, volumes of de imagetag is docker compose up -d nodig. Deze opdracht vergelijkt elke service met de actieve container en maakt de containers die verschillen opnieuw aan. Voeg --force-recreate toe als u wilt dat de vervanging plaatsvindt, ook wanneer er niets in het bestand is gewijzigd.

Hoe werk ik een service bij naar een nieuwere image?

Voer docker compose pull uit en daarna docker compose up -d. De pull haalt de huidige image op voor elke tag in het bestand. up -d maakt elke service opnieuw aan waarvan de image-ID niet meer overeenkomt met die van de container. Als u alleen up -d uitvoert, wordt de image gebruikt die al op schijf staat. Daardoor kan een stack die is vastgezet op latest maandenlang op een oude build blijven draaien zonder een fout weer te geven.

Welke opruimopdrachten zijn veilig op een actieve server?

docker system df, docker image prune -a en docker builder prune verwijderen alleen images en cache. Actieve services blijven daardoor werken en named volumes worden niet gewijzigd. De gevaarlijke combinatie is docker compose down -v en docker volume prune. Deze opdrachten verwijderen named volumes zonder bevestiging te vragen. Voer eerst docker compose config --volumes uit, zodat u weet wat risico loopt.

Kan ik één opdracht uitvoeren zonder de hele stack te starten?

Ja. docker compose run --rm --no-deps web sh start één container op basis van de web-servicedefinitie, slaat de afhankelijkheden ervan over en verwijdert de container wanneer u afsluit. Gebruik exec als de container al actief is. exec maakt dan verbinding met het actieve proces en toont de feitelijke status van de service.