Docker Compose spiekbrief voor echte servers

De Compose-commando's die u daadwerkelijk gebruikt

Docker Compose bevat tientallen subcommando's. Voor dagelijks werk op een server gebruikt u er ongeveer een dozijn. Deze pagina groepeert ze op basis van uw taak, geeft voor elk commando een duidelijke reden en verwijst naar de verdiepende documentatie wanneer een commando een valkuil bevat.

Alles hier gebruikt Compose V2 of V5: docker compose met een spatie, niet het oude docker-compose-script. Beide zijn Go-plugins; op Linux wordt de Compose-plugin afzonderlijk van Docker Engine geïnstalleerd. Ubuntu 24.04 LTS biedt nog steeds de verouderde Python V1-tool aan als docker-compose versie 1.29.2-6ubuntu1 in de universe-repository. Controleer dit met docker compose version. Als het commando niet beschikbaar is, stel dan de repository van Docker in en installeer het docker-compose-plugin-pakket.

Elk onderstaand commando wordt uitgevoerd vanuit de map die uw compose.yaml bevat; Compose gebruikt de naam van die map als de standaard projectnaam, tenzij u deze overschrijft. Zonder -f of COMPOSE_FILE doorzoekt Compose de werkmap en de bovenliggende mappen naar een configuratiebestand. Als u één niveau hoger werkt, wordt uw stack alleen gevonden als het bestand zich nog op dat zoekpad bevindt. Als het bestandsformaat nieuw voor u is, begin dan met 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, maakt de containers aan, start ze en keert terug. Het keert terug nadat de containers zijn gestart zonder te wachten op de gereedheid van de applicatie; daarom faalt een deploy-script dat direct daarna een curl-probe uitvoert vaak bij de eerste poging. up -d --wait wacht tot services met healthchecks de status 'healthy' bereiken en services zonder healthchecks draaien; een ongezonde service of een verlopen --wait-timeout resulteert in een exit-code die niet nul is. De vlag is slechts zo betrouwbaar als de controle erachter, dus schrijf een healthcheck waar Compose op kan vertrouwen voordat u deze in automatisering gebruikt.

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 is geschreven en buiten een volume valt, gaat verloren. Dat is het meest kostbare misverstand in Compose, en het volledige verschil tussen down en stop behandelt waar dit problemen veroorzaakt.

restart is geen herlaadactie. Het stopt en start dezelfde container met de configuratie die deze al heeft, dus een gewijzigde omgevingsvariabele, een nieuwe image-tag of een aangepaste poorttoewijzing hebben geen enkel effect. Om een wijziging in een bestand toe te passen, voert u up -d opnieuw uit. Compose vergelijkt elke service met de draaiende container en maakt de services opnieuw aan waarvan de configuratie of image is gewijzigd.

Een wijziging doorvoeren: recreaten, pullen of rebuilden

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 hergebruikt draaiende containers wanneer de configuratie en de image ongewijzigd zijn; het ophalen (pullen) en bouwen van images volgt het pull-beleid van de service. --force-recreate negeert die vergelijking en vervangt elke container, zelfs als de configuratie identiek is. Dit is daarom de snelste manier om ongebruikelijke statusinformatie binnen een container te wissen.

De expliciete procedure voor het bijwerken van images gebruikt twee commando's omdat deze verschillende taken uitvoeren. pull downloadt de huidige image voor elke tag die in het bestand is gedefinieerd. up -d detecteert vervolgens dat de image-ID van de service niet langer overeenkomt met de draaiende container en maakt deze opnieuw aan. Bij het standaard missing pull-beleid worden gecachte tags hergebruikt, met uitzondering van latest, die altijd opnieuw wordt opgehaald. 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 adviseert een zelfgehoste AFFiNE-werkruimte om de applicatie- en migratie-image vast te pinnen op dezelfde digest. Pinnen verandert een upgrade bovendien in een bewuste wijziging van de tag, gevolgd door diezelfde pull- en recreate-procedure. Bij een stack die de database migreert tijdens het opstarten, is het raadzaam om voor beide commando's een dump bij de hand te hebben; dit is de procedure die een zelfgehoste Chatwoot-supportdesk volgt bij elke versie-update.

build is van toepassing op services die een build:-sectie declareren, inclusief services die ook een image: declareren. up -d --build bouwt en start in één stap; dit is de gebruikelijke cyclus tijdens het aanpassen van code. Gebruik --no-cache alleen wanneer een gecachte laag duidelijk verouderd is, omdat dit elke laag vanaf nul opnieuw opbouwt. Sommige projecten bieden beide routes aan vanuit één gekloonde repository; in dat geval zijn de twee cycli alternatieve updatepaden: een zelfgehoste openGym-workouttracker gebruikt docker compose up -d --build om zijn vastgepinde checkout te bouwen, omdat het pullen van de latest-images een nieuwere release kan opleveren dan die specifieke checkout.

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 hier 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 gewenste overzicht wanneer services met elkaar communiceren en de volgorde van gebeurtenissen van belang is. Geef een servicenaam op om het overzicht te beperken. --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 binnen de container draait". ls verlaat de huidige map en toont actieve Compose-projecten op de host met hun status; voeg -a toe om ook gestopte projecten op te nemen.

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 een exec-sessie te starten. 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. Sommige op Alpine gebaseerde images bevatten bash, waaronder de officiële PostgreSQL Alpine-image; wanneer dit ontbreekt, luidt 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 zien 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

Standaard plaatst Compose elke service op één projectnetwerk, waarbij elke servicenaam fungeert als een DNS-naam binnen dat netwerk. Het uitvoeren van getent hosts db binnen web, wanneer de image getent bevat, controleert de naamresolutie; het test niet of db verbindingen accepteert. Als de naam wordt omgezet maar de verbinding wordt geweigerd, controleer dan of de server draait en luistert op het gevraagde adres en de gevraagde poort; het binden aan alleen 127.0.0.1 is een mogelijke oorzaak. Dezelfde grens verklaart waarom een container die buiten het project is gestart, hetzij door docker run of als een eigen stack, een gedeeld netwerk nodig heeft om een servicenaam zoals jellyfin op te lossen. Dit is het eerste wat u moet controleren wanneer een Halcyon front-end voor uw Jellyfin-bibliotheek de server waarnaar deze verwijst niet kan bereiken. 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; dit voorkomt gokwerk wanneer de mapping afkomstig is van een variabele. Het publiceren van een poort schrijft ook een firewallregel die Docker zelf beheert, en die regel staat vóór uw eigen regels. Hierdoor kan een service waarvan u dacht dat deze privé was, openstaan voor het internet. Dat scenario wordt behandeld in waarom gepubliceerde Docker-poorten ufw omzeilen. Het is veiliger om die poorten niet te publiceren en in plaats daarvan één authenticerende proxy op het projectnetwerk voor de services te plaatsen; dit is wat het draaien van Authentik als single sign-on laag u biedt.

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 vormt slechts een deel van een backup-inventaris: bind mounts en configuratiebestanden moeten ook worden gecontroleerd. Wanneer de volumes onvervangbare gegevens bevatten, is het exacte backup-commando net zo belangrijk als de lijst; 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 gedeclareerde benoemde volumes, met uitzondering van externe volumes, evenals anonieme volumes die aan de containers zijn gekoppeld, samen met de containers zelf. Dit is het juiste commando voor het afbreken van een testomgeving en het verkeerde commando 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 blijven behouden, 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 draaien, en docker compose ps neemt standaard ook actieve wees-containers mee.

docker system df toont waar de schijfruimte is gebleven voordat u iets verwijdert. Het geeft een overzicht van images, containers, lokale volumes en build-cache, inclusief de hoeveelheid ruimte die per onderdeel kan worden vrijgemaakt. image prune -a verwijdert elke image die door geen enkele container wordt gebruikt, ongeacht of deze een tag heeft. Op een systeem waar meerdere versies van een grote image zijn binnengehaald, levert dit meestal de grootste winst op. builder prune verwijdert standaard zwevende build-cache; voeg -a toe om alle ongebruikte build-cache te verwijderen.

Geen van deze commando's raakt een named volume aan. docker volume prune --all, docker compose down -v en docker volume rm verwijderen named volumes. Het eenvoudige docker volume prune verwijdert alleen anonieme volumes.

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, alhoewel de regels voor lijsten en maps verschillen. Lees daarom 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. Om de stack na een herstart terug te krijgen, gebruikt u een restart policy of een unit die Compose voor u uitvoert, zoals beschreven in Compose-stacks starten bij het opstarten.

FAQ

Wat heeft docker-compose met een koppelteken vervangen?

Compose V2 en V5, aangeroepen als docker compose met een spatie. Op Linux is Compose een afzonderlijk geïnstalleerde plugin; Ubuntu 24.04 LTS biedt nog steeds de V1 Python-tool aan in de universe-repository. Als de vorm met spatie niet beschikbaar is, configureer dan de repository van Docker en installeer het pakket docker-compose-plugin. Werk oude scripts bij naar de vorm met 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 in 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 en daarna 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 meer overeenkomt met de container. Het uitvoeren van up -d op zichzelf volgt het pull-beleid: het standaardbeleid missing hergebruikt gecachte images, behalve voor latest, die altijd wordt opgehaald.

Welke opschooncommando's zijn veilig op een live server?

docker system df rapporteert schijfgebruik zonder iets te verwijderen; docker image prune -a en docker builder prune verwijderen ongebruikte images en de build-cache, waardoor draaiende services blijven werken en benoemde volumes onaangetast blijven. Het gevaarlijke duo is docker compose down -v, dat de gedeclareerde niet-externe benoemde volumes en gekoppelde anonieme volumes van het project zonder waarschuwing verwijdert, en docker volume prune --all, dat ongebruikte lokale volumes verwijdert, inclusief benoemde volumes, na een enkele y/N-prompt, of zonder enige prompt met -f. 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 servicedefinitie web, slaat de afhankelijkheden over en verwijdert de container wanneer u afsluit. Gebruik in plaats daarvan exec wanneer de container al draait, omdat exec uw commando uitvoert in de live container en u de status laat zien waarin de service zich daadwerkelijk bevindt.