Comandi Docker Compose: guida rapida per server

I comandi Compose che utilizzerai realmente

Docker Compose include decine di sottocomandi. Il lavoro quotidiano su un server ne richiede circa una dozzina. Questa pagina li raggruppa in base all'attività svolta, fornisce una motivazione chiara per ciascuno e rimanda all'approfondimento quando un comando nasconde delle insidie.

Tutto ciò che è descritto qui utilizza Compose V2 o V5: docker compose con lo spazio, non il vecchio script docker-compose. Entrambi sono plugin Go; su Linux, il plugin Compose viene installato separatamente da Docker Engine. Ubuntu 24.04 LTS offre ancora il vecchio strumento Python V1 come docker-compose versione 1.29.2-6ubuntu1 nel repository universe. Verifica con docker compose version. Se il comando non è disponibile, configura il repository di Docker e installa il pacchetto docker-compose-plugin.

Ogni comando riportato di seguito viene eseguito dalla directory che contiene il tuo compose.yaml; Compose utilizza il nome di tale directory come nome predefinito del progetto, a meno che non venga sovrascritto. Senza -f o COMPOSE_FILE, Compose cerca un file di configurazione nella directory di lavoro e nelle sue directory superiori; pertanto, eseguendo il comando un livello sopra, troverai lo stack solo se il file si trova ancora in quel percorso di ricerca. Se il formato del file è nuovo per te, inizia con un primo file Compose su una VPS e torna qui per i comandi.

Ciclo di vita: i quattro comandi che digiti e quello che rimuove i container

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

up -d crea la rete, crea i container, li avvia e termina. Il comando restituisce il controllo dopo l'avvio dei container senza attendere che l'applicazione sia pronta; per questo motivo, uno script di deploy che esegue subito dopo un probe curl fallisce spesso al primo tentativo. up -d --wait attende che i servizi dotati di healthcheck diventino integri e che quelli senza siano in esecuzione; un servizio non integro o un --wait-timeout scaduto causano un codice di uscita diverso da zero. Il flag è efficace solo quanto il controllo che lo supporta, quindi scrivi un healthcheck di cui Compose possa fidarsi prima di farvi affidamento nell'automazione.

stop arresta i container mantenendoli, così start ripristina gli stessi container con lo stesso layer scrivibile. down li arresta e successivamente rimuove i container e la rete del progetto. Qualsiasi dato scritto all'interno del container, al di fuori di un volume, viene eliminato. Questo è il malinteso più costoso in Compose, e la differenza completa tra down e stop spiega dove si annidano i rischi.

restart non è un ricaricamento. Arresta e avvia lo stesso container con la configurazione già esistente, pertanto una variabile d'ambiente modificata, un nuovo tag di immagine o un mapping di porta editato non hanno alcun effetto. Per applicare una modifica ai file, esegui nuovamente up -d. Compose confronta ogni servizio con il relativo container in esecuzione e ricrea quelli la cui configurazione o immagine è cambiata.

Applicare una modifica: ricreare, scaricare o ricostruire

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 riutilizza i container in esecuzione quando la loro configurazione e l'immagine sono invariate; il download e la compilazione delle immagini seguono la policy di pull del servizio. --force-recreate ignora tale confronto e sostituisce ogni container anche quando la configurazione è identica, rappresentando quindi il metodo più rapido per eliminare stati anomali all'interno del container.

La procedura esplicita di aggiornamento dell'immagine utilizza due comandi poiché eseguono operazioni distinte. pull scarica l'immagine corrente per ogni tag specificato nel file. up -d rileva quindi che l'ID dell'immagine del servizio non corrisponde più a quello del container in esecuzione e lo ricrea. Con la policy di pull predefinita missing, i tag memorizzati nella cache vengono riutilizzati, ad eccezione di latest, che viene sempre scaricato. Il rischio opposto si presenta in uno stack multi-servizio, dove scaricare latest per ogni servizio contemporaneamente può compromettere un'applicazione che funzionava dieci secondi prima; per questo motivo un workspace AFFiNE self-hosted raccomanda di bloccare l'immagine dell'applicazione e quella di migrazione allo stesso digest. Il blocco trasforma inoltre un aggiornamento in una modifica deliberata del tag, seguita dalla stessa procedura di pull e ricreazione; su uno stack che esegue la migrazione del database all'avvio, è opportuno disporre di un dump prima di eseguire entrambi i comandi, procedura che un help desk Chatwoot self-hosted segue per ogni incremento di versione.

build si applica ai servizi che dichiarano una sezione build:, inclusi i servizi che dichiarano anche un image:. up -d --build compila e avvia in un unico passaggio, che rappresenta il ciclo normale durante la modifica del codice. Ricorrere a --no-cache solo quando un layer memorizzato nella cache è chiaramente obsoleto, poiché ricostruisce ogni layer da zero. Alcuni progetti offrono entrambi i percorsi da un singolo repository clonato; in tal caso, i due cicli rappresentano percorsi di aggiornamento alternativi: un tracker di allenamento openGym self-hosted utilizza docker compose up -d --build per compilare il proprio checkout bloccato, poiché scaricare le sue immagini latest potrebbe avviare una release più recente rispetto a quel checkout.

Verifica dei processi in esecuzione

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 elenca solo i container in esecuzione. Un servizio che si è arrestato durante l'avvio non è visibile finché non si aggiunge -a; pertanto, un container assente da ps mentre ps -a lo mostra come Exited (1) è la condizione tipica di un fallimento all'avvio. Leggere il codice di uscita, quindi consultare i log.

logs -f segue tutti i servizi contemporaneamente e antepone a ogni riga il nome del servizio; questa è la visualizzazione necessaria quando i servizi comunicano tra loro e l'ordine degli eventi è rilevante. Specificare un servizio per restringere il campo. --tail=100 è utile per un container attivo da un mese, poiché l'impostazione predefinita stampa l'intera cronologia inondando il terminale. --since 15m risponde alla domanda tipica su cosa sia accaduto durante il riavvio appena eseguito.

top elenca i processi all'interno di ogni container, distinguendo tra "il container è in esecuzione" e "il processo al suo interno è in esecuzione". ls esce dalla directory corrente ed elenca i progetti Compose attivi sull'host con il relativo stato; aggiungere -a per includere i progetti arrestati.

Ottenere una shell all'interno di un servizio

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 esegue un comando all'interno di un container già attivo. run avvia un nuovo container basato sulla stessa definizione di servizio; questa è l'operazione necessaria quando il servizio non rimane attivo abbastanza a lungo per eseguire un exec. Abbina sempre run a --rm, poiché senza di esso ogni invocazione lascia dietro di sé un container arrestato; questi si accumulano finché docker compose ps -a non diventa illeggibile.

Prova sh prima di bash. Alcune immagini basate su Alpine includono bash, inclusa l'immagine ufficiale Alpine di PostgreSQL; quando è assente, l'errore riporta exec: "bash": executable file not found in $PATH. Aggiungere --no-deps a run ignora le dipendenze del servizio, evitando che un rapido controllo della configurazione avvii l'intero database.

run --rm web env è il modo più rapido per visualizzare l'ambiente effettivamente ricevuto da un servizio, dopo che ogni file .env, blocco environment: e variabile di shell sono stati uniti. Quando un valore risulta errato, la causa è solitamente l'ordine di unione, e come Compose risolve file env e secret spiega quale origine ha la priorità.

Reti, porte e risoluzione dei nomi

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

Per impostazione predefinita, Compose inserisce ogni servizio in una rete di progetto, dove il nome di ciascun servizio funge da nome DNS. Eseguire getent hosts db all'interno di web, quando l'immagine include getent, verifica la risoluzione dei nomi; non testa se db accetta connessioni. Se il nome viene risolto ma la connessione viene rifiutata, verificare che il server sia in esecuzione e in ascolto sull'indirizzo e sulla porta richiesti; il binding limitato a 127.0.0.1 è una possibile causa. Lo stesso limite spiega perché un container avviato al di fuori del progetto, tramite docker run o come stack indipendente, necessiti di una rete condivisa per risolvere un nome di servizio come jellyfin, che è il primo elemento da controllare quando un front-end Halcyon per la propria libreria Jellyfin non riesce a raggiungere il server a cui punta. Il resto del modello è descritto in come funzionano le reti Compose e il DNS dei servizi.

port web 80 stampa l'indirizzo host e la porta su cui è pubblicata la porta di un container, evitando di dover indovinare quando il mapping deriva da una variabile. Pubblicare una porta scrive anche una regola firewall gestita autonomamente da Docker; tale regola ha la precedenza sulle proprie, rendendo potenzialmente accessibile a Internet un servizio che si riteneva privato. Questo caso è trattato in perché le porte Docker pubblicate bypassano ufw. Lasciare tali porte non pubblicate e inserire un proxy di autenticazione sulla rete di progetto davanti ai servizi è la configurazione più sicura, che è ciò che si ottiene eseguendo Authentik come livello di single sign-on.

Volumi e dati

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

config --volumes stampa i volumi nominati dichiarati dal progetto, uno per riga. Tale elenco costituisce solo una parte dell'inventario di backup: è necessario verificare anche i bind mount e i file di configurazione. Quando i volumi contengono dati insostituibili, il comando di backup esatto è importante quanto l'elenco; per questo motivo il confronto tra PhotoPrism e Immich specifica i comandi di dump e copia necessari per ogni server fotografico. cp copia un file all'interno o all'esterno di un container senza aprire una shell, utilizzando la forma service:path sul lato che corrisponde al container.

down -v rimuove i volumi nominati dichiarati, ad eccezione di quelli esterni, oltre ai volumi anonimi collegati ai container e ai container stessi. È il comando corretto per smantellare uno stack di test, ma è errato per qualsiasi risorsa contenente dati importanti, poiché non prevede conferme né possibilità di annullamento. I bind mount sopravvivono a questa operazione, poiché risiedono nel filesystem dell'host. Questa differenza nel raggio d'azione è uno dei motivi per scegliere consapevolmente tra bind mount e volumi nominati.

Pulizia per liberare spazio su disco senza perdere dati

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

--remove-orphans elimina i container che appartengono al progetto ma non compaiono più nel file, situazione tipica dopo aver rinominato un servizio. Senza questo comando, tali container continuano a essere eseguiti e docker compose ps include i container orfani attivi per impostazione predefinita.

docker system df mostra l'occupazione del disco prima di procedere con l'eliminazione, suddividendo immagini, container, volumi locali e build cache con il relativo spazio recuperabile. image prune -a rimuove ogni immagine non utilizzata da alcun container, indipendentemente dalla presenza di tag; su un sistema che ha scaricato diverse versioni di un'immagine di grandi dimensioni, questa operazione solitamente garantisce il maggior recupero di spazio. builder prune rimuove la build cache orfana per impostazione predefinita; aggiungere -a per rimuovere l'intera build cache inutilizzata.

Nessuno di questi comandi agisce sui volumi denominati. docker volume prune --all, docker compose down -v e docker volume rm rimuovono i volumi denominati. Il comando docker volume prune semplice rimuove solo i volumi anonimi.

Controllare il file prima che causi problemi

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

config --quiet verifica il file e non produce output in caso di esito positivo, quindi è adatto a una fase di pre-deploy o a un hook Git. Il semplice comando config stampa il file completamente unito e interpolato. Questo consente di verificare che una variabile sia stata risolta e che un file di override sia stato applicato nell’ordine previsto. Una variabile non impostata viene visualizzata come valore vuoto, insieme all’avviso The "X" variable is not set. Defaulting to a blank string.

--dry-run è un’opzione globale, non un’opzione del sottocomando, quindi deve essere inserita prima di up. Stampa tutte le operazioni che Compose eseguirebbe senza apportare modifiche. Sono trenta secondi utili prima di un down su uno stack importante.

Lavorare con file, profili e progetti

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

Più flag -f vengono uniti in ordine; i file successivi sovrascrivono quelli precedenti chiave per chiave. Questo è il metodo standard per mantenere un file di base con un piccolo override per la produzione, sebbene le regole differiscano per liste e mappe. Leggi come Compose unisce più file prima di eseguire il debug di un comportamento inatteso.

--profile avvia i servizi contrassegnati con quel profilo insieme a quelli non contrassegnati, mantenendo gli strumenti di debug fuori da un normale up. -p imposta il nome del progetto, consentendo a due copie dello stesso stack di essere eseguite contemporaneamente con reti e nomi di volume separati. Per ripristinare lo stack dopo un riavvio si utilizza una policy di riavvio o una unit che esegue Compose automaticamente, come descritto in avviare stack Compose all'avvio del sistema.

FAQ

Cosa ha sostituito docker-compose con un trattino?

Compose V2 e V5, richiamati come docker compose con uno spazio. Su Linux, Compose è un plugin installato separatamente; Ubuntu 24.04 LTS offre ancora lo strumento Python V1 nel suo repository universe. Se la forma con lo spazio non è disponibile, configura il repository di Docker e installa il pacchetto docker-compose-plugin. Aggiorna i vecchi script alla forma con lo spazio invece di aggiungere un alias, poiché la V2 dispone di flag che la V1 non ha mai avuto.

Perché docker compose restart non rileva la mia modifica alla configurazione?

restart arresta e avvia il container esistente con la configurazione con cui è stato creato e non rilegge mai compose.yaml. Qualsiasi modifica a variabili d'ambiente, porte, volumi o al tag dell'immagine richiede docker compose up -d, che confronta ogni servizio con il suo container in esecuzione e ricrea quelli che differiscono. Aggiungi --force-recreate quando vuoi che la sostituzione avvenga anche se nulla nel file è cambiato.

Come aggiorno un servizio a un'immagine più recente?

Esegui docker compose pull, quindi docker compose up -d. Il comando pull recupera l'immagine corrente per ogni tag nel file e up -d ricrea qualsiasi servizio il cui ID immagine non corrisponde più al suo container. L'esecuzione di up -d da sola segue la policy di pull: la policy predefinita missing riutilizza le immagini memorizzate nella cache, ad eccezione di latest, che viene sempre scaricata.

Quali comandi di pulizia sono sicuri su un server attivo?

docker system df riporta l'utilizzo del disco senza eliminare nulla; docker image prune -a e docker builder prune rimuovono immagini inutilizzate e la cache di build, quindi i servizi in esecuzione continuano a funzionare e i volumi denominati rimangono intatti. La coppia pericolosa è docker compose down -v, che elimina i volumi denominati dichiarati nel progetto (non esterni) e i volumi anonimi collegati senza richiesta di conferma, e docker volume prune --all, che elimina i volumi locali inutilizzati, inclusi quelli denominati, dopo una singola richiesta y/N, o nessuna se si usa -f. Esegui prima docker compose config --volumes per sapere cosa è a rischio.

Posso eseguire un comando senza avviare l'intero stack?

Sì. docker compose run --rm --no-deps web sh avvia un singolo container dalla definizione del servizio web, salta le sue dipendenze e rimuove il container all'uscita. Usa invece exec quando il container è già in esecuzione, poiché exec esegue il comando all'interno del container attivo e mostra lo stato in cui si trova effettivamente il servizio.