Come eseguire il debug dei container Docker su Debian 13

Introduzione

In questo tutorial, imparerai a eseguire il debug dei container Docker utilizzando tecniche pratiche e adatte ai principianti. Identificherai i problemi controllando lo stato del container, analizzando i log, ispezionando la configurazione e accedendo all'ambiente del container. Questo approccio ti aiuta a comprendere rapidamente perché un container fallisce e come risolverlo.

Obiettivo finale: Alla fine di questo tutorial, sarai in grado di identificare e risolvere i problemi comuni dei container Docker utilizzando log, ispezioni e strumenti di analisi runtime.

Prerequisiti

• Pubblico target: Amministratori di sistema principianti
• Tempo stimato: ~30 minuti
• Sistema operativo: Debian 13
• Software: Docker 24.0 o successivo
• Permessi: Utente con privilegi sudo o membro del gruppo docker
• Requisiti hardware: Almeno 2 GB di RAM e 10 GB di spazio libero su disco
• Requisiti di rete: Accesso a Internet per scaricare le immagini, nessuna porta specifica richiesta per questo tutorial
• Requisiti: Uso base della riga di comando e un servizio Docker in esecuzione
• Compatibilità: Testato su Debian 13 e funziona su Debian 12 e Ubuntu 22.04

Passo 1: Controlla le informazioni di sistema di Docker

Prima di eseguire il debug di un container specifico, verifica che Docker stesso funzioni correttamente.
Esegui il seguente comando:

docker system info

Vedrai informazioni dettagliate sull'ambiente Docker, inclusi:

• Versione del server
• Driver di archiviazione
• Numero di container e immagini
• Disponibilità di CPU e memoria
• Directory root di Docker

Questo ti aiuta a confermare che:

• Docker è in esecuzione correttamente
• Il sistema ha risorse sufficienti
• Non ci sono problemi di configurazione globale

Per controllare lo stato del servizio Docker:

systemctl status docker

Vedrai se il servizio Docker è attivo. Se non è in esecuzione, avvialo:

sudo systemctl start docker

Dovresti ora vedere il servizio in stato attivo.

Passo 2: Controlla lo stato del container

Esegui il seguente comando:

docker ps

Vedrai un elenco di container in esecuzione con dettagli come ID del container, immagine e stato. Se il tuo container appare con lo stato "Up", è attualmente in esecuzione.

Per includere i container fermati:

docker ps -a

Ora vedrai tutti i container. Se il tuo container mostra "Exited", significa che si è fermato a causa di un errore o ha completato l'esecuzione.

Passo 3: Visualizza i log del container

I log mostrano ciò che l'applicazione all'interno del container produce. Questo è il passo più importante per il debug. Puoi ottenere <CONTAINER_ID> tramite il comando docker ps descritto nel passo 2.

Esegui:

docker logs <CONTAINER_ID>

Vedrai l'output dell'applicazione, inclusi errori e avvisi. Cerca messaggi che indicano fallimenti come file mancanti o errori di connessione.

Per seguire i log in tempo reale:

docker logs -f <CONTAINER_ID>

Vedrai nuove voci di log man mano che appaiono. Questo è utile quando si riavvia un container e si osserva il comportamento.

Per visualizzare solo i log recenti:

docker logs --tail 50 <CONTAINER_ID>

Vedrai le ultime 50 righe di output. Questo ti aiuta a concentrarti sugli eventi più recenti.

Passo 4: Ispeziona lo stato del container

Docker memorizza informazioni dettagliate su ogni container.

Esegui:

docker inspect <CONTAINER_ID>

Vedrai un output JSON strutturato con dettagli di configurazione e runtime.

Per controllare lo stato del container:

docker inspect -f '{{.State.Status}}' <CONTAINER_ID>

Vedrai un valore semplice come "running" o "exited", che conferma lo stato del container.

Per controllare il codice di uscita:

docker inspect -f '{{.State.ExitCode}}' <CONTAINER_ID>

Vedrai un numero. Un valore di 0 significa successo, mentre qualsiasi valore diverso da zero indica un errore.

Per controllare la politica di riavvio:

docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' <CONTAINER_ID>

Vedrai se il container è configurato per riavviarsi automaticamente.

I codici di uscita comuni che potresti vedere:

• 0 – Il processo è stato completato con successo senza errori. Questo di solito significa che il container si è fermato normalmente. Ad esempio, uno script ha completato il suo compito ed è uscito.
• 1 – Si è verificato un errore generale. Questo è il codice di fallimento più comune e di solito significa che qualcosa all'interno dell'applicazione è fallito, come un file mancante, una configurazione non valida o un errore di runtime.
• 125 – Docker non è riuscito a eseguire il container. Questo di solito indica un problema con il comando docker run stesso, come opzioni non valide o parametri errati.
• 126 – Il comando all'interno del container non può essere eseguito. Questo spesso significa problemi di permessi o che il file non è eseguibile.
• 127 – Il comando non è stato trovato. Questo di solito significa che il binario o lo script specificato non esiste all'interno del container.
• 137 – Il container è stato fermato forzatamente. Questo spesso accade quando il sistema esaurisce la memoria e termina il processo del container.
• 139 – Il container è andato in crash con un errore di segmentazione. Questo indica un grave errore dell'applicazione, spesso legato a problemi di accesso alla memoria.
• 143 – Il container è stato fermato in modo ordinato. Questo di solito accade quando esegui docker stop e il container si spegne correttamente.

Passo 5: Accedi all'ambiente del container

A volte i log non sono sufficienti. Puoi entrare nel container per ispezionarlo direttamente.

Esegui:

docker exec -it <CONTAINER_ID> /bin/bash

Entri in una shell interattiva all'interno del container.

Se bash non è disponibile:

docker exec -it <CONTAINER_ID> /bin/sh

Puoi ora esplorare il container.

Controlla i processi del container in esecuzione dall'host:

docker top <CONTAINER_ID>

Vedrai i processi attivi all'interno del container. Se il processo principale manca, il container potrebbe fermarsi.

Passo 6: Monitora l'uso delle risorse

I container possono fallire a causa di risorse limitate.

Esegui:

docker stats

Vedrai l'uso in tempo reale di CPU, memoria e rete per tutti i container.

Per monitorare un container specifico:

docker stats <CONTAINER_ID>

Vedrai una tabella live che si aggiorna continuamente con l'uso delle risorse per tutti i container in esecuzione. Ogni riga rappresenta un container e ogni colonna mostra un tipo specifico di uso delle risorse.
Le colonne più importanti sono:

• CPU % – Mostra quanta CPU sta usando il container. Valori alti possono indicare un'elaborazione pesante o codice inefficiente.
• MEM USAGE / LIMIT – Mostra quanta memoria sta usando il container rispetto al suo limite. Se l'uso è vicino al limite, il container può rallentare o essere fermato.
• MEM % – Percentuale di memoria usata rispetto al limite.
• NET I/O – Traffico di rete. Questo mostra quanta dati il container ha ricevuto e inviato. Valori alti possono indicare un'attività di rete pesante.
• BLOCK I/O – Attività di lettura e scrittura su disco. Questa colonna mostra quanta dati il container ha letto da e scritto su disco.
• PIDs – Numero di processi in esecuzione all'interno del container. Un numero molto alto può indicare una perdita di processi o un'applicazione fuori controllo.

Passo 7: Controlla gli eventi di Docker

Docker registra eventi che descrivono cosa sta accadendo a livello di sistema e di container. Questi eventi ti aiutano a capire quando un container inizia, si ferma, si blocca o si riavvia.
Esegui il seguente comando:

docker events

Vedrai un flusso live di eventi come avvio, arresto e riavvio del container. L'output si aggiorna continuamente in tempo reale.

Filtra gli eventi per un container specifico

Esegui:

docker events --filter container=<CONTAINER_ID>

Vedrai solo gli eventi relativi al container selezionato. Questo ti aiuta a concentrarti su un singolo carico di lavoro.

Mostra eventi da un intervallo di tempo specifico

Per visualizzare eventi da un punto specifico nel tempo:

docker events --since 10m

Vedrai eventi degli ultimi 10 minuti.

Per definire sia l'ora di inizio che di fine:

docker events --since 2026-01-01T10:00:00 --until 2026-01-01T11:00:00

Vedrai eventi che si sono verificati in quell'intervallo di tempo.

Formatta l'output degli eventi

Esegui:

docker events --format '{{.Time}} {{.Type}} {{.Action}} {{.Actor.ID}}'

Vedrai un output formattato con campi selezionati. Questo rende più facile la lettura o l'integrazione con script.

Filtra tipi specifici di eventi

Puoi filtrare gli eventi per concentrarti su problemi specifici.

Arresto o crash del container

Esegui:

docker events --filter event=die

Vedrai eventi quando i container si fermano. Questo aiuta a identificare arresti inaspettati.

Eventi di memoria insufficiente

Esegui:

docker events --filter event=oom

Vedrai eventi quando un container viene terminato a causa di limiti di memoria. Questo è critico per diagnosticare problemi di risorse.

Riavvii del container

Esegui:

docker events --filter event=restart

Vedrai quando i container si riavviano. Eventi di riavvio frequenti possono indicare un ciclo di crash.

Combina filtri e intervallo di tempo

Esegui:

docker events --since 10m --filter event=die

Vedrai eventi di arresto del container degli ultimi 10 minuti. Questo aiuta a restringere i fallimenti recenti.

Passo 8: Controlla l'uso del disco e pulisci le immagini non utilizzate

Docker memorizza immagini, container, volumi e cache su disco. Nel tempo, i dati non utilizzati possono consumare spazio significativo e causare problemi.

Esegui il seguente comando:

docker system df

Vedrai un riepilogo dell'uso del disco, inclusi:

• Immagini
• Container
• Volumi locali
• Cache di build

Ogni sezione mostra:

• Conteggio totale
• Elementi attivi
• Dimensione
• Spazio recuperabile

Questo ti aiuta a capire quanto spazio su disco sta usando Docker e quanto può essere pulito.

Per visualizzare le immagini non utilizzate esegui:

docker images -f dangling=true

Vedrai immagini che non sono taggate e non utilizzate da alcun container. Queste sono candidate sicure per la rimozione.

Per rimuovere le immagini non utilizzate esegui:

docker image prune

Ti verrà chiesto di confermare. Dopo la conferma, le immagini non utilizzate vengono eliminate e lo spazio su disco viene liberato.

Per rimuovere tutte le immagini non utilizzate, non solo quelle sospese:

docker image prune -a

Rimuovi tutte le immagini che non sono utilizzate da alcun container.

Verifica e test

• Esegui docker ps e conferma che lo stato del container sia corretto.
• Esegui docker logs e verifica che gli errori siano identificati o risolti.
• Esegui docker inspect e conferma che lo stato e il codice di uscita corrispondano alle aspettative.
• Usa docker exec per confermare che i processi siano in esecuzione all'interno del container.
• Se il debug ha successo, il container dovrebbe rimanere in stato di esecuzione senza errori critici nei log.

Ripristino delle modifiche

Se hai apportato modifiche durante il debug, puoi ripristinare uno stato pulito.

Ferma un container:

docker stop <CONTAINER_ID>

Vedrai la conferma che il container è stato fermato.

Rimuovi un container:

docker rm <CONTAINER_ID>

Vedrai la conferma che il container è stato rimosso.

Ricrea il container:

docker run <OPTIONS> <IMAGE_NAME>

Un nuovo container viene creato dall'immagine.

Risoluzione dei problemi

Il container esce immediatamente

Controlla docker logs per messaggi di errore. Questi di solito spiegano il problema.

Impossibile accedere al container

Assicurati che sia in esecuzione usando docker ps.

Nessun log disponibile

Assicurati che l'applicazione scriva output su stdout o stderr.

Il container si riavvia ripetutamente

Controlla la politica di riavvio e i log per identificare i cicli di crash.

Uso elevato delle risorse

Usa docker stats per confermare picchi di CPU o memoria.

Conclusione

Hai imparato come eseguire il debug dei container Docker controllando il loro stato, analizzando i log, ispezionando la configurazione e accedendo all'ambiente del container. Queste tecniche ti permettono di identificare e risolvere rapidamente i problemi comuni. Come passo successivo, esplora il debug di Docker Compose e i sistemi di logging centralizzati per gestire più container.