Docker Compose down versus stop: wat blijft behouden?

Het korte antwoord

docker compose stop stopt de containers en laat ze op schijf staan. docker compose down stopt ze en verwijdert daarna de containers en het netwerk dat Compose voor het project heeft aangemaakt. Geen van beide opdrachten heeft invloed op een named volume. Uw database verdwijnt pas wanneer u -v toevoegt, zoals in docker compose down -v. Daarmee worden de named volumes verwijderd die in de sectie volumes van het Compose-bestand zijn gedeclareerd.

Dat is het volledige verschil in één alinea. In de rest van deze handleiding wordt dit aangetoond met een Postgres-volume dat u na down kunt zien blijven bestaan en dat onder down -v verdwijnt. Ook worden de twee gevallen uitgelegd waarin u --force-recreate nodig hebt.

docker compose stop: de containers blijven bestaan

stop stuurt SIGTERM naar het hoofdproces in elke container, wacht vervolgens en stuurt SIGKILL als het proces nog actief is. De standaardwachttijd is 10 seconden en -t wijzigt deze. Er wordt niets verwijderd. De container behoudt zijn ID, zijn beschrijfbare laag, zijn IP-reservering en zijn logboeken.

docker compose stop
docker compose ps -a

docker compose ps toont alleen actieve containers. Na stop wordt daarom een lege tabel weergegeven, waardoor men denkt dat de containers zijn verwijderd. ps -a omvat ook gestopte containers. Daar ziet u naast elke service Exited (0). Start ze opnieuw met docker compose start. Daarbij worden exact dezelfde containers opnieuw gebruikt.

Omdat de containers nog bestaan, blijft alles wat daarin buiten een volume is geschreven behouden. Dit geldt ook voor een pakket dat u handmatig met docker compose exec hebt geïnstalleerd en voor een configuratiebestand dat u in de container hebt bewerkt. Daarom verdient stop de voorkeur tijdens het debuggen: u kunt opnieuw starten met dezelfde toestand.

docker compose down: containers en netwerken worden verwijderd

down stopt de containers en verwijdert ze daarna, samen met het standaardnetwerk dat Compose voor het project heeft aangemaakt. In de Docker-documentatie wordt dit beschreven als het stoppen van containers en het verwijderen van containers, netwerken, volumes en images die door up zijn aangemaakt. De onderdelen voor volumes en images worden echter alleen uitgevoerd als u hierom vraagt met -v en --rmi.

docker compose down
docker compose ps -a
docker network ls

Na down geeft ps -a niets meer weer voor het project en is het netwerk <project>_default verwijderd. De projectnaam is standaard afkomstig van de mapnaam, tenzij u name: instelt in het Compose-bestand of -p doorgeeft. Elke wijziging die u in de schrijfbare laag van een container hebt aangebracht, kan nu niet meer worden hersteld. Beschouw down daarom als een opdracht die de container verwijdert, maar de gegevens bewaart die u in volumes hebt geplaatst.

Als u de opdracht in de verkeerde map uitvoert, krijgt u no configuration file provided: not found. Compose weet dan niet welk project u bedoelt en weigert de opdracht uit te voeren. Gebruik docker compose -f /srv/myapp/compose.yaml down wanneer u zich niet in de projectmap bevindt.

Verwijdert docker compose down mijn volumes?

Nee. Een benoemd volume dat onder de top-level-sleutel volumes is gedeclareerd, blijft bestaan nadat down is uitgevoerd en nadat de container waaraan het was gekoppeld, is verwijderd. Dit is de meest voorkomende zorg over deze opdracht. Het antwoord blijft hetzelfde in Compose v2.

Maak een stack die u kunt testen. Plaats dit in compose.yaml in een lege map met de naam voltest.

services:
  db:
    image: postgres:16.4
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Start de stack en schrijf een rij die u later kunt herkennen.

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "create table marker (note text);"
docker compose exec -T db psql -U postgres -c "insert into marker values ('survived');"

Verwijder nu de container en controleer het volume.

docker compose down
docker volume ls

De uitvoer vermeldt voltest_pgdata nog steeds. De container is verwijderd, maar de gegevens niet. Start de stack opnieuw en lees de rij.

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "select * from marker;"

U krijgt één rij met survived. De nieuwe container is een andere container met een andere ID, gekoppeld aan hetzelfde volume. Raadpleeg voor het volledige overzicht de handleiding over de basisbeginselen van Compose, waarin benoemde volumes worden vergeleken met bind mounts en wordt uitgelegd waar elk type werkelijk op de host staat.

Wat -v precies verwijdert

-v (de lange vorm --volumes) verwijdert de benoemde volumes die in de sectie volumes van het Compose-bestand zijn gedeclareerd, plus anonieme volumes die aan de containers zijn gekoppeld. Voer dit uit voor dezelfde stack.

docker compose down -v
docker volume ls

voltest_pgdata wordt niet meer vermeld. Start de stack opnieuw. Het Postgres-entrypoint vindt dan een lege datamap en initialiseert een nieuw cluster. Het containerlog vermeldt dit expliciet.

The files belonging to this database system will be owned by user "postgres".
PostgreSQL init process complete; ready for start up.

Als u dat blok ziet bij een stack die al maanden actief is, betekent dit dat het volume is verwijderd. Uw tabel marker is verdwenen. Een back-up is de enige manier om deze te herstellen.

Sommige opslag wordt nooit door -v verwijderd. Een bind mount verwijst naar een pad op de host. Docker koppelt dit pad daarom alleen los en uw bestanden blijven staan. Een volume met de markering external: true is gedeclareerd als behorend tot iets buiten dit project. Compose verwijdert het daarom nooit. Een benoemd volume dat u vóór het uitvoeren van down -v uit het Compose-bestand hebt verwijderd, is niet meer gedeclareerd. Compose weet dan niet dat het moet worden verwijderd en laat het als wees achter voor docker volume prune.

Dat laatste geval leidt tijdens een refactor vaak tot problemen. Verwijder een service en het bijbehorende volume uit het bestand en voer vervolgens down -v uit. Het volume blijft bestaan omdat het bestand er niet meer naar verwijst. Voer down -v uit voordat u het bestand bewerkt, niet erna.

Wanneer u --force-recreate daadwerkelijk nodig hebt

docker compose up -d bouwt niet elke keer alles opnieuw op. Compose slaat een hash van de opgeloste configuratie van elke service op als label op de container. Als de hash en de image-ID overeenkomen, laat Compose de container ongewijzigd en krijgt u Container voltest-db-1 Running in plaats van Recreated. Dat is bijna altijd het gewenste gedrag, omdat up -d daardoor veilig herhaaldelijk kan worden uitgevoerd.

Daarom lijken sommige wijzigingen niets te doen. Compose maakt een hash van de opgeloste servicedefinitie, niet van de inhoud van de bestanden waarnaar die definitie verwijst. Een configuratiebestand dat in de container is aangekoppeld en bij het opstarten eenmaal wordt ingelezen, veroorzaakt geen nieuwe aanmaak wanneer u het bestand bewerkt, omdat het aankoppelpad niet is gewijzigd. De service blijft actief met de waarden die bij het opstarten zijn ingelezen.

docker compose up -d --force-recreate

Hiermee wordt elke container gestopt en verwijderd en wordt een nieuwe container gemaakt op basis van dezelfde definitie. Gebruik dit na een wijziging in een aangekoppeld configuratiebestand en wanneer een container in een toestand is geraakt die u niet kunt verklaren. Volumes blijven ongewijzigd, dus een database blijft behouden bij een geforceerde nieuwe aanmaak. Als u een nieuwere image met dezelfde tag wilt ophalen, hebt u ook de pull nodig.

docker compose pull
docker compose up -d

pull haalt de nieuwe image-ID op. Vervolgens ziet up -d dat de image-ID afwijkt van die van de actieve container en maakt het de container zelfstandig opnieuw aan. Als u --force-recreate toevoegt zonder pull, krijgt u een nieuwe container met dezelfde oude image. Daarom is "ik heb de container geforceerd opnieuw aangemaakt en het is nog steeds de oude versie" een veelgehoorde klacht.

docker compose restart doet niets van dit alles. Het herstart de bestaande containers en leest het Compose-bestand helemaal niet opnieuw in. Een gewijzigde omgevingsvariabele of gewijzigde poorttoewijzing wordt daarom niet toegepast. Als u het bestand hebt bewerkt, gebruikt u up -d.

Het mentale model dat u moet aanhouden

Containers zijn vervangbaar. Een container is een proces plus een dunne beschrijfbare laag. Compose kan in ongeveer een seconde een identieke container maken op basis van het bestand. Volumes zijn niet vervangbaar, omdat ze de enige kopie van de status bevatten die geen bestand in uw repository opnieuw kan genereren.

Elk Compose-werkwoord sluit aan op deze scheiding. stop en start behouden de container. down en up vervangen de container en behouden het volume. down -v is de enige reguliere opdracht die de status verwijdert. Daarom is hiervoor een expliciete vlag nodig. Controleer voordat u deze opdracht op een echte omgeving uitvoert of u een back-up hebt die u ten minste eenmaal hebt teruggezet.

Dezelfde logica geldt voor secrets. Een wachtwoord dat via POSTGRES_PASSWORD is ingesteld, wordt alleen gelezen wanneer de database voor het eerst wordt geïnitialiseerd. Als u het wachtwoord in uw omgevingsbestand wijzigt en up -d uitvoert, krijgt u password authentication failed for user "postgres". De container is nieuw en het volume is oud. Het oude volume bevat nog steeds het oude wachtwoord. Hoe Compose env-bestanden en secrets oplost legt uit welke laag voorrang krijgt wanneer dezelfde variabele tweemaal is ingesteld.

Foutmodi en de meldingen die u ziet

no configuration file provided: not found betekent dat Compose wordt uitgevoerd in een directory zonder compose.yaml en zonder docker-compose.yml. Geef -f op met het volledige pad.

network voltest_default has active endpoints op down betekent dat een container buiten dit project aan het projectnetwerk is gekoppeld. Meestal is dit een container die handmatig met docker run --network is gestart. Verwijder die container en voer down opnieuw uit.

Found orphan containers ([voltest-old-1]) for this project verschijnt nadat u een service hebt hernoemd of verwijderd. De oude container bevat het projectlabel nog. Met docker compose down --remove-orphans verwijdert u deze labels. Dit is veilig op een gezonde stack.

Error response from daemon: remove voltest_pgdata: volume is in use bij een handmatige docker volume rm betekent dat een container nog naar het volume verwijst, ook als deze is gestopt. Voer eerst docker compose down uit en verwijder daarna het volume, of gebruik gewoon down -v. In een groter project laat een Compose-stack met meerdere services zien hoeveel volumes één project kan verzamelen.

FAQ

Verwijdert docker compose down mijn database?

Niet als de database in een named volume of een bind mount staat. down verwijdert de containers en het projectnetwerk. Het volume blijft met de gegevens intact op de schijf staan. Met de volgende docker compose up -d wordt een nieuwe container aan hetzelfde volume gekoppeld en zijn de gegevens weer beschikbaar. Alleen docker compose down -v verwijdert named volumes, en alleen de volumes die in de sectie volumes van het Compose-bestand zijn gedeclareerd.

Wat is het verschil tussen stop en down voor een container die ik opnieuw wil gebruiken?

stop behoudt de container. Met docker compose start komt u daardoor terug in dezelfde container, met dezelfde beschrijfbare laag. Alles wat u handmatig in de container hebt geïnstalleerd of gewijzigd, blijft aanwezig. down verwijdert de container. De volgende up -d maakt daarom een nieuwe container op basis van de image, waardoor die handmatige wijzigingen verloren gaan. Gebruik tijdens het debuggen stop.

Hoe verwijder ik alles wat een Compose-project heeft gemaakt?

docker compose down -v --rmi all --remove-orphans verwijdert de containers, het projectnetwerk, de in het bestand gedeclareerde named volumes, de images die de services hebben gebruikt en alle containers die nog met de projectnaam zijn gelabeld. Bind mounts en volumes met de markering external: true worden niet gewijzigd. Controleer met docker volume ls wat u gaat verwijderen voordat u de opdracht uitvoert.

Waarom negeert mijn container de wijziging die ik in een gekoppeld configuratiebestand heb aangebracht?

Compose bepaalt of een container opnieuw moet worden gemaakt door een hash van de opgeloste servicedefinitie te vergelijken. De inhoud van een gekoppeld bestand maakt geen deel uit van die hash. Het pad is niet gewijzigd. Daarom laat Compose de container actief met de waarden die bij het opstarten zijn ingelezen. Voer docker compose up -d --force-recreate uit om een nieuwe container te maken die het bestand opnieuw inleest.

Waarom werkt mijn nieuwe POSTGRES_PASSWORD niet nadat ik deze heb gewijzigd?

De Postgres-image leest POSTGRES_PASSWORD alleen wanneer een lege gegevensdirectory wordt geïnitialiseerd. Uw volume bevat al een geïnitialiseerd cluster. Daarom wordt de variabele genegeerd en blijft het oude wachtwoord van kracht. U ziet password authentication failed for user "postgres". Wijzig het wachtwoord met ALTER USER in de actieve database, of accepteer dat de gegevens verloren gaan en begin opnieuw met docker compose down -v.