Docker Compose commando's: de complete cheat sheet

De Compose-commando's die u daadwerkelijk gebruikt

Docker Compose bevat meer dan veertig subcommando's. Voor dagelijks beheer op een server gebruikt u er ongeveer twaalf. Deze pagina groepeert ze op basis van de taak die u uitvoert, geeft voor elk commando één duidelijke reden en verwijst naar de verdiepende documentatie wanneer een commando een valkuil bevat.

Alles hier gebruikt Compose V2: docker compose met een spatie, niet het oude docker-compose-script. V2 is een Go-plugin die wordt geïnstalleerd met Docker Engine, en V1 is verwijderd uit de huidige pakketten. Een docker-compose: command not found op een verse Ubuntu-server per juli 2026 is dus de verwachting in plaats van een fout. Controleer dit met docker compose version. Als dit niets weergeeft, installeer dan het docker-compose-plugin-pakket.

Elk onderstaand commando voert u uit vanuit de map die uw compose.yaml bevat, omdat Compose de projectnaam afleidt van die map en het bestand relatief daaraan zoekt. Voer hetzelfde commando één niveau hoger uit en Compose stopt met no configuration file provided: not found. Als de bestandsindeling zelf nieuw voor u is, begin dan bij een eerste Compose-bestand op een VPS en keer hier terug voor de commando's.

Lifecycle: de vier commando's die u typt, en degene 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 aan, creëert de containers, start ze en keert terug. Het commando keert terug zodra de containers zijn aangemaakt; daarom faalt een deploy-script dat direct daarna een curl-probe uitvoert vaak bij de eerste poging. up -d --wait blokkeert totdat elke service die een healthcheck declareert, rapporteert dat deze in orde is, en sluit af met een non-zero status als dit niet wordt bereikt. De vlag is slechts zo betrouwbaar als de achterliggende check; schrijf daarom een healthcheck waar Compose op kan vertrouwen voordat u hierop leunt in automatisering.

stop stopt de containers en behoudt ze, waardoor start dezelfde containers terugbrengt met dezelfde beschrijfbare laag. down stopt ze en verwijdert vervolgens de containers en het projectnetwerk. Alles wat binnen de container en buiten een volume is geschreven, gaat daarmee verloren. Dat is het meest kostbare misverstand in Compose, en het volledige verschil tussen down en stop behandelt waar dit tot problemen leidt.

restart is geen herlaadactie. Het stopt en start dezelfde container met de configuratie die deze al heeft, waardoor een gewijzigde omgevingsvariabele, een nieuwe image-tag of een aangepaste poortmapping geen enkel effect heeft. Om een bestandswijziging toe te passen, voert u opnieuw up -d uit. Compose vergelijkt elke service met de draaiende container en recreëert alleen de services waarvan de configuratie is gewijzigd.

Wijzigingen doorvoeren: recreate, pull of rebuild

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, wat het veilig maakt om herhaaldelijk uit te voeren. --force-recreate negeert die vergelijking en vervangt elke container, zelfs als de configuratie identiek is; dit is dus de snelste manier om een ongebruikelijke status binnen een container te wissen.

Het bijwerken van een image vereist twee commando's omdat ze twee verschillende taken uitvoeren. pull downloadt de huidige image voor elke tag die in het bestand is benoemd. up -d ziet vervolgens dat het image-ID van de service niet langer overeenkomt met de draaiende container en maakt deze opnieuw aan. Sla de pull over en up -d blijft de latest van vorige maand uitvoeren zonder foutmelding. Het tegenovergestelde risico doet zich voor bij een stack met meerdere services, waarbij het tegelijkertijd pullen van latest voor elke service een applicatie kan verbreken die tien seconden eerder nog werkte. Daarom gebruikt een zelfgehoste AFFiNE-workspace voor elk van de vier image-tags een specifieke versie.

build is van toepassing op services die een build:-sectie declareren in plaats van een image:. up -d --build bouwt en start in één stap; dit is de normale cyclus terwijl u code wijzigt. Gebruik --no-cache alleen wanneer een gecachte laag duidelijk verouderd is, omdat dit elke laag vanaf nul opnieuw opbouwt.

Inzicht in actieve processen

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 opstarten is gecrasht, is daar niet zichtbaar totdat u -a toevoegt. Het is daarom normaal dat een container ontbreekt in ps, terwijl ps -a deze weergeeft als Exited (1) bij een opstartfout. Lees de exitcode en raadpleeg vervolgens de logs.

logs -f volgt alle services tegelijk en voorziet elke regel van de servicenaam. Dit is het overzicht dat u nodig heeft wanneer services met elkaar communiceren en de volgorde van gebeurtenissen van belang is. Geef een servicenaam op om het resultaat te filteren. --tail=100 is van belang bij een container die al een maand draait, omdat de standaardinstelling de volledige geschiedenis toont en de terminal overspoelt. --since 15m beantwoordt de vraag die u doorgaans heeft: wat is er gebeurd tijdens de herstart die u zojuist heeft uitgevoerd.

top somt de processen binnen elke container op. Hiermee maakt u onderscheid tussen "de container draait" en "het proces in de container draait". ls verlaat de huidige map en toont elk Compose-project op de host met de bijbehorende status, zodat u de stack die u drie maanden geleden heeft gestart, kunt terugvinden.

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 commando uit in een container die al actief is. run start een nieuwe container op basis van dezelfde servicedefinitie; dit is nodig wanneer de service niet lang genoeg actief blijft om er met exec in te kunnen. Combineer run altijd met --rm, omdat elke aanroep anders een gestopte container achterlaat. Deze stapelen zich op totdat docker compose ps -a onleesbaar wordt.

Probeer sh voordat u bash gebruikt. Images op basis van Alpine bevatten geen bash, wat resulteert in de foutmelding exec: "bash": executable file not found in $PATH. Door --no-deps toe te voegen aan run worden de afhankelijkheden van de service overgeslagen. Dit voorkomt dat een snelle configuratiecontrole uw volledige database opstart.

run --rm web env is de snelste manier om de omgeving te bekijken die een service daadwerkelijk heeft ontvangen, nadat elk .env-bestand, environment:-blok en elke shell-variabele is samengevoegd. Wanneer een waarde onjuist is, is de samenvoegvolgorde meestal de oorzaak, en 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 en elke servicenaam fungeert daarbinnen als een DNS-naam. Het uitvoeren van getent hosts db binnen web toont het IP-adres van de container als de resolutie werkt en geeft geen uitvoer als dit niet het geval is; hiermee beantwoordt u in twee seconden of de containers elkaar kunnen bereiken. Als de naam wel wordt omgezet maar de verbinding wordt geweigerd, is het proces binnen db gebonden aan 127.0.0.1 in plaats van 0.0.0.0, waardoor het nooit pakketten van een andere container accepteert. De rest van dat model staat in hoe Compose-netwerken en service-DNS werken.

port web 80 toont het hostadres en de poort waarop een containerpoort is gepubliceerd, wat giswerk voorkomt wanneer de mapping afkomstig is van een variabele. Het publiceren van een poort schrijft ook een firewallregel die Docker zelf beheert; deze regel staat vóór uw eigen regels, waardoor een service die u als privé beschouwde, open kan staan voor het internet. Dat scenario wordt behandeld in waarom gepubliceerde Docker-poorten ufw omzeilen. Het is veiliger om deze poorten niet te publiceren en in plaats daarvan één authenticerende proxy op het projectnetwerk voor de services te plaatsen, wat u bereikt met Authentik draaien als single sign-on laag.

Volumes en data

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

config --volumes toont de benoemde volumes die in het project zijn gedeclareerd, één per regel. Deze lijst is wat u moet back-uppen. Wanneer de volumes onvervangbare gegevens bevatten, is het exacte back-upcommando net zo belangrijk als de lijst zelf. Daarom beschrijft de vergelijking tussen PhotoPrism en Immich de specifieke dump- en kopieercommando's die elke fotoserver vereist. cp kopieert een bestand naar of uit een container zonder een shell te openen, waarbij de service:path-notatie wordt gebruikt aan de zijde waar de container zich bevindt.

down -v verwijdert deze benoemde volumes samen met de containers. Dit is het juiste commando voor het afbreken van een testomgeving, maar het is ongeschikt voor alles wat gegevens bevat die u wilt behouden, omdat er geen bevestiging wordt gevraagd en de actie niet ongedaan kan worden gemaakt. Bind mounts overleven dit proces, aangezien deze zich op het bestandssysteem van de host bevinden. Dit verschil in impact is een reden om bewust te kiezen tussen bind mounts en benoemde volumes.

Opschonen van schijfruimte zonder gegevensverlies

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 langer in het bestand voorkomen. Dit is precies wat er gebeurt na het hernoemen van een service. Zonder dit commando blijven die containers actief, terwijl ze onzichtbaar zijn voor docker compose ps.

docker system df toont waar de schijfruimte is gebleven voordat u iets verwijdert. Het geeft een overzicht van images, containers, lokale volumes en de build-cache, inclusief de hoeveelheid ruimte die per onderdeel kan worden vrijgemaakt. image prune -a verwijdert elke image waarnaar geen tag verwijst. Op een server die meerdere versies van een grote image heeft binnengehaald, levert dit meestal de grootste winst op. builder prune wist de build-cache, die ongemerkt groeit op elke server die zelf images bouwt.

Geen van deze commando's raakt een named volume aan. Alleen docker volume prune en docker compose down -v doen dat.

Het bestand controleren voordat het schade aanricht

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

config --quiet valideert en geeft geen output bij succes; daarom hoort dit thuis in een pre-deploy stap of een git hook. Een standaard config toont het volledig samengevoegde en geïnterpoleerde bestand. Hiermee controleert u of een variabele correct is opgelost en of een override-bestand op de verwachte wijze is toegepast. Een niet-ingestelde variabele verschijnt hier als een lege waarde, naast de waarschuwing The "X" variable is not set. Defaulting to a blank string.

--dry-run is een globale vlag in plaats van een subcommando-vlag, dus deze plaatst u vóór up. Het toont elke actie die Compose zou uitvoeren zonder daadwerkelijk wijzigingen aan te brengen. Dit is dertig seconden die goed besteed zijn vóór een down op een belangrijke stack.

Werken met meerdere 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, waarbij latere bestanden eerdere bestanden per sleutel overschrijven. Dit is de standaardmethode om één basisbestand te behouden met een kleine override voor productie. De regels voor lijsten en maps wijken echter af, dus lees hoe Compose meerdere bestanden samenvoegt voordat u een onverwacht resultaat gaat debuggen.

--profile start services die met dat profiel zijn getagd naast de services zonder tag, waardoor debug-tools buiten een normale up blijven. -p stelt de projectnaam in, zodat twee kopieën van dezelfde stack naast elkaar kunnen draaien met afzonderlijke netwerken en aparte volumenamen. Het terugkrijgen van de stack na een reboot is geen commando dat u handmatig typt; het is een unit die dit voor u uitvoert, zoals beschreven in Compose-stacks starten bij het opstarten.

FAQ

Wat heeft docker-compose met een koppelteken vervangen?

Compose V2, aangeroepen als docker compose met een spatie. Het is een plugin die is meegeleverd met Docker Engine, en de V1 Python-tool wordt niet langer geïnstalleerd door huidige pakketten. Als de vorm met een spatie niets weergeeft, installeer dan het docker-compose-plugin-pakket voor uw distributie. Update oude scripts naar de vorm met een spatie in plaats van een alias toe te voegen, omdat V2 vlaggen heeft die V1 nooit had.

Waarom verwerkt docker compose restart mijn configuratiewijziging niet?

restart stopt en start de bestaande container met de configuratie waarmee deze is aangemaakt, en leest compose.yaml nooit opnieuw in. Elke wijziging aan omgevingsvariabelen, poorten, volumes of de image-tag vereist docker compose up -d, die elke service vergelijkt met de draaiende container en de afwijkende containers opnieuw aanmaakt. Voeg --force-recreate toe wanneer u wilt dat de vervanging plaatsvindt, zelfs als er niets in het bestand is gewijzigd.

Hoe update ik een service naar een nieuwere image?

Voer docker compose pull uit, gevolgd door docker compose up -d. De pull haalt de huidige image op voor elke tag in het bestand, en up -d maakt elke service opnieuw aan waarvan de image-ID niet langer overeenkomt met de container. Het uitvoeren van up -d op zichzelf hergebruikt de image die al op schijf staat; dit is de reden waarom een stack die vastgezet is op latest maandenlang op een oude build kan blijven draaien zonder foutmeldingen te geven.

Welke opschooncommando's zijn veilig op een live server?

docker system df, docker image prune -a en docker builder prune verwijderen alleen images en cache, waardoor draaiende services blijven werken en named volumes onaangetast blijven. Het gevaarlijke duo is docker compose down -v en docker volume prune, die named volumes zonder waarschuwing verwijderen. Voer eerst docker compose config --volumes uit zodat u weet wat er op het spel staat.

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

Ja. docker compose run --rm --no-deps web sh start een enkele container op basis van de web-service-definitie, slaat de afhankelijkheden over en verwijdert de container wanneer u afsluit. Gebruik in plaats daarvan exec wanneer de container al draait, omdat exec zich aansluit bij het actieve proces en u de werkelijke status van de service toont.