Docker Compose: differenza tra stop e down

La risposta breve

docker compose stop arresta i container e li lascia sul disco. docker compose down li arresta, quindi elimina i container e la rete creata da Compose per il progetto. Nessuno dei due comandi modifica un volume denominato. Il database viene eliminato solo quando si aggiunge -v, come in docker compose down -v, che rimuove i volumi denominati dichiarati nella sezione volumes del file Compose.

Questa è tutta la differenza in un paragrafo. Il resto della guida lo dimostra con un volume PostgreSQL che rimane dopo un down e scompare con un down -v. Inoltre, spiega i due casi in cui è necessario usare --force-recreate.

docker compose stop: i container restano

stop invia SIGTERM al processo principale di ogni container, attende, quindi invia SIGKILL se il processo è ancora in esecuzione. L'attesa predefinita è di 10 secondi e -t la modifica. Non viene eliminato nulla. Il container mantiene il proprio ID, il proprio layer scrivibile, la propria prenotazione IP e i propri log.

docker compose stop
docker compose ps -a

docker compose ps da solo mostra solo i container in esecuzione, quindi dopo stop stampa una tabella vuota e si può pensare che i container siano stati eliminati. ps -a include quelli arrestati; qui vedrai Exited (0) accanto a ogni servizio. Riavviali con docker compose start, che riutilizza esattamente gli stessi container.

Poiché i container esistono ancora, tutto ciò che è stato scritto al loro interno al di fuori di un volume è ancora presente. Questo include un pacchetto installato manualmente con docker compose exec e un file di configurazione modificato all'interno del container. Questo è il motivo pratico per preferire stop durante il debug: puoi riavviare mantenendo lo stesso stato.

docker compose down: i container e le reti vengono rimossi

down arresta i container e poi li rimuove, insieme alla rete predefinita che Compose ha creato per il progetto. La documentazione di Docker lo descrive come un comando che arresta i container e rimuove i container, le reti, i volumi e le immagini creati da up, ma la rimozione di volumi e immagini avviene solo quando si richiedono esplicitamente con -v e --rmi.

docker compose down
docker compose ps -a
docker network ls

Dopo down, ps -a non restituisce alcun output per il progetto e la rete <project>_default non esiste più. Il nome del progetto deriva dal nome della directory, a meno che non si imposti name: nel file Compose o non si passi -p. Ogni modifica apportata nel livello scrivibile di un container è ora irrecuperabile. Considerare quindi down un comando che elimina il container e conserva i dati inseriti nei volumi.

Se lo si esegue nella directory sbagliata, viene restituito no configuration file provided: not found. Compose non sa a quale progetto ci si riferisca e quindi rifiuta il comando. Usare docker compose -f /srv/myapp/compose.yaml down quando non ci si trova nella directory del progetto.

docker compose down elimina i miei volumi?

No. Un volume denominato dichiarato nella chiave di primo livello volumes continua a esistere oltre down e oltre il container a cui era collegato. Questo è il timore più comune relativo al comando. La risposta resta valida in Compose v2.

Configura uno stack da usare per i test. Inserisci questo contenuto in compose.yaml, in una directory vuota chiamata voltest.

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

volumes:
  pgdata:

Avvialo e scrivi una riga che potrai riconoscere in seguito.

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');"

Ora elimina il container e controlla il volume.

docker compose down
docker volume ls

L'output elenca ancora voltest_pgdata. Il container non esiste più, ma i dati sono ancora presenti. Riavvia lo stack e leggi la riga.

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

Ottieni una riga contenente survived. Il nuovo container è un container diverso, con un ID diverso, collegato allo stesso volume. Per una panoramica più ampia, la guida di base su Compose illustra la differenza tra i volumi denominati e i bind mount, oltre a spiegare dove si trova realmente ciascuno di essi sull'host.

Cosa elimina esattamente down -v

-v (forma estesa --volumes) rimuove i volumi denominati dichiarati nella sezione volumes del file Compose, oltre ai volumi anonimi collegati ai container. Eseguirlo sullo stesso stack.

docker compose down -v
docker volume ls

voltest_pgdata non è più elencato. Avviare di nuovo lo stack: l'entrypoint di Postgres trova una directory dei dati vuota e inizializza quindi un nuovo cluster. Il log del container lo indica chiaramente.

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

La presenza di questo blocco in uno stack in esecuzione da mesi indica che il volume è stato rimosso. La tabella marker è scomparsa e l'unico modo per ripristinarla è usare un backup.

Alcuni dati non vengono mai rimossi da -v. Un bind mount corrisponde a un percorso dell'host, quindi Docker lo smonta soltanto e i file restano al loro posto. Un volume contrassegnato con external: true è dichiarato come appartenente a qualcosa di esterno a questo progetto e Compose non lo rimuove mai. Un volume denominato eliminato dal file Compose prima di eseguire down -v non è più dichiarato, quindi Compose non sa di doverlo rimuovere e lo lascia come orfano per docker volume prune.

Quest'ultimo caso si verifica spesso durante un refactoring. Rimuovere un servizio e il relativo volume dal file, quindi eseguire down -v: il volume sopravvive perché il file non lo menziona più. Eseguire down -v prima di modificare il file, non dopo.

Quando serve davvero --force-recreate

docker compose up -d non ricrea tutto ogni volta. Compose memorizza come etichetta sul container un hash della configurazione risolta di ogni servizio. Se l'hash e l'ID dell'immagine corrispondono, il container viene lasciato invariato e viene restituito Container voltest-db-1 Running invece di Recreated. Questo comportamento è quasi sempre quello desiderato, perché rende sicuro eseguire up -d ripetutamente.

Per lo stesso motivo, alcune modifiche sembrano non avere effetto. Compose calcola l'hash della definizione risolta del servizio, non del contenuto dei file a cui fa riferimento. Se un file di configurazione viene montato nel container e letto una sola volta all'avvio, modificarlo non attiva una ricreazione, perché il percorso del mount non è cambiato. Il servizio continua a funzionare con i valori letti all'avvio.

docker compose up -d --force-recreate

Arresta e rimuove ogni container, quindi ne crea uno nuovo dalla stessa definizione. Usalo dopo aver modificato un file di configurazione montato e quando un container è entrato in uno stato che non riesci a spiegare. I volumi non vengono modificati, quindi un database sopravvive a una ricreazione forzata. Per usare un'immagine più recente con lo stesso tag, devi eseguire anche il pull.

docker compose pull
docker compose up -d

pull recupera il nuovo ID dell'immagine e up -d rileva quindi che l'ID dell'immagine è diverso da quello del container in esecuzione, ricreandolo autonomamente. Aggiungere --force-recreate senza pull crea un nuovo container dalla stessa immagine precedente. Per questo la frase «ho eseguito una ricreazione forzata, ma la versione è ancora quella vecchia» è una lamentela così comune.

docker compose restart non esegue nessuna di queste operazioni. Riavvia i container esistenti e non rilegge affatto il file Compose, quindi una variabile d'ambiente o una mappatura di porta modificata non viene applicata. Se hai modificato il file, usa up -d.

Il modello mentale da mantenere

I container sono sostituibili. Un container è un processo con un sottile livello scrivibile e Compose può crearne uno identico dal file in circa un secondo. I volumi non sono sostituibili perché contengono l'unica copia dello stato che nessun file nel repository può rigenerare.

Ogni comando di Compose corrisponde a questa distinzione. stop e start mantengono il container. down e up sostituiscono il container e mantengono il volume. down -v è l'unico comando di routine che rimuove lo stato, per questo richiede un flag esplicito. Prima di eseguirlo su un sistema reale, verifica di avere un backup che hai ripristinato almeno una volta.

La stessa logica si applica ai secret. Una password impostata tramite POSTGRES_PASSWORD viene letta solo la prima volta che il database viene inizializzato. Di conseguenza, modificarla nel file dell'ambiente ed eseguire up -d produce password authentication failed for user "postgres". Il container è nuovo e il volume è quello precedente, che contiene ancora la vecchia password. Come Compose risolve i file env e i secret spiega quale livello ha la precedenza quando la stessa variabile viene impostata due volte.

Modalità di errore e messaggi visualizzati

no configuration file provided: not found indica che Compose è in esecuzione in una directory che non contiene né compose.yaml né docker-compose.yml. Specificare -f con il percorso completo.

network voltest_default has active endpoints su down indica che un container esterno a questo progetto è collegato alla rete del progetto, in genere perché è stato avviato manualmente con docker run --network. Rimuovere il container, quindi eseguire di nuovo down.

Found orphan containers ([voltest-old-1]) for this project viene visualizzato dopo aver rinominato o eliminato un servizio. Il vecchio container contiene ancora l'etichetta del progetto. docker compose down --remove-orphans le cancella ed è sicuro eseguirlo su uno stack integro.

Error response from daemon: remove voltest_pgdata: volume is in use durante un'operazione manuale docker volume rm indica che un container fa ancora riferimento al volume, anche se è arrestato. Eseguire prima docker compose down, quindi rimuovere il volume, oppure usare semplicemente down -v. In un progetto più grande, uno stack Compose con più servizi mostra quanti volumi può accumulare un singolo progetto.

FAQ

Il comando docker compose down elimina il database?

No, se il database risiede in un volume denominato o in un bind mount. down rimuove i container e la rete del progetto, mentre il volume resta sul disco con tutti i dati. Il comando docker compose up -d successivo collega un nuovo container allo stesso volume e i dati sono ancora disponibili. Solo docker compose down -v rimuove i volumi denominati, e solo quelli dichiarati nella sezione volumes del file Compose.

Qual è la differenza tra stop e down per un container che voglio riutilizzare?

stop conserva il container, quindi docker compose start ripristina lo stesso container con lo stesso layer scrivibile. Tutto ciò che hai installato o modificato manualmente nel container resta disponibile. down elimina il container, quindi il comando up -d successivo ne crea uno nuovo dall'immagine e perde queste modifiche manuali. Durante il debug, usa stop.

Come posso rimuovere tutto ciò che ha creato un progetto Compose?

docker compose down -v --rmi all --remove-orphans rimuove i container, la rete del progetto, i volumi denominati dichiarati nel file, le immagini usate dai servizi e qualsiasi container ancora contrassegnato con il nome del progetto. Non modifica i bind mount né i volumi contrassegnati con external: true. Prima di eseguire il comando, controlla cosa stai per perdere con docker volume ls.

Perché il mio container ignora la modifica apportata a un file di configurazione montato?

Compose decide se ricreare un container confrontando un hash della definizione del servizio risolta. Questo hash non include il contenuto di un file montato. Il percorso non è cambiato, quindi Compose lascia in esecuzione il container con i valori letti all'avvio. Esegui docker compose up -d --force-recreate per creare un nuovo container che rilegga il file.

Perché il nuovo POSTGRES_PASSWORD non funziona dopo la modifica?

L'immagine Postgres legge POSTGRES_PASSWORD solo quando inizializza una directory di dati vuota. Il volume contiene già un cluster inizializzato, quindi la variabile viene ignorata e la vecchia password resta valida. Visualizzerai password authentication failed for user "postgres". Modifica la password con ALTER USER all'interno del database in esecuzione oppure accetta di perdere i dati e ricomincia con docker compose down -v.