Come installare Docker su Debian 13 Trixie passo dopo passo

Preparare Debian 13 Trixie prima di toccare Docker

Su Debian 13 Trixie Docker si installa senza forzature, ma conviene partire con due verifiche semplici: il sistema deve essere aggiornato e il kernel deve supportare correttamente cgroups, overlayfs e namespace. Se salti questo passaggio, poi finisci a inseguire errori ambigui sul demone, sullo storage driver o sui permessi del socket.

La strada più solida è usare il repository ufficiale Docker e non il pacchetto generico dei repository Debian, perché il primo ti dà versioni allineate al ciclo di Docker e documentazione coerente. Su una macchina di produzione o su un host che ospiterà più container, questa scelta evita differenze strane tra ambienti.

Prima di tutto, aggiorna l’indice pacchetti e verifica che il sistema sia in ordine.

sudo apt update
sudo apt upgrade -y
uname -r
cat /etc/debian_version

Se il comando uname -r restituisce un kernel recente della serie Debian 13, sei già nella condizione normale. Se invece hai un kernel molto vecchio o un sistema appena migrato, conviene riavviare prima di iniziare l’installazione: non è un requisito formale di Docker, ma è il modo più rapido per evitare problemi residui di moduli o cgroups.

Dipendenze minime e chiave del repository

Per aggiungere il repository ufficiale servono pochi pacchetti: strumenti per HTTPS, gestione delle chiavi e repository APT. Su Debian moderno l’approccio corretto è usare /etc/apt/keyrings, non il vecchio keyring globale deprecato. In pratica riduci la superficie di fiducia e tieni la chiave legata al repository specifico.

sudo apt install -y ca-certificates curl gnupg

Poi crea la directory dedicata alle chiavi se non esiste già.

sudo install -m 0755 -d /etc/apt/keyrings

Scarica la chiave GPG del repository Docker e convertila nel formato corretto per APT. Qui non c’è nulla di esotico: il punto è rendere esplicito a quale sorgente stai concedendo fiducia.

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Se questo passaggio fallisce, le cause pratiche sono quasi sempre tre: connettività in uscita bloccata, proxy aziendale che intercetta TLS, oppure problema temporaneo lato mirror. La verifica minima è banale: prova un curl -I verso il dominio del repository e controlla che il certificato venga presentato correttamente.

curl -I https://download.docker.com/linux/debian/

Aggiungere il repository ufficiale Docker per Trixie

Il file sorgente APT va creato con l’architettura corretta e con la distribuzione esplicitata. Su Trixie il nome della suite è trixie, quindi non serve nessun trucco di compatibilità. Se stai leggendo questa guida su un host diverso da AMD64, sostituisci l’architettura con quella reale del sistema.

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Subito dopo, aggiorna l’indice pacchetti. Questo è il punto in cui verifichi se il repository è stato letto correttamente o se hai un errore di firma, di rete o di sintassi nel file sorgente.

sudo apt update

Se tutto è andato bene, nel risultato di apt update dovresti vedere il repository Docker senza errori di tipo NO_PUBKEY o Release file. Se compare un errore di firma, il file della chiave in /etc/apt/keyrings/docker.gpg è il primo posto da controllare.

Installare Docker Engine, CLI e componenti utili

Per un’installazione standard bastano quattro pacchetti: motore, CLI, plugin per Compose e plugin per la gestione degli oggetti di rete. In Debian 13 il nome dei pacchetti può cambiare nel tempo solo se Docker introduce nuove dipendenze, ma la linea base resta quella.

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Durante l’installazione il sistema può proporre di avviare automaticamente il servizio. Se non succede, lo fai tu dopo la verifica del demone. In ogni caso, il controllo reale non è “il pacchetto è installato”, ma “il socket risponde e il demone crea container”.

docker --version
sudo systemctl status docker --no-pager

Se docker --version risponde ma systemctl status docker mostra un servizio inattivo, il problema è nell’avvio del demone, non nel client. Se invece il client non trova il socket, il servizio non è partito o non ha terminato l’inizializzazione.

Avviare e abilitare il servizio Docker

Su un host che deve restare disponibile dopo il reboot, il servizio va abilitato. Questa è la parte più semplice, ma anche quella che spesso viene dimenticata nei test rapidi in laboratorio.

sudo systemctl enable --now docker

Verifica subito che il demone sia attivo e che il socket sia stato creato. Il controllo utile è doppio: stato del servizio e risposta del comando Docker con privilegi adeguati.

sudo systemctl is-active docker
sudo docker info

Se docker info fallisce con errori di comunicazione col demone, guarda i log di systemd. Nella pratica, le righe che contano sono quelle con dockerd, containerd e gli eventuali errori sul driver di storage.

journalctl -u docker -b --no-pager | tail -n 80

Un errore classico dopo installazioni parziali è la mancanza del supporto per overlayfs o una configurazione di storage non coerente. Su Debian recente, se non hai esigenze particolari, lascia che Docker scelga overlay2: è il percorso più stabile nella maggior parte degli scenari.

Permessi per usare Docker senza sudo

Per default solo root può parlare con il socket di Docker. È una scelta sensata dal punto di vista della sicurezza, perché l’accesso al socket equivale di fatto a controllo quasi totale dell’host. Se però devi usare Docker da utente amministrativo, puoi aggiungere il tuo account al gruppo docker.

sudo usermod -aG docker $USER

Dopo aver modificato i gruppi, devi aprire una nuova sessione shell o fare logout/login. Questo passaggio non è opzionale: la membership viene letta all’avvio della sessione, non in tempo reale.

id -nG
newgrp docker

Attenzione al punto di sicurezza: il gruppo docker non è un permesso “leggero”. Chi lo possiede può montare filesystem host, esporre socket, leggere dati e avviare container privilegiati. In ambienti condivisi, meglio preferire accesso via sudo controllato o strumenti di orchestrazione con policy più strette.

Test pratico con un container minimale

La prova vera non è l’output della versione, ma un container che parte, scarica un’immagine e termina con un messaggio atteso. Il classico hello-world resta utile proprio perché riduce il problema a tre elementi: rete, demone e runtime.

docker run --rm hello-world

Se il comando scarica l’immagine e stampa il messaggio di conferma, il circuito base è integro. Se invece fallisce, il dettaglio dell’errore dice dove guardare: DNS se non risolve i registri, rete se non raggiunge il registry, permessi se non accede al socket, storage se non riesce a creare il layer locale.

Un test leggermente più utile, se vuoi validare anche la rete interna dei container, è avviare un web server minimale e pubblicarlo su una porta locale.

docker run -d --name webtest -p 8080:80 nginx:stable
curl -I http://127.0.0.1:8080

Il risultato atteso è un HTTP/1.1 200 OK o, in alcune configurazioni, un 403 iniziale se il contenuto di default è stato rimosso dal tag immagine. In ogni caso il punto è che la porta locale risponda. Se non risponde, il problema è nel publish della porta o nel container stesso.

Installazione con Compose: quando serve davvero

Su molti host moderni la CLI docker compose basta e avanza. Il plugin incluso nel pacchetto ufficiale ti evita dipendenze Python esterne e mantiene il flusso coerente con il resto dello stack. Se gestisci applicazioni multi-servizio, Compose è il minimo indispensabile per rendere ripetibile un ambiente.

docker compose version

Per un test rapido, puoi creare un file compose.yml minimale con un servizio singolo. Non serve complicare: l’obiettivo è verificare che il plugin venga letto e che il progetto salga senza errori di parsing.

services:
  web:
    image: nginx:stable
    ports:
      - "8081:80"

Poi avvii lo stack con il comando standard.

docker compose up -d
docker compose ps

Se docker compose ps mostra lo stato running, la catena APT → demone → runtime → networking è coerente. Se il container si ferma subito, i log del servizio specifico sono il primo posto da guardare.

docker compose logs --no-color --tail=100

Collaudo dell’installazione e controlli di base

A installazione conclusa, conviene raccogliere tre verifiche che in pratica coprono il 90% dei casi: stato del servizio, versione dei componenti e capacità di eseguire un container. Sono controlli banali, ma sono anche quelli che evitano di credere che tutto sia a posto solo perché il pacchetto è stato installato.

sudo systemctl status docker --no-pager
docker version
docker info | sed -n '1,40p'

Nel blocco docker info osserva in particolare il driver di storage, il numero di container, l’architettura e il campo relativo ai plugin. Se trovi Server Version e Storage Driver: overlay2, sei sulla strada giusta. Se il driver è diverso senza una ragione precisa, vale la pena capire perché prima di mettere carico reale.

Un controllo utile anche in ottica manutenzione è il riavvio del servizio. Non perché Docker debba essere riavviato spesso, ma perché un host sano deve ripartire senza sorprese.

sudo systemctl restart docker
sudo systemctl is-active docker

Se dopo il restart il demone resta attivo e i container configurati con restart policy tornano su, hai validato anche il comportamento post-reboot. È il test che spesso manca nelle installazioni “manuali” fatte in fretta.

Problemi tipici su Debian 13 Trixie e come leggerli

Il primo problema tipico è la rete in uscita bloccata verso download.docker.com. In quel caso apt update fallisce o il download della chiave non riesce. Il modo corretto di chiudere il dubbio è una prova di connettività con curl -I e, se necessario, la verifica del proxy a livello di shell o di sistema.

Il secondo problema è la mancata attivazione del servizio. Qui il segnale è evidente: systemctl status docker mostra failed o inactive. Il log di journalctl -u docker -b ti dice se il demone non parte per storage, socket, overlay o errore di configurazione.

Il terzo è il permesso utente. Se il comando docker ps risponde con errore sul socket, ma sudo docker ps funziona, non hai un problema di installazione: hai un problema di membership nel gruppo o di sessione non rinnovata. In quel caso la correzione è semplice, ma va fatta con attenzione perché stai cambiando il perimetro di accesso al motore container.

Disinstallare o ripulire senza lasciare residui

Se devi rimuovere Docker, distingui tra disinstallazione del software e cancellazione dei dati. I pacchetti si possono togliere con APT, ma i volumi, le immagini e i container non spariscono automaticamente. Questo è importante perché una rimozione “pulita” in un ambiente di test può diventare una perdita dati in un ambiente reale.

sudo apt remove -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Se vuoi eliminare anche i dati locali, il percorso da valutare con molta attenzione è /var/lib/docker. Non cancellarlo a occhi chiusi: lì dentro vivono immagini, layer, volumi e metadati. Prima di intervenire, verifica cosa c’è davvero.

sudo du -sh /var/lib/docker
sudo ls -lah /var/lib/docker

Se l’obiettivo è solo cambiare versione o ripartire da zero, meglio fare un backup o almeno un inventario dei volumi da preservare. In produzione, la dismissione va trattata come change controllato, non come pulizia manuale.

Decisione pratica: quando questa installazione è davvero pronta

Una installazione Docker su Debian 13 Trixie è pronta quando quattro condizioni sono vere insieme: il repository ufficiale è registrato e firmato, il servizio è attivo, il comando docker info restituisce dati coerenti e un container di test parte senza interventi manuali. Se manca anche solo uno di questi punti, il setup è incompleto.

Il vantaggio di seguire questa sequenza è che ogni passaggio produce un’evidenza concreta. Non ti affidi a un “sembra installato”, ma a segnali verificabili: stato del servizio, log, risposta del socket e comportamento reale di un container. È il modo più rapido per evitare sorprese quando Docker diventa la base di una piattaforma più ampia.

Assunzione: host Debian 13 Trixie aggiornato, accesso root o sudo, connettività HTTPS verso il repository Docker e nessun vincolo aziendale che imponga mirror o proxy diversi da quelli standard.