Come installare Docker e Portainer su Raspberry Pi

Prerequisiti & Hardware Necessario

• Hardware: Raspberry Pi 4 Model B o Raspberry Pi 5, rete Ethernet consigliata, alimentatore ufficiale e almeno 32 GB di memoria affidabile. Per il Raspberry Pi 4: Raspberry Pi 4 Model B 4GB. Per il Raspberry Pi 5: Raspberry Pi 5 4GB con alimentatore ufficiale.
• Software di base: Raspberry Pi OS 64-bit aggiornato, basato su Debian, installato sul supporto di avvio. Il sistema operativo e Docker Engine sono software distinti: Docker non è il sistema operativo e Portainer non è Docker.
• Accesso: account con sudo, indirizzo IP locale stabile e accesso SSH o terminale locale.
• Rete: la porta TCP 9443 sarà usata dall’interfaccia HTTPS di Portainer; la porta 8000 serve solo per gli Edge Agent e non è necessaria in una semplice installazione locale.

Procedura passo-passo

1. Controlla l’architettura e aggiorna Raspberry Pi OS. Esegui:

   dpkg --print-architecture
   cat /etc/os-release
   sudo apt update && sudo apt full-upgrade -y

   Per questa guida usa Raspberry Pi OS 64-bit su Raspberry Pi 4 o 5. L’output dell’architettura deve essere normalmente arm64; non confondere arm64 con amd64.

2. Installa i prerequisiti del repository Docker.

   sudo apt install -y ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/raspbian/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc

3. Aggiungi il repository Docker per Raspberry Pi OS. Il comando usa il codename dichiarato dal sistema e l’architettura rilevata:

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

   Se il codename del sistema non è pubblicato dal repository Docker, non forzare un codename diverso: usa la procedura Debian compatibile indicata dalla documentazione ufficiale.

4. Installa Docker Engine e Docker 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

5. Verifica Docker prima di aggiungere Portainer.

   sudo docker run --rm hello-world
   sudo docker version
   sudo docker compose version

   Il primo comando scarica un’immagine di test e termina il container. Non usare l’installazione tramite snap per questa procedura.

6. Abilita l’uso di Docker per il tuo utente. Aggiungi l’utente corrente al gruppo Docker e ricarica la sessione SSH:

   sudo usermod -aG docker "$USER"
   exit

   Ricollegati via SSH, poi verifica con docker run --rm hello-world. Il gruppo Docker equivale a privilegi elevati sul demone: aggiungi solo utenti fidati.

7. Crea il volume persistente di Portainer.

   docker volume create portainer_data

   Il volume contiene il database e la configurazione di Portainer. Non eliminarlo quando aggiorni il container.

8. Avvia Portainer Community Edition. Usa un tag stabile documentato da Portainer; l’esempio seguente usa il tag lts:

   docker run -d   --name portainer   --restart=always   -p 9443:9443   -v /var/run/docker.sock:/var/run/docker.sock   -v portainer_data:/data   portainer/portainer-ce:lts

   Il socket Docker consente a Portainer Server di amministrare il motore locale. La pubblicazione su 9443 usa il certificato autofirmato generato da Portainer.

9. Completa l’inizializzazione. Recupera l’IP del Raspberry Pi con hostname -I e apri https://IP_DEL_RASPBERRY:9443. Crea subito l’utente amministratore con una password lunga. Il browser può mostrare un avviso perché il certificato iniziale è autofirmato.
10. Controlla il container e le porte.

    docker ps --filter name=portainer
    docker logs --tail=50 portainer
    ss -lnt | grep 9443

    Devi vedere il container in stato Up e la porta 9443 in ascolto. Non pubblicare la porta 9000 HTTP né esporre Portainer direttamente su Internet senza un reverse proxy e autenticazione adeguati.

Verifica del funzionamento

Docker è installato correttamente se docker run --rm hello-world termina con il messaggio di conferma e il servizio risulta attivo. Portainer è operativo se docker ps mostra il container portainer in esecuzione, https://IP_DEL_RASPBERRY:9443 apre la procedura iniziale e l’ambiente locale risulta connesso nella dashboard. Riavvia il Raspberry Pi e verifica che il container ritorni automaticamente grazie a --restart=always.

Problemi comuni

Problema	Causa	Soluzione
docker: permission denied	La sessione non ha ancora recepito il gruppo Docker	Riconnettiti dopo sudo usermod -aG docker "$USER" oppure usa temporaneamente sudo docker.
Repository Docker senza Release file	Codename Raspberry Pi OS non supportato dal repository scelto	Controlla VERSION_CODENAME e segui la procedura ufficiale per la distribuzione Debian compatibile; non sostituire il codename alla cieca.
Portainer non raggiungibile sulla porta 9443	Container fermo, porta già occupata o indirizzo IP errato	Controlla docker ps -a, docker logs portainer e ss -lnt | grep 9443; cambia la porta a sinistra di 9443:9443 solo se necessario.
Dashboard Portainer vuota o ambiente non connesso	Socket Docker non montato oppure permessi insufficienti	Ricrea il container mantenendo -v /var/run/docker.sock:/var/run/docker.sock e verifica che Docker sia attivo.
Il Raspberry Pi diventa instabile sotto carico	Alimentazione, raffreddamento o memoria di massa insufficienti	Usa alimentatore corretto, dissipazione adeguata e supporto di avvio affidabile; Docker non corregge problemi elettrici del sistema.

FAQ essenziali

Posso installare Docker sopra Home Assistant OS?

Non con la procedura Raspberry Pi OS di questa guida. Home Assistant OS è un sistema appliance con gestione propria dei componenti aggiuntivi; per Docker Engine e Portainer usa Raspberry Pi OS, Debian/Ubuntu o una macchina virtuale dedicata.

Portainer sostituisce Docker?

No. Docker Engine esegue container, immagini, reti e volumi; Portainer CE è un’interfaccia software che amministra il motore Docker tramite il socket locale.