Docker Compose exec: aprire una shell interattiva
Usa docker compose exec web bash per entrare in un servizio running; se bash non esiste, prova sh. Con il servizio fermo, docker compose run crea un nuovo container.
Aprire una shell interattiva con docker compose exec
docker compose exec web bash apre una shell interattiva all'interno del container già in esecuzione come servizio web. Il nome dopo exec è il nome del servizio definito nel file compose.yaml, non il nome del container. Se l'immagine non include bash, richiedere sh.
docker compose ps
docker compose exec web bashEseguire prima docker compose ps. Dovrebbe elencare web con lo stato running. Il secondo comando apre quindi un prompt all'interno del container; exit o Ctrl-D consente di tornare all'host. Il servizio continua a essere in esecuzione dopo l'uscita, perché exec avvia un secondo processo accanto a quello principale. La chiusura della shell non modifica PID 1 (process ID 1), cioè il processo per cui il container è stato creato.
Questo è uno dei due modi per accedere al container. exec si collega a un container già esistente. docker compose run crea un nuovo container dalla stessa definizione del servizio. Quasi tutto il resto di questa guida deriva da questa singola differenza.
Perché -it è facoltativo in Compose ma obbligatorio con plain docker
Due flag controllano la parte interattiva di una sessione. -i mantiene aperto stdin, quindi ciò che si digita viene passato al processo. -t alloca un terminale pseudografico, chiamato TTY, in modo che la shell visualizzi il prompt e gestisca i tasti freccia. plain docker exec lascia entrambe le opzioni disabilitate per impostazione predefinita; per questo tutti gli esempi precedenti riportano docker exec -it. docker compose exec le abilita entrambe automaticamente, quindi docker compose exec -it web bash e docker compose exec web bash producono lo stesso risultato. Compose accetta comunque -it, così la consuetudine di usarlo continua a funzionare.
La mancanza di un TTY è evidente in pochi secondi. La shell viene eseguita, ma non visualizza alcun prompt e Ctrl-C non raggiunge mai il processo. Il caso opposto, in cui è necessario chiedere a Compose di non allocare un TTY, ha un flag specifico e una sezione dedicata più avanti.
Cosa fare quando l'immagine non contiene bash
Se si chiede bash a un'immagine basata su Alpine, exec ha esito negativo in questo modo:
OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found in $PATH: unknownIl messaggio non indica un problema di exec. Indica che nelle directory elencate nel PATH del container non è stato trovato alcun bash. Per una shell, questo significa quasi sempre che l'immagine non ne contiene una. Alpine include BusyBox, che fornisce ash come /bin/sh, ma non include bash. È quindi necessario richiedere sh:
docker compose exec web shLe immagini basate su Debian e Ubuntu, inclusi i tag -slim, includono bash. bash offre la cronologia dei comandi e un completamento migliore. Provare quindi prima bash e, se non è disponibile, usare sh. sh è presente in quasi tutte le immagini per uso generico.
Alcune immagini non contengono alcuna shell. Le immagini Distroless e quelle compilate FROM scratch contengono intenzionalmente solo il binario dell'applicazione e le relative librerie. Una shell assente non può essere usata contro l'applicazione. In queste immagini, sh ha esito negativo con lo stesso messaggio e non resta nulla da provare. Sono disponibili due approcci. Le immagini Distroless di Google pubblicano tag :debug che aggiungono una shell BusyBox. Passando temporaneamente a questo tag è possibile accedere al container. In alternativa, avviare un container separato all'interno dei namespace del target:
CID=$(docker compose ps -q web)
docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshootA questo punto gli strumenti di netshoot operano sulla rete dell'applicazione. Di conseguenza, curl localhost:8080 e ss -lntp si comportano come se fossero eseguiti dall'interno dell'applicazione. Il filesystem visualizzato appartiene a netshoot, non all'applicazione. Poiché il namespace dei processi è condiviso, /proc/1/root/ punta al filesystem del processo target. Tuttavia, ls /proc/1/root/ deve superare il controllo dei permessi ptrace del kernel. Non è sufficiente che entrambi i processi siano eseguiti come root. Il controllo considera anche le credenziali, le capability, l'attributo dumpable del target e i moduli di sicurezza. Un valore dumpable diverso da 1 blocca l'accesso, a meno che il chiamante non disponga di CAP_SYS_PTRACE nel namespace utente del target. Docker non concede SYS_PTRACE per impostazione predefinita. L'aggiunta di --cap-add SYS_PTRACE alla riga docker run risolve i controlli relativi a credenziali e dumpability, ma i moduli di sicurezza possono comunque negare l'accesso.
Quando il servizio non è in esecuzione, usa docker compose run --rm
exec richiede un container in esecuzione. Se lo punti a un servizio arrestato, restituisce un errore:
service "web" is not runningNon avvia nulla automaticamente. docker compose run invece:
docker compose run --rm web bashrun crea un nuovo container dalla definizione del servizio web, usando la stessa immagine, le stesse variabili d'ambiente, gli stessi volumi e le stesse reti, quindi sostituisce il comando del servizio con quello specificato. --rm elimina il container quando esci. Se ometti --rm, i container residui si accumulano con nomi come myproject-web-run-4f1c2b. docker compose ps -a li mostra, mentre docker compose rm li rimuove insieme agli altri container arrestati del servizio.
Due comportamenti di run sorprendono spesso gli utenti. Non pubblica le porte del servizio, a meno che tu non aggiunga --service-ports oppure non ne mappi una manualmente con -p. È una scelta intenzionale: un secondo container che tenta di associare la porta host 8080 mentre il primo la utilizza ancora fallirebbe con bind: address already in use. Inoltre avvia tutto ciò che il servizio elenca in depends_on prima di mostrare la shell. Anche un controllo rapido all'interno del container può quindi avviare un database e una cache. --no-deps evita questo comportamento.
run passa attraverso l'ENTRYPOINT dell'immagine, mentre exec no. exec avvia direttamente il comando nel container esistente, quindi lo script dell'entrypoint non lo riceve. Con run, il tuo bash viene passato come argomento a quello script. Molte immagini ufficiali terminano l'entrypoint con exec "$@", quindi il comando passa direttamente e ottieni la shell. Uno script che interpreta autonomamente i propri argomenti può invece comportarsi in modo diverso. In questo caso puoi sostituire l'entrypoint per una singola esecuzione:
docker compose run --rm --entrypoint sh webQuesto è il motivo più comune per cui un comando che funziona con exec si comporta diversamente con run. La distinzione tra comando ed entrypoint spiega quale parte della configurazione dell'immagine stai sostituendo ogni volta.
exec o run: come scegliere
execrichiede un container in esecuzione.runno e può avviare le dipendenze.execvede l’elenco dei processi in esecuzione e i file nello stato attuale, inclusi quelli che l’applicazione ha creato dall’avvio.runottiene un livello scrivibile pulito dall’immagine, ma i volumi denominati e i bind mount continuano a esporre i dati esistenti del servizio.execignora l’entrypoint.runlo esegue.runlascia un container, a meno che non si passi--rm.
Usa exec per verificare che cosa sta accadendo realmente. Usa run --rm per una copia temporanea dello stesso ambiente, per eseguire una migrazione una tantum oppure quando il servizio reale non rimane attivo abbastanza a lungo da consentire l’accesso con exec.
Flag utili per l'esecuzione: utente, directory di lavoro e repliche
La maggior parte delle immagini passa a un utente non root. Per questo, l'installazione di uno strumento diagnostico nella shell exec si interrompe a questo punto:
E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)-u root apre una shell root nello stesso container:
docker compose exec -u root web sh-w /srv/app imposta la directory di lavoro solo per quel comando. -e KEY=value aggiunge una variabile d'ambiente alla sessione, non al servizio. Quando un servizio esegue più repliche, --index 2 determina in quale container si accede. Se si sta verificando la proprietà dei file in una directory montata, PUID e PGID nelle immagini container spiega perché sono gli ID numerici, non i nomi utente, a determinare chi può scrivere nella directory.
Aprire una shell psql o mysql all'interno del container del database
Il client è già incluso nell'immagine del database. Non serve installarne uno sull'host e non è necessario pubblicare la porta:
docker compose exec db psql -U postgres -d app
docker compose exec db mariadb -u root -pLe immagini Postgres includono psql, le immagini MySQL includono mysql e le immagini MariaDB includono mariadb. La connessione viene aperta dall'interno del container. Il comando funziona quindi anche quando il file Compose non pubblica alcuna porta del database. Questa è la configurazione più sicura con la rete bridge predefinita di Docker: gli host esterni non possono raggiungere direttamente una porta del database non pubblicata, mentre l'host Docker e i container sulla stessa rete possono ancora farlo.
Un errore comune può far perdere molto tempo. La shell espande le variabili sull'host, prima che Docker visualizzi il comando. Di conseguenza, -U "$POSTGRES_USER" invia una stringa vuota quando la variabile esiste soltanto all'interno del container. Gli apici singoli e una shell eseguita nel container eseguono l'espansione nel punto corretto:
docker compose exec db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'Qui non usare docker compose run --rm db senza un comando. In questo modo avvii un secondo server Postgres sullo stesso volume dati, che rifiuta di avviarsi:
FATAL: lock file "postmaster.pid" already existsIl file di lock sta svolgendo la sua funzione, perché due server che scrivono nella stessa directory dati la danneggerebbero. Quando il database è attivo, esegui exec nel container in esecuzione. Stabilire se il database debba essere eseguito in Compose è una decisione separata; eseguire il database in Docker o sull'host illustra i compromessi.
Servizi che richiedono una console all'avvio: stdin_open e tty
exec e run riguardano le shell aperte manualmente. Un servizio il cui processo principale è interattivo per sua natura richiede due chiavi nel file Compose:
services:
console:
image: python:3.12-slim
command: python
stdin_open: true
tty: truestdin_open: true è docker run -i e tty: true è docker run -t. Senza queste impostazioni, il container viene avviato e termina subito con codice 0; docker compose ps -a mostra Exited (0). Non si è verificato alcun arresto anomalo. python, senza un terminale su stdin, legge immediatamente la fine del file e termina normalmente. Questo è il comportamento corretto per un programma con cui nessuno sta interagendo tramite tastiera.
Con entrambe le chiavi impostate, collegarsi al processo in esecuzione:
docker attach $(docker compose ps -q console)Per scollegarsi, premere Ctrl-P e poi Ctrl-Q. Il processo continuerà a essere eseguito. Questa sequenza funziona soltanto quando il container ha sia un TTY sia stdin aperto. Ctrl-C invia invece un interrupt (SIGINT) al PID 1. Il servizio si arresta solo se il programma è progettato per terminare alla ricezione di SIGINT, perché Linux non applica la gestione predefinita dei segnali al PID 1. Non usare quindi Ctrl-C per scollegarsi.
Lasciare entrambe le chiavi disattivate per i servizi ordinari. Un web server non legge mai stdin e tty: true induce molti programmi ad attivare l'output a colori e il buffering per righe, perché ritengono che una persona stia osservando l'output. Di conseguenza docker compose logs si riempie di codici di escape.
Perché l'esecuzione tramite script non funziona in cron e CI: il flag -T
Un comando exec che funziona nel terminale può non riuscire quando viene eseguito da uno script, da un job cron, da un runner di integrazione continua (CI) o tramite una pipe:
the input device is not a TTYCompose richiede un terminale pseudo quando il proprio output è diretto a un terminale. La richiesta fallisce prima dell'esecuzione del comando se anche stdin non è un terminale. Il codice sorgente recente della Docker CLI descrive lo stesso errore come cannot attach stdin to a TTY-enabled container because stdin is not a terminal. Le versioni attuali di Compose evitano autonomamente la richiesta quando l'output viene reindirizzato o inoltrato tramite pipe, come avviene di solito in cron. Alcune versioni precedenti effettuavano comunque la richiesta, mentre cat dump.sql | docker compose exec db psql digitato direttamente al prompt continua a provocarla. -T disabilita la richiesta in ogni caso. Usalo quindi negli script invece di affidarti al rilevamento automatico:
0 3 * * * docker compose -f /srv/app/compose.yaml exec -T db pg_dump -U postgres -Fc app > /srv/backups/app.dump-T è importante per un secondo motivo. Un TTY modifica il flusso di byte durante l'output, quindi un dump compresso che lo attraversa arriva danneggiato. Specifica esplicitamente -T per qualsiasi output reindirizzato o inoltrato tramite pipe.
Considera altri due dettagli relativi a cron. Specifica -f con un percorso assoluto, perché cron esegue il job dalla home directory, dove non è presente il file Compose. Compose si interrompe quindi con no configuration file provided: not found. Inoltre, exec restituisce il codice di uscita del comando eseguito. Di conseguenza, un pg_dump non riuscito fa fallire lo script con set -e, invece di scrivere un backup vuoto e segnalare un esito positivo. Gli altri comandi di uso quotidiano sono raccolti in un promemoria dei comandi Compose da tenere accanto a questi script.
Perché le modifiche apportate all'interno di un container scompaiono
Installi uno strumento con exec, modifichi un file di configurazione, risolvi il problema e, una settimana dopo, la correzione è scomparsa. Questo è il comportamento previsto del livello scrivibile del container. docker compose up -d dopo ogni modifica al tag dell'immagine o alla definizione del servizio elimina il vecchio container e ne crea uno nuovo a partire dall'immagine; tutte le modifiche manuali vengono quindi perse insieme al vecchio container.
docker compose restart è diverso. Arresta e riavvia lo stesso container, quindi le modifiche manuali restano disponibili. Per questo una correzione manuale può sembrare persistente per settimane e poi scomparire durante un aggiornamento non correlato. I volumi denominati e i bind mount persistono con entrambe le operazioni, perché i relativi dati risiedono all'esterno del container. bind mount e volumi denominati spiega quale scegliere per i dati che si desidera conservare.
Considera quindi una shell exec come un ambiente per leggere e verificare. Quando hai individuato la correzione, scrivila in un punto persistente: installa un pacchetto nel Dockerfile e inserisci un'impostazione nel file compose. Poi docker compose up -d per applicarla e verifica con un altro exec che il nuovo container la contenga effettivamente.
FAQ
Qual è la differenza tra docker compose exec e docker compose run?
exec esegue un comando all'interno di un container già in esecuzione, accanto al processo principale, e ignora l'entrypoint dell'immagine. run crea un nuovo container dalla stessa definizione del servizio, usando la stessa immagine, lo stesso ambiente, gli stessi volumi e le stesse reti, passa il comando attraverso l'entrypoint e avvia prima i servizi depends_on. run inoltre non pubblica le porte del servizio, a meno che non si aggiunga --service-ports o una mappatura -p. Usa exec per esaminare il servizio attivo. Usa run --rm quando il servizio è arrestato o quando serve un container separato, ricordando però che i volumi denominati e i bind mount sono condivisi.
Perché docker compose exec segnala che il servizio non è in esecuzione?
exec si collega a un container esistente e non può crearne uno. Di conseguenza, un servizio arrestato o terminato in modo anomalo restituisce service "web" is not running. Controlla docker compose ps -a, che elenca i container terminati con uno stato come Exited (1), e leggi docker compose logs web per conoscere il motivo dell'arresto. Per ottenere comunque una shell, esegui docker compose run --rm --entrypoint sh web. In questo modo viene creato un nuovo container dalla stessa definizione del servizio senza eseguire il comando di avvio difettoso.
Come apro una shell quando l'immagine non contiene bash?
Se docker compose exec web bash restituisce exec: "bash": executable file not found in $PATH, significa che nei percorsi elencati in PATH del container non è stato trovato bash. Quasi sempre questo indica che l'immagine non lo include. È normale per le immagini basate su Alpine. Usa docker compose exec web sh, perché BusyBox fornisce /bin/sh. In un'immagine priva di shell, exec non può aprire una shell, ma può comunque eseguire gli eseguibili presenti nell'immagine. Passa al tag :debug dell'immagine se il publisher ne mette a disposizione uno, oppure avvia un container di debug negli namespace del target con docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshoot, dove $CID proviene da docker compose ps -q web.
Perché il comando exec restituisce "the input device is not a TTY" in cron?
docker compose exec richiede un terminale pseudo-TTY quando l'output è diretto a un terminale. La richiesta non riesce se anche stdin non è un terminale. Le versioni attuali di Compose evitano automaticamente la richiesta quando l'output è reindirizzato, come accade normalmente in cron. Alcune versioni precedenti la eseguivano comunque, e anche l'invio di input tramite pipe a exec da una shell interattiva può attivarla. Aggiungi -T per disabilitarla: docker compose exec -T db pg_dump -U postgres app. Usa -T anche per qualsiasi output reindirizzato o tramite pipe, perché un TTY modifica il flusso di byte e danneggia un dump binario. In cron, passa inoltre -f con il percorso assoluto del file Compose. In caso contrario, Compose termina con no configuration file provided: not found.
Le modifiche apportate all'interno di un container con exec persistono dopo un riavvio?
Persistono dopo docker compose restart, che riutilizza lo stesso container. Vanno perse dopo docker compose up -d in seguito a una modifica dell'immagine o della configurazione, perché il container viene ricreato dall'immagine e il relativo layer scrivibile viene eliminato. I dati scritti nei volumi denominati o nei bind mount persistono in entrambi i casi, perché risiedono all'esterno del container. Applica con exec solo modifiche diagnostiche, quindi inserisci la configurazione permanente nel Dockerfile o nel file Compose.