Come installare Docker su Proxmox VE in una macchina virtuale Debian

Prerequisiti & Hardware Necessario

• Hardware: host Proxmox VE con CPU x86-64 dotata di virtualizzazione Intel VT-x o AMD-V, storage SSD e rete cablata. Un esempio di host compatto è Beelink Mini S12 Pro Mini PC; il modello commerciale e la capacità di memoria/storage non sono requisiti di Docker.
• Software: Proxmox VE è l’hypervisor; Debian è il sistema operativo guest; Docker Engine e Docker Compose sono software installati dentro Debian. Non installare Docker direttamente sul nodo Proxmox per questa procedura.
• VM consigliata: 2 vCPU, 2–4 GiB di RAM, disco virtuale da almeno 32 GiB su SSD, controller VirtIO SCSI e scheda di rete VirtIO. Aumenta CPU, RAM e disco in base a immagini e container.
• Accesso: account amministratore Proxmox, ISO Debian 64-bit, indirizzo IP o DHCP reservation per la VM e accesso SSH alla VM.

Procedura passo-passo

1. Scarica l’ISO corretta. Usa una ISO Debian 64-bit ufficiale e caricala in Datacenter → Storage → ISO Images. La VM deve essere x86-64; non usare un’immagine ARM destinata a Raspberry Pi.
2. Crea la macchina virtuale. In Proxmox seleziona Create VM, assegna un ID, scegli l’ISO Debian, abilita QEMU Guest Agent e imposta il disco su controller VirtIO SCSI single con Discard e IO thread se disponibili. Imposta la rete su modello VirtIO (paravirtualized).
3. Assegna risorse proporzionate. Parti da 2 vCPU, 4096 MiB di RAM e 32 GiB di disco. Non attivare ballooning se il carico Docker richiede memoria riservata e prevedibile; in caso contrario puoi abilitarlo secondo la policy del nodo.
4. Installa Debian e l’agente guest. Durante l’installazione crea un utente amministrativo, abilita SSH e poi, nella VM, esegui:

   sudo apt update
   sudo apt full-upgrade -y
   sudo apt install -y qemu-guest-agent ca-certificates curl
   sudo systemctl enable --now qemu-guest-agent
   hostname -I

   Il servizio QEMU Guest Agent migliora la comunicazione tra Proxmox e il sistema guest, ma non è il demone Docker.

5. Rimuovi eventuali pacchetti Docker in conflitto. Esegui questo comando solo se la VM è nuova o non contiene già container da conservare:

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

   La disinstallazione dei pacchetti non rimuove automaticamente /var/lib/docker, ma non cancellare dati esistenti senza un backup verificato.

6. Aggiungi il repository ufficiale Docker per Debian.

   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
   Types: deb
   URIs: https://download.docker.com/linux/debian
   Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
   Components: stable
   Architectures: $(dpkg --print-architecture)
   Signed-By: /etc/apt/keyrings/docker.asc
   EOF
   sudo apt update

   Il codename della VM deve corrispondere a una release Debian supportata dal repository. Non usare il repository Ubuntu su Debian.

7. Installa Docker Engine e Compose.

   sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   sudo systemctl enable --now docker
   sudo systemctl is-active docker

8. Verifica il motore e i volumi.

   sudo docker run --rm hello-world
   sudo docker version
   sudo docker compose version
   sudo docker info | grep -E 'Docker Root Dir|Storage Driver'

   Per usare Docker senza sudo, aggiungi solo utenti fidati al gruppo Docker e riapri la sessione: sudo usermod -aG docker "$USER". L’accesso al socket Docker equivale di fatto a privilegi elevati sulla VM.

9. Distribuisci un container di prova persistente.

   sudo docker volume create test_data
   sudo docker run -d --name web-test --restart=unless-stopped   -p 8080:80   -v test_data:/usr/share/nginx/html:ro   nginx:stable
   sudo docker ps

   Raggiungi http://IP_DELLA_VM:8080 dalla LAN. In produzione pubblica solo le porte necessarie e applica la segmentazione di rete prevista dal tuo ambiente.

10. Configura il backup dal lato Proxmox. Spegni o congela correttamente i workload secondo la loro documentazione, poi pianifica un backup della VM in Datacenter → Backup. Il backup della VM e il backup dei volumi applicativi sono livelli diversi: verifica entrambi prima di considerare ripristinabile un servizio.

Verifica del funzionamento

La configurazione è corretta quando la VM mostra l’IP atteso, qemu-guest-agent è attivo, systemctl is-active docker restituisce active e il container hello-world termina con il messaggio di conferma. Il container web-test deve risultare Up, rispondere sulla porta 8080 e tornare automaticamente dopo il riavvio della VM. Dal pannello Proxmox, l’agente guest deve risultare disponibile.

Problemi comuni

Problema	Causa	Soluzione
La VM è lenta negli I/O	Disco su controller emulato o storage HDD sovraccarico	Usa VirtIO SCSI single, abilita IO thread e Discard quando compatibili, e sposta lo storage su SSD.
Il repository Docker restituisce errore	Codename Debian non supportato o chiave GPG non leggibile	Controlla /etc/os-release, permessi di /etc/apt/keyrings/docker.asc e release ufficialmente supportate.
docker: permission denied	Utente non nel gruppo Docker o sessione non ricaricata	Riconnettiti dopo sudo usermod -aG docker "$USER", oppure usa sudo per il primo test.
Il container funziona ma non è raggiungibile	Porta non pubblicata, IP errato o firewall	Controlla docker ps, ss -lnt, l’IP della VM e le regole firewall del guest e della rete.
Il backup della VM non ripristina l’app	Volume applicativo o database non coerente al momento dello snapshot	Usa backup applicativi coordinati oltre al backup Proxmox e prova periodicamente un ripristino.

FAQ essenziali

È meglio Docker in una VM o in un container LXC?

Per un primo deployment isolato e facilmente ripristinabile, una VM Debian è più semplice da separare dall’host. Docker dentro LXC richiede scelte specifiche su nesting, permessi e sicurezza; non va trattato come una VM senza ulteriori verifiche.

Posso installare Docker direttamente sul nodo Proxmox?

È tecnicamente possibile installare software Debian sul nodo, ma non è l’architettura consigliata per workload applicativi. Mantieni il nodo Proxmox dedicato all’hypervisor e usa una VM guest per Docker, così aggiornamenti e guasti restano isolati.