Docker Compose: differenza tra command ed entrypoint
ENTRYPOINT avvia il programma e command fornisce gli argomenti. Scopri le 4 combinazioni di override in Compose e perché entrypoint cancella CMD.
Comando e entrypoint in Docker Compose: una sola regola
In Docker Compose, entrypoint: imposta il programma da eseguire e command: imposta gli argomenti da passare a quel programma. Il processo del container è costituito dall'elenco dell'entrypoint seguito dall'elenco del comando. Ogni altro comportamento descritto in questa pagina deriva da questa regola.
Queste due chiavi corrispondono a due istruzioni Dockerfile. entrypoint: sostituisce ENTRYPOINT dell'immagine. command: sostituisce CMD dell'immagine. Non sono indipendenti. È questo il punto che crea più difficoltà: impostando entrypoint: si elimina anche CMD dell'immagine. La specifica di Compose lo dichiara esplicitamente. Se entrypoint è diverso da null, Compose ignora il comando predefinito dell'immagine.
Leggi ciò che l'immagine dichiara già
Prima di sovrascrivere qualsiasi impostazione, verifica cosa include l'immagine.
docker image inspect --format '{{json .Config.Entrypoint}}' postgres:16
docker image inspect --format '{{json .Config.Cmd}}' postgres:16Ottieni ["docker-entrypoint.sh"] e ["postgres"], quindi il container esegue docker-entrypoint.sh postgres. Questo script crea la directory dei dati al primo avvio, legge le variabili POSTGRES_*, abbandona i privilegi passando all'utente postgres e infine esegue gli argomenti ricevuti. La decisione dipende interamente da quale parte vuoi modificare. Per passare un flag al database, sostituisci command:. Se sostituisci entrypoint:, tutta questa procedura di configurazione non viene eseguita.
Le quattro combinazioni, mostrate in una piccola immagine
Crea un'immagine il cui unico compito sia stampare l'elenco degli argomenti con cui è stata avviata.
FROM alpine:3.20
ENTRYPOINT ["/bin/echo", "ep"]
CMD ["cmd"]docker build -t argdemo .services:
demo:
image: argdemoEsegui docker compose up dopo ogni modifica e leggi l'unica riga che registra.
- Nessuna chiave impostata. Il processo è
/bin/echo ep cmde il log mostraep cmd. - Solo
command: ["cmd2"]. Il processo è/bin/echo ep cmd2. L'entrypoint non viene modificato; cambiano solo gli argomenti. - Solo
entrypoint: ["/bin/echo", "ep2"]. Il processo è/bin/echo ep2e il log mostraep2.cmddell'immagine scompare e non viene visualizzato alcun avviso. - Entrambe le chiavi impostate. Il processo è
/bin/echo ep2 cmd2. Questo è l'unico caso in cui controlli l'intero elenco degli argomenti.
Perché impostare entrypoint cancella il CMD dell'immagine
Il CMD di un'immagine viene definito come elenco di argomenti predefinito per il ENTRYPOINT di quell'immagine. Se si sostituisce l'entrypoint, quegli argomenti appartengono ora a un programma che non viene più eseguito. Per questo Compose li rimuove invece di costruire una riga di comando che l'autore dell'immagine non intendeva definire. Anche docker run --entrypoint si comporta allo stesso modo. Si tratta quindi di un comportamento di Docker, non di una particolarità di Compose.
La conseguenza è concreta. nginx:1.27 dichiara ENTRYPOINT ["/docker-entrypoint.sh"] e CMD ["nginx", "-g", "daemon off;"]. Impostare entrypoint: /custom-init.sh fa avviare lo script con un elenco di argomenti vuoto. Uno script che termina con il consueto exec "$@" non ha quindi nulla da eseguire con exec. Di conseguenza, exec non esegue alcuna operazione, lo script raggiunge l'ultima riga e il container termina con il codice 0, senza messaggi di errore. Specificare nuovamente gli argomenti:
services:
web:
image: nginx:1.27
entrypoint: /custom-init.sh
command: ["nginx", "-g", "daemon off;"]La regola da ricordare è questa: ogni volta che si imposta entrypoint:, decidere nella stessa modifica quale valore deve avere command:.
Sintassi exec e sintassi shell, e differenze rispetto a Compose
Un Dockerfile accetta due sintassi. CMD ["nginx", "-g", "daemon off;"] è la sintassi exec: il binario viene eseguito direttamente, senza usare una shell. CMD nginx -g "daemon off;" è la sintassi shell: Docker la riscrive come /bin/sh -c 'nginx -g "daemon off;"', quindi prima viene avviata una shell e il programma diventa un processo figlio.
Compose non applica la stessa regola, e questo può sorprendere. Una stringa in command: viene suddivisa in argomenti ed eseguita direttamente, senza un wrapper /bin/sh -c. La documentazione di riferimento di Compose lo specifica chiaramente: il campo command non viene eseguito nel contesto SHELL definito nell'immagine. Se servono funzionalità della shell, è quindi necessario invocarla esplicitamente.
Per questo command: echo "hello $$HOSTNAME" stampa il testo letterale hello $HOSTNAME. Nessuna shell ha interpretato la stringa, quindi nulla l'ha espansa. Se serve una shell, invocatela esplicitamente:
services:
demo:
image: alpine:3.20
command: /bin/sh -c 'echo "hello $$HOSTNAME"'Segnali, PID 1 e un arresto pulito con docker compose down
docker compose stop e docker compose down inviano il segnale di arresto del container al PID 1 all'interno di ogni container. Il segnale è SIGTERM, a meno che STOPSIGNAL dell'immagine o stop_signal: del servizio non ne specifichi un altro. Compose attende quindi fino a stop_grace_period e invia SIGKILL solo se il container è ancora in esecuzione. Il periodo di tolleranza predefinito è di 10 secondi.
PID 1 è un processo speciale in Linux. Il kernel non applica l'azione predefinita di un segnale a PID 1. Di conseguenza, un processo che non installa alcun gestore SIGTERM ignora SIGTERM quando viene eseguito come PID 1. Rimane in esecuzione per l'intero periodo di tolleranza e poi viene terminato forzatamente. Questo interrompe tutte le connessioni aperte o le transazioni non confermate.
La presenza di una shell davanti al programma rende questo comportamento più probabile, perché la shell è PID 1 e la maggior parte delle shell non inoltra i segnali a un processo figlio. Alcune shell sostituiscono se stesse con il comando finale in una stringa -c. In questi casi il programma può comunque diventare PID 1. Il comportamento dipende dalla shell e dalla stringa esatta, quindi non fare supposizioni. Verifica:
docker compose exec -T web cat /proc/1/cmdline | tr '\0' ' '; echoSe PID 1 viene visualizzato come /bin/sh -c ... invece del tuo programma, hai due possibilità. Usa la forma exec nell'immagine oppure mantieni la shell e trasferisci il controllo al processo con exec:
services:
web:
image: myapp:1.4
command: /bin/sh -c 'exec myapp --config /etc/myapp.toml'exec sostituisce il processo della shell con il tuo programma invece di creare un processo figlio. In questo modo il programma eredita PID 1 e riceve il segnale.
Alcuni programmi creano processi figli e non li raccolgono mai. Questo lascia processi zombie, perché PID 1 svolge anche il ruolo di processo di raccolta. Compose dispone di un'opzione specifica:
services:
web:
image: myapp:1.4
init: true
stop_grace_period: 30sinit: true esegue un processo init di dimensioni ridotte come PID 1. Questo processo inoltra i segnali al tuo programma e raccoglie i processi figli. stop_grace_period concede più tempo a un arresto effettivamente lento. Se il programma deve ricevere un segnale diverso, stop_signal: SIGQUIT modifica il segnale inviato da Compose. Per verificare cosa richiede già un'immagine, usa docker image inspect --format '{{.Config.StopSignal}}' nginx:1.27.
Se docker compose down impiega sempre dieci secondi per ogni servizio, significa che nulla gestisce SIGTERM. Risolvi questo problema prima di attribuire la causa agli strumenti e consulta la differenza tra docker compose down e stop per sapere cosa rimuove ciascun sottocomando.
La distinzione tra forma exec e forma shell ricorre anche in un altro punto. Un controllo di integrità scritto come test: ["CMD", "curl", "-f", "http://localhost/"] esegue direttamente il binario, mentre test: ["CMD-SHELL", "curl -f http://localhost/ || exit 1"] viene eseguito tramite una shell, in modo che || abbia effetto. Scrivere controlli di integrità Compose che rilevano correttamente gli errori illustra il resto di quel campo.
Aggiungere un flag a un'immagine ufficiale
Questo è il motivo principale per cui molti lettori sono arrivati qui. Vuoi aggiungere un flag a postgres senza interferire con lo script di inizializzazione.
services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- pgdata:/var/lib/postgresql/data
command: postgres -c max_connections=200 -c shared_buffers=256MB
volumes:
pgdata:È cambiato solo command:, quindi docker-entrypoint.sh continua a essere eseguito e continua a eseguire ciò che gli hai assegnato. Verifica il risultato invece di darlo per scontato:
docker compose up -d db
docker compose exec -T db psql -U postgres -c 'show max_connections;'L'output dovrebbe mostrare 200. Se mostra ancora 100, esegui docker compose config e verifica che command previsto sia presente nell'output risultante. Compose unisce i file di override sostituendo command completamente, non aggiungendovi contenuto. Di conseguenza, un secondo file che imposta anch'esso command: prevale senza generare errori.
Il ${POSTGRES_PASSWORD} precedente viene espanso da Compose sull'host a partire dal file .env, prima che il container venga creato. File di ambiente e secret in Compose spiega dove conservare questo valore in modo sicuro.
Eseguire una migrazione una tantum con docker compose run
docker compose run crea un nuovo container dalla stessa definizione del servizio e sostituisce il comando con quello specificato dopo il nome del servizio. Viene comunque eseguito l'entrypoint dell'immagine, quindi il container viene preparato esattamente come quello a esecuzione continua.
docker compose run --rm app python manage.py migrate--rmelimina il container al termine del comando. Senza questa opzione, ogni esecuzione lascia un container arrestato, visibile indocker compose ps -a.- Le porte non vengono pubblicate. Un container
runignoraports:del servizio, a meno che non si aggiunga--service-ports, quindi non può entrare in conflitto con il servizio già attivo. - Le dipendenze vengono avviate prima. Tutto ciò che è definito in
depends_onviene avviato prima del comando, mentre--no-depsdisabilita questo comportamento. - Al container viene assegnato un nome generato, ad esempio
myproject-app-run-9f2c1a, quindi non può entrare in conflitto con il container del servizio.
Per sostituire anche l'entrypoint, è disponibile un'opzione specifica:
docker compose run --rm --entrypoint /bin/sh app -c 'python manage.py migrate'L'elenco degli argomenti risultante è /bin/sh -c 'python manage.py migrate', perché le parole dopo il nome del servizio restano il comando. docker compose exec è l'altro strumento e funziona in modo diverso: esegue un processo all'interno di un container già attivo e ignora completamente entrypoint: e command:. Usare run per un'attività che richiede un container nuovo e exec per esaminare un container in esecuzione. Il promemoria dei comandi Compose mette a confronto gli altri sottocomandi.
Perché il mio container termina immediatamente?
Inizia dal codice di uscita, perché restringe rapidamente la causa.
docker compose ps -a
docker compose logs appCodice di uscita 0 e nessun output. Il comando è stato eseguito e si è concluso. La causa più comune è un override entrypoint: che ha eliminato anche il CMD dell'immagine. Di conseguenza, l'entrypoint è stato eseguito con un elenco di argomenti vuoto e non aveva nulla da avviare.
Un errore che termina con permission denied. Lo script non ha il bit di esecuzione all'interno dell'immagine. Di solito il bit non è mai stato impostato sul file nel repository. Impostalo durante la build con COPY --chmod=0755 entrypoint.sh /entrypoint.sh.
Un errore che termina con no such file or directory per un file chiaramente presente nell'immagine. Lo script usa terminatori di riga Windows. La prima riga viene quindi letta come #!/bin/sh più un byte di ritorno a capo. Il kernel cerca un interprete il cui nome contiene quel byte e non lo trova. Esegui dos2unix entrypoint.sh, quindi aggiungi * text eol=lf a .gitattributes per evitare che il problema si ripresenti.
executable file not found in $PATH. Il programma indicato in command: non si trova in nessuna directory del PATH del container. L'immagine potrebbe non contenerlo, oppure il programma potrebbe essere installato al di fuori di PATH: in questo caso, specifica il percorso completo. In alternativa, potresti avere indicato un costrutto interno della shell, come cd, in un punto in cui è ammesso soltanto un programma reale.
Aprire una shell in un'immagine il cui entrypoint non funziona
Quando l'entrypoint termina prima che sia possibile eseguire qualsiasi controllo, sostituitelo:
docker compose run --rm --entrypoint /bin/sh appSe il comando non funziona con stat /bin/sh: no such file or directory, l'immagine non contiene alcun /bin/sh. Le immagini Distroless e quelle basate su scratch spesso non includono alcuna shell. È comunque possibile leggere il filesystem dall'esterno senza avviare l'entrypoint:
docker create --name probe myapp:1.4
docker export probe | tar -tv | head -40
docker rm probeQuando è necessario mantenere attivo il container per potervi eseguire più volte il collegamento, usate un processo che non termina. Inserite questa configurazione in un file di override da non sottoporre a commit:
services:
app:
entrypoint: ["tail", "-f", "/dev/null"]
command: []command: [] non è strettamente necessario, perché l'impostazione di entrypoint: ha già cancellato CMD dell'immagine. Scriverlo esplicita comunque l'intento a chi leggerà il file in seguito. Avviate il container ed entratevi:
docker compose -f compose.yaml -f compose.debug.yaml up -d app
docker compose exec app /bin/shOra eseguite manualmente l'entrypoint reale e osservate dove si interrompe. In questo modo il messaggio di errore viene visualizzato nel terminale, invece di finire in un container terminato mezzo secondo prima. Se state ancora assemblando il primo stack, il primo stack Compose su un VPS descrive la struttura dei file presupposta da tutto quanto sopra.
FAQ
Perché il container termina subito dopo docker compose up?
Controlla docker compose ps -a per conoscere il codice di uscita. Un'uscita con codice 0 e senza output indica generalmente che hai impostato entrypoint: sul servizio. In questo modo hai anche annullato CMD dell'immagine, quindi l'entrypoint è stato eseguito con un elenco di argomenti vuoto e il processo è terminato. Ripristina gli argomenti con command:. Un errore che termina con permission denied indica che allo script entrypoint manca il bit di esecuzione. Un errore che termina con no such file or directory riferito a un file esistente indica che lo script usa terminatori di riga Windows. Di conseguenza, la riga shebang specifica un interprete che non esiste nel container.
Impostare entrypoint in Compose rimuove il CMD dell'immagine?
Sì. Se entrypoint non è null, Compose ignora il comando predefinito dichiarato dall'immagine. Questo comportamento è documentato e corrisponde a docker run --entrypoint. Il motivo è che CMD di un'immagine contiene gli argomenti destinati a ENTRYPOINT di quella stessa immagine. Quando sostituisci l'entrypoint, gli argomenti precedenti non sono quindi più associati ad alcun comando. Imposta command: nello stesso servizio se il nuovo entrypoint richiede ancora degli argomenti.
Una stringa in Compose command viene eseguita tramite una shell?
No. A differenza di CMD in un Dockerfile, una stringa in command: di Compose viene suddivisa in argomenti ed eseguita direttamente, senza un wrapper /bin/sh -c. Compose non avvia quindi una shell nel container per espandere $VARIABLE al posto tuo. Quando ti serve una shell, chiamala esplicitamente, come in command: /bin/sh -c 'echo "hello $$HOSTNAME"'. Il doppio $$ esegue l'escape del simbolo del dollaro, così Compose lo passa al container invece di espanderlo sull'host.
Perché docker compose down impiega dieci secondi per un solo container?
Compose invia il segnale di arresto al PID 1 (SIGTERM, a meno che l'immagine o il servizio non ne imposti un altro), attende fino a stop_grace_period (10 secondi per impostazione predefinita), quindi invia SIGKILL se il container è ancora in esecuzione. Il kernel non applica le azioni predefinite dei segnali al PID 1. Di conseguenza, un programma senza un gestore SIGTERM ignora il segnale e attende sempre per l'intero intervallo. Verifica quale processo è effettivamente il PID 1 con docker compose exec -T app cat /proc/1/cmdline | tr '\0' ' '. Se è una shell, modifica l'immagine usando la forma exec oppure inserisci exec nella stringa della shell. Se il processo crea processi figli che non raccoglie mai, imposta init: true sul servizio.