1 26/05/2026 11 min

Su Debian 11 Bullseye conviene installare Docker CE dal repository ufficiale di Docker, non dai pacchetti del repo Debian, se vuoi una versione allineata agli aggiornamenti upstream e un ciclo di rilascio prevedibile. La differenza non è cosmetica: cambia il ritmo delle patch, la disponibilità di componenti come docker-ce, docker-ce-cli e containerd.io, e soprattutto la probabilità di trovarti con versioni vecchie o dipendenze non coerenti quando devi fare troubleshooting o upgrade.

Qui parto da un’installazione pulita e verificabile. L’obiettivo è arrivare a un host con Docker Engine funzionante, servizio attivo, test di base passato e, se serve, accesso al daemon senza usare sempre sudo. Ogni passaggio include una verifica concreta, perché su sistemi reali il punto non è “installare” ma capire subito se il layer giusto sta rispondendo.

Prerequisiti e controllo dello stato iniziale

Prima di toccare i repository, verifica che il sistema sia davvero Debian 11 e che non ci siano conflitti già presenti con pacchetti Docker di origine diversa. Se hai già installazioni parziali o vecchi componenti, conviene identificarli subito per evitare mix di versioni difficili da diagnosticare dopo.

Esegui questi controlli:

cat /etc/debian_version
lsb_release -a 2>/dev/null || cat /etc/os-release
apt list --installed 2>/dev/null | grep -E 'docker|containerd|runc' || true

Atteso: Debian 11 o Bullseye nei dati di release, e nessun pacchetto Docker inatteso se parti da zero. Se trovi docker.io installato dal repository Debian, non è un errore in sé, ma devi decidere se sostituirlo con Docker CE o mantenere la versione distro. Per una guida orientata a Docker CE, la strada pulita è rimuovere i pacchetti in conflitto prima dell’installazione ufficiale.

Se il nodo è in produzione o ospita servizi già attivi, considera il blast radius: la rimozione di pacchetti può impattare container esistenti, unit systemd personalizzate e dipendenze applicative. Fai uno snapshot o un backup della macchina se l’infrastruttura lo consente, oppure almeno esporta l’elenco dei container e le configurazioni rilevanti prima di procedere.

Rimozione di eventuali pacchetti in conflitto

Se il sistema ha già docker.io, podman-docker o vecchi componenti Docker, la scelta più pulita è rimuoverli prima di installare Docker CE. Non è una procedura distruttiva sui dati dei container se i volumi sono separati, ma resta una modifica da trattare con attenzione.

Comandi tipici:

sudo apt remove -y docker.io docker-doc docker-compose podman-docker containerd runc

Verifica subito cosa è rimasto installato:

dpkg -l | grep -E 'docker|containerd|runc' || true

Se il comando non restituisce nulla, hai un punto di partenza pulito. Se invece compaiono pacchetti che sai di dover mantenere per altri servizi, fermati e valuta le dipendenze prima di continuare. Qui il principio è semplice: meglio risolvere il conflitto ora che inseguire un daemon che non parte più tardi.

Aggiunta del repository ufficiale Docker per Bullseye

Per installare Docker CE su Debian 11 servono tre cose: trasporto HTTPS per APT, chiave GPG del repository e sorgente pacchetti Docker. La sequenza è importante perché ti permette di verificare ogni passaggio senza assumere che la rete o il repository siano sani.

Installa i prerequisiti:

sudo apt update
sudo apt install -y ca-certificates curl gnupg

Atteso: installazione senza errori e repository di base raggiungibili. Se apt update fallisce, non è un problema Docker: hai prima un tema di connettività, DNS o mirror Debian da risolvere.

Crea la directory per le chiavi e importa la chiave del repository Docker in formato dearmored, che è la modalità corretta per APT moderno:

sudo install -m 0755 -d /etc/apt/keyrings
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

Verifica che il file esista e abbia permessi leggibili da APT:

ls -l /etc/apt/keyrings/docker.gpg

Atteso: un file presente con permessi almeno -rw-r--r--. Se il download della chiave fallisce, non forzare oltre: controlla proxy, TLS inspection aziendale o restrizioni outbound. In ambienti con filtraggio stretto, il problema spesso non è Docker ma la catena di uscita HTTPS.

Ora aggiungi il repository per Bullseye. Il file sorgente deve puntare alla distribuzione corretta e usare la chiave appena importata:

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

Controlla il contenuto effettivo del repository configurato:

cat /etc/apt/sources.list.d/docker.list

Atteso: una riga con bullseye stable. Se qui compare un codename diverso, non andare avanti alla cieca: stai installando contro il repository sbagliato e ti esponi a errori di dipendenza o a pacchetti non compatibili.

Installazione di Docker CE, CLI e containerd

A questo punto aggiorna l’indice pacchetti e installa il set minimo utile: engine, CLI e containerd. In molti casi è sensato includere anche docker-buildx-plugin e docker-compose-plugin, così non dipendi da binari esterni per build e compose moderni.

Comando di installazione:

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

Se vuoi ridurre al minimo, puoi limitarti a docker-ce docker-ce-cli containerd.io, ma nella pratica i plugin sono comodi e allineano meglio l’esperienza operativa. Dopo l’installazione, verifica le versioni installate:

docker --version
sudo docker version

Atteso: il client risponde, e anche il daemon lato server restituisce informazioni sulla versione. Se docker --version funziona ma sudo docker version no, il problema non è il binario ma il servizio o il socket del daemon.

Per controllare quali pacchetti sono stati effettivamente installati:

dpkg -l | grep -E '^ii\s+(docker-ce|docker-ce-cli|containerd.io|docker-buildx-plugin|docker-compose-plugin)'

Se manca containerd.io o compare un messaggio di dipendenze non soddisfatte, fermati e leggi l’errore: spesso indica repository non aggiornati, pacchetti residui o architettura non coerente. In questi casi non serve “riprovare”: serve capire quale vincolo APT sta bloccando la transazione.

Avvio del servizio e verifica del socket

Con i pacchetti installati, il punto successivo è il servizio systemd. Docker su Debian si appoggia a docker.service e al socket docker.socket. È utile verificare entrambi, perché un problema può essere nel daemon, nel socket o nelle policy locali.

Abilita e avvia il servizio:

sudo systemctl enable --now docker

Controlla lo stato:

systemctl status docker --no-pager
systemctl status containerd --no-pager

Atteso: entrambi i servizi in stato active (running). Se docker fallisce ma containerd è attivo, il problema è quasi sempre di configurazione del daemon, permessi sul socket o residui di configurazioni precedenti. I log più utili, in ordine, sono:

journalctl -u docker -n 50 --no-pager
journalctl -u containerd -n 50 --no-pager

Se vedi errori su cgroup, storage driver o namespace, non forzare una reinstallazione alla cieca. Il messaggio preciso nel journal è la traccia da seguire. In un’installazione standard su Debian 11, Docker CE dovrebbe partire senza interventi speciali; quando non succede, c’è quasi sempre una causa esterna, non “Docker rotto”.

Uso senza sudo: gruppo docker e implicazioni di sicurezza

Per comodità operativa puoi aggiungere il tuo utente al gruppo docker. È una scelta pratica, ma va capita bene: chi appartiene al gruppo Docker ha di fatto un potere molto elevato sul sistema host, perché può avviare container con mount sensibili e aggirare molti controlli locali. Non è un dettaglio da glossario, è una decisione di sicurezza.

Se accetti questo trade-off, esegui:

sudo usermod -aG docker $USER

Poi esci e rientra nella sessione, oppure applica il nuovo gruppo senza logout con:

newgrp docker

Verifica l’appartenenza al gruppo:

id | grep -o 'docker' || true

Test senza sudo:

docker ps

Se il comando restituisce la lista dei container o una tabella vuota senza errori, il socket è accessibile e il daemon risponde. Se ottieni permission denied, controlla id e il gruppo del socket con:

ls -l /var/run/docker.sock

Atteso: proprietario root:docker e permessi coerenti con l’accesso del gruppo. Se il gruppo utente non coincide, non cambiare i permessi del socket a mano: stai alterando il modello di sicurezza del servizio.

Test operativo con un container minimale

La verifica che conta davvero è il pull e l’esecuzione di un container banale. Questo test copre accesso al registry, runtime, networking di base e scrittura sul filesystem del container. Non sostituisce il testing applicativo, ma ti dice se il motore è sano.

Esegui un container di prova:

docker run --rm hello-world

Atteso: messaggio di benvenuto di Docker e uscita con codice zero. Se il pull fallisce, separa il problema in tre ipotesi: connettività verso Docker Hub, DNS locale o proxy aziendale. Una diagnosi rapida:

getent hosts registry-1.docker.io
curl -I https://registry-1.docker.io/v2/
docker info

Se getent hosts fallisce, hai un problema DNS. Se curl -I non raggiunge il registry, guarda proxy e firewall. Se docker info mostra errori sul daemon, torna ai log di systemd. Qui l’ordine conta: non ha senso rifare il test container se il layer di rete è già rotto.

Configurazione base del daemon e aspetti pratici

Su Debian 11, in molti casi Docker funziona bene con la configurazione di default. Quando però devi standardizzare il comportamento, la configurazione del daemon si gestisce in /etc/docker/daemon.json. È il posto giusto per impostare, per esempio, registry mirror, log driver o storage options, ma va trattato con disciplina: un JSON malformato basta a impedire l’avvio del servizio.

Esempio minimale, solo come riferimento strutturale:

{ "log-driver": "json-file", "log-opts": { "max-size": "10m", "max-file": "3" }
}

Dopo una modifica del genere, la verifica minima è sempre la stessa:

sudo systemctl restart docker
sudo systemctl status docker --no-pager
journalctl -u docker -n 50 --no-pager

Se il file JSON è errato, il journal lo indica chiaramente. In quel caso il rollback è semplice: ripristina il backup del file e riavvia il servizio. Per questo, prima di toccare daemon.json, conviene avere una copia versionata o almeno un backup locale:

sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak.$(date +%F_%H%M%S)

Questo approccio riduce il rischio di restare con un daemon non avviabile dopo una modifica banale. È una buona abitudine anche quando il cambio sembra innocuo.

Aggiornamento, manutenzione e rollback

Una volta installato Docker CE, gli aggiornamenti seguono il normale flusso APT. Prima di aggiornare in produzione, però, conviene sapere cosa stai cambiando: il motore, la CLI o entrambi, e se ci sono container con dipendenze sensibili da versioni specifiche. Non serve congelare tutto, ma serve una finestra di manutenzione coerente con il carico.

Verifica gli aggiornamenti disponibili:

apt list --upgradable | grep -E 'docker|containerd' || true

Per aggiornare in modo controllato:

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

Il rollback, quando necessario, dipende dalla strategia di packaging disponibile nel tuo repository APT e dall’eventuale cache dei pacchetti. In linea generale, se devi tornare indietro, il primo passo è identificare la versione installata e quella precedente disponibile:

apt-cache policy docker-ce docker-ce-cli containerd.io

Se hai versioni precedenti ancora presenti nei repository, puoi pinning o reinstallazione mirata. Se non le hai più, il rollback richiede una fonte pacchetti accessibile o un mirror interno. Anche qui vale la regola pratica: non fare upgrade di runtime critici senza sapere come tornare alla versione precedente.

Errori comuni su Debian 11 e come leggerli

Ci sono alcuni errori ricorrenti che vale la pena riconoscere al volo. Se apt update segnala problemi di firma, il repository o la chiave sono il punto da controllare. Se docker risponde ma il daemon no, il servizio systemd o il socket sono il layer da ispezionare. Se i container partono ma non escono su rete, il problema è più avanti: bridge, firewall o policy esterne.

Una triage rapida può usare questi comandi:

apt update
systemctl is-active docker containerd
journalctl -u docker -n 20 --no-pager
docker info
docker run --rm hello-world

Atteso: nessun errore di firma, servizi attivi, docker info coerente e test container completato. Se uno di questi punti fallisce, non proseguire con altri cambiamenti finché non hai localizzato il layer guasto. È il modo più rapido per evitare diagnosi confuse e modifiche inutili.

Scelta operativa consigliata

Se stai allestendo un server nuovo su Debian 11 Bullseye, la combinazione più sensata è repository ufficiale Docker, installazione di docker-ce e containerd.io, test con hello-world e, solo se serve, aggiunta dell’utente al gruppo docker. È una sequenza semplice, ma soprattutto è diagnosticabile: ogni passaggio ha un controllo chiaro e un rollback ragionevole.

Se invece stai intervenendo su un host già usato da altri servizi, il punto non è “installare Docker” ma farlo senza rompere il resto. In quel caso il prerequisito vero è la visibilità: stato dei pacchetti, journal del daemon, carico dei container esistenti e strategia di ritorno indietro. Senza questi elementi, la procedura è solo metà del lavoro.

Assunzione operativa: il sistema parte da Debian 11 Bullseye standard, senza proxy o firewall restrittivi non dichiarati, e l’obiettivo è un’installazione Docker CE funzionale e verificata localmente.