Docker Compose: controlli essenziali quando un servizio non sale

Quando un servizio Compose non parte

Un container che resta in errore non indica sempre un problema dell’immagine. In molti casi la causa è nel file di configurazione, nei volumi, nelle variabili d’ambiente o nella sequenza di avvio dei servizi.

Prima di cambiare parametri a caso, conviene seguire una verifica ordinata. Con pochi comandi è possibile isolare quasi sempre il punto esatto del blocco.

1. Leggere lo stato reale dei container

Il primo controllo è vedere se il servizio esiste, se si riavvia in loop o se esce subito con un codice di errore.

docker compose ps

Se un container risulta Exited o Restarting, annota il codice di uscita. È spesso il primo indizio per distinguere tra errore applicativo, problema di mount o configurazione errata.

2. Controllare i log senza filtri

I log del servizio sono la fonte più utile per capire se l’applicazione non trova un file, non raggiunge un database o fallisce durante l’inizializzazione.

docker compose logs -f nome_servizio

Cerca messaggi come:

• file o directory mancanti
• connessione rifiutata verso un altro container
• permessi negati su volume o cartella
• variabile d’ambiente non definita

3. Verificare volumi e percorsi montati

Molti avvii falliti dipendono da un bind mount sbagliato o da una directory host inesistente. Se il container si aspetta un file di configurazione e trova una cartella vuota, l’app può chiudersi subito.

Controlla con attenzione:

• il percorso sorgente sul sistema host
• il punto di mount nel container
• i permessi di lettura e scrittura
• la presenza di file creati con utente diverso

Se serve, entra nel container e verifica direttamente cosa vede il processo:

docker exec -it nome_servizio sh

4. Esaminare porte e conflitti

Un servizio può non partire perché la porta esposta è già occupata sul sistema host. In questi casi il container non riesce a completare il bind e termina subito.

Controlla il mapping nel file Compose e confrontalo con i servizi già in ascolto. Se una porta è in conflitto, prova temporaneamente a cambiarla per confermare la diagnosi.

5. Controllare variabili d’ambiente e file .env

Una credenziale vuota, un valore scritto male o una variabile mancante bastano a bloccare l’avvio. Questo succede spesso con database, cache, applicazioni web e code worker.

Verifica:

• nomi delle variabili scritti correttamente
• valori tra virgolette se contengono caratteri speciali
• presenza del file .env
• coerenza tra compose e documentazione dell’applicazione

6. Valutare le dipendenze tra servizi

Se un servizio dipende da un database o da un broker, non basta che il container esista: deve essere realmente pronto a ricevere connessioni. depends_on non garantisce sempre la disponibilità completa del servizio dipendente.

Quando un’app parte troppo presto, può fallire per tentativi di connessione iniziali andati male. In questo caso conviene introdurre healthcheck o ritardi controllati, invece di aumentare i restart indiscriminatamente.

7. Controllare immagine, tag e aggiornamenti

Un tag troppo generico, come latest, può introdurre cambiamenti improvvisi. Se il problema è apparso dopo un aggiornamento, confronta la versione precedente dell’immagine con quella attuale.

In alcuni casi il container non parte perché l’entrypoint è cambiato, una dipendenza interna è stata rimossa o la configurazione attesa non è più valida.

8. Usare un approccio minimo per isolare la causa

Se il problema resta poco chiaro, riduci la configurazione al minimo. Avvia un solo servizio, senza volumi complessi e senza dipendenze esterne, per capire se il difetto è nell’applicazione o nell’orchestrazione.

Più il test è semplice, più velocemente si capisce se il guasto è nel container o nel contesto in cui viene eseguito.

Checklist finale veloce

1. verifica lo stato con docker compose ps
2. leggi i log completi del servizio
3. controlla volumi, path e permessi
4. verifica porte già occupate
5. conferma variabili d’ambiente e file .env
6. valuta dipendenze e tempi di avvio
7. controlla immagine e tag utilizzati

Con questi controlli, nella maggior parte dei casi il motivo per cui un servizio non sale emerge rapidamente. L’obiettivo non è solo farlo ripartire, ma capire quale elemento della composizione lo rende fragile.

Se vuoi, posso anche preparare una versione più tecnica, una più divulgativa oppure un articolo dedicato ai casi in cui docker compose up fallisce dopo un deploy.