Implementazione di Portainer CE in Docker per la gestione dei container

Livello: Principiante
Tempo necessario: circa 30 minuti
Obiettivo: al termine di questa guida, avrai a disposizione un pannello Portainer CE completamente configurato, protetto con HTTPS e pronto per gestire l’infrastruttura Docker del tuo server. Al termine di questa guida, avrai a disposizione un pannello Portainer CE completamente configurato, protetto con HTTPS e pronto per gestire l’infrastruttura Docker del tuo server.

Introduzione

La containerizzazione basata su Docker è diventata lo standard per l’infrastruttura server, garantendo un’implementazione prevedibile e un ridimensionamento efficiente dei servizi. Tuttavia, quando si eseguono decine di container, gestirli esclusivamente tramite la riga di comando diventa scomodo. Portainer CE risolve questo problema fornendo un’interfaccia web intuitiva per l’amministrazione di Docker: consente di accedere a tutti i container, ai loro stati, ai log e alle risorse, e la gestione avviene con pochi clic senza perdere il controllo del sistema.

Preparazione del server

Prima dell’installazione, è necessario assicurarsi che il server sia pronto per l’implementazione di Portainer. Portainer stesso viene eseguito come un container, quindi è sufficiente installare Docker.

Requisiti di sistema:

• Sistema operativo: qualsiasi distribuzione Linux (Ubuntu 20.04+, Debian 11+, CentOS/Rocky Linux 8+) utilizzata nell'hosting.
• Privilegi: accesso come root o la possibilità di eseguire comandi tramite sudo.
• Requisiti hardware: almeno 1 GB di RAM e 10 GB di spazio libero su disco.
• Requisiti di rete: porte 8000 e 9443 aperte per l’accesso a Portainer, porta 443 per la configurazione del proxy inverso.

Verifica della disponibilità di Docker

Connettersi al server tramite SSH. Innanzitutto, verificare se Docker è installato e se il daemon è in esecuzione:

docker --version
sudo systemctl status docker

Se viene visualizzata la versione di Docker e lo stato è attivo (in esecuzione), è possibile saltare la fase di installazione di Docker.

Installazione di Docker (se necessario)

Sui nuovi server, Docker in genere non è presente. Per installarlo, eseguire lo script standard (per Debian/Ubuntu):

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable docker
sudo systemctl start docker

Per installare il plugin Docker Compose (se non è stato installato nel passaggio precedente), eseguire:

sudo apt-get install docker-compose-plugin   # For Debian/Ubuntu
# or
sudo dnf install docker-compose-plugin       # For CentOS/Rocky Linux

Verifica la versione di Docker Compose installata:

docker compose version

Distribuzione di Portainer CE in Docker

Esistono due modi principali per eseguire Portainer: tramite il comando `docker run` (avvio rapido) e tramite il file `docker-compose.yml` (utile per la gestione delle versioni delle configurazioni).

Metodo 1: Esecuzione tramite `docker run`

Esegui il seguente comando sul server:

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

sudo usermod -aG docker $USER

Dopo aver eseguito il comando, è necessario disconnettersi e riconnettersi, oppure riavviare la sessione.

Spiegazione dei parametri:

• -d – Esegue il container in background.
• -p 8000:8000 – Inoltro delle porte per gli agenti Edge e i tunnel.
• -p 9443:9443 – Reindirizzamento delle porte per l’interfaccia web protetta (HTTPS). Portainer genera automaticamente un certificato SSL autofirmato.
• --name portainer – Assegna un nome significativo al container.
• --restart=always – Politica di riavvio automatico del container in caso di errori o riavvio del server.
• -v /var/run/docker.sock:/var/run/docker.sock – Monta il socket Docker all’interno del container Portainer. Ciò consente a Portainer di interagire con il daemon Docker sull’host e di gestirlo.
• -v portainer_data:/data – Crea un volume denominato per l'archiviazione dei dati di Portainer (utenti, impostazioni, configurazioni di connessione).
• portainer/portainer-ce:latest – L’immagine con l’ultima versione stabile della Community Edition.

Metodo 2: Esecuzione tramite docker-compose

Per utilizzare questo metodo, creare una directory e un file docker-compose.yml:

mkdir ~/portainer-docker
cd ~/portainer-docker
nano docker-compose.yml

Inserisci il seguente contenuto:

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: always
    ports:
      - "8000:8000"
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:

Salva il file ed esegui il comando:

docker compose up -d

Avvio iniziale e configurazione dell’interfaccia web

Una volta avviato il container Portainer, questo diventa accessibile tramite la rete.

Passaggio 1. Connessione all'interfaccia web

Apri un browser e vai all'indirizzo: https://:9443.

A causa dell’uso di un certificato autofirmato, il browser visualizzerà un avviso. È necessario procedere all’accesso al sito.

Passaggio 2. Creazione di un utente

Nella pagina di registrazione, dovrai specificare un nome utente (si consiglia "admin") e impostare una password complessa.

Passo 3. Connessione dell’ambiente

Dopo aver creato l'utente, Portainer chiederà di collegare gli ambienti. A questo punto, è possibile collegare il Docker locale (già disponibile grazie al socket montato) oppure procedere all'aggiunta di ambienti remoti tramite il pulsante "Aggiungi ambienti".

Gli ambienti remoti sono utili quando è necessario gestire più server da un'unica interfaccia di Portainer: ad esempio, aggiungendo host Docker in diversi data center o server con Kubernetes. La connessione avviene tramite gli agenti di Portainer o tramite l’API utilizzando certificati TLS.

• Selezionare l’opzione "Inizia". Questo è lo scenario di base per un singolo server.



• Portainer rileverà automaticamente il socket Docker locale. Verrà visualizzato come "locale".



• Fare clic su di esso per completare la configurazione.

La configurazione è completata. Si aprirà la dashboard di Portainer (schermata principale) con brevi statistiche su container, immagini, volumi e reti.

Caratteristiche principali di Portainer

Diamo un'occhiata alle sezioni principali dell’interfaccia utilizzate per le attività amministrative quotidiane.

Dashboard

La schermata iniziale che mostra il quadro generale: il numero di container in esecuzione e arrestati, il numero di immagini scaricate. Consente di valutare rapidamente lo stato del server.

Container

• La sezione centrale di gestione. Visualizza un elenco di tutti i container.
• Gestione dei container: avvia, arresta, riavvia o elimina un container con un solo clic.
• Log: la scheda "Log" consente di visualizzare i log dei container in tempo reale.
• Ispeziona: visualizza informazioni complete sul container in formato JSON: variabili d’ambiente, punti di montaggio, impostazioni di rete.
• Statistiche: grafici relativi all’utilizzo di CPU, memoria e rete per ciascun container. Aiutano a determinare il consumo di risorse da parte dei singoli servizi.
• Console di esecuzione: possibilità di aprire un terminale web all’interno di un container per eseguire comandi.

Stack

Implementazione di Docker Compose nell’interfaccia web. Consente di caricare o creare file YAML direttamente tramite il browser per distribuire applicazioni multi-container.

Immagini

• Gestione delle immagini Docker.
• Pull: possibilità di scaricare immagini (ad es. nginx:latest o mysql:8.0) direttamente dall’interfaccia.
• Rimuovi: eliminazione delle immagini inutilizzate per liberare spazio su disco.

Volumi

Gestione dei volumi di dati persistenti. Visualizza i volumi esistenti, il loro collegamento ai container e lo spazio che occupano. Di fondamentale importanza per i database e i dati degli utenti.

Reti

Consente di creare reti isolate per l’interazione tra i container.

Ripristino delle modifiche (Rimozione di Portainer)

Se è necessario rimuovere completamente Portainer e i relativi dati dal server, procedere come segue:

1. Arresta e rimuovi il container di Portainer:

sudo docker stop portainer
sudo docker rm portainer

2. Rimuovere il volume dei dati di Portainer (attenzione: questa operazione è irreversibile):

sudo docker volume rm portainer_data

3. Rimuovere l'immagine di Portainer (facoltativo):

sudo docker rmi portainer/portainer-ce:latest

Sicurezza e raccomandazioni

Per l’ambiente di produzione, è necessaria una configurazione di sicurezza aggiuntiva di Portainer.

Utilizzo di un proxy inverso (Nginx/Apache)

Si consiglia di configurare un sottodominio (ad es., portainer.domain.com) e di instradare il traffico tramite Nginx. Ciò garantirà:

• L'utilizzo di un certificato SSL valido (gratuito da Let's Encrypt o a pagamento, ad esempio da Sectigo).
• Registrazione centralizzata degli accessi.
• Possibilità di configurare un'autenticazione aggiuntiva.

1. Installazione e configurazione di Nginx

Installare Nginx:

sudo apt install -y nginx              # For Debian/Ubuntu
# or
sudo dnf install -y nginx              # For CentOS/Rocky Linux

Creare un file di configurazione per Portainer:

sudo nano /etc/nginx/sites-available/portainer.conf

Aggiungere la seguente configurazione, sostituendo con il proprio dominio che punta all'IP del server:

server {
    listen 80;
    server_name <YOUR_DOMAIN>;

    location / {
        proxy_pass https://localhost:9443;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        
        # Timeouts for long operations
        proxy_connect_timeout 600;
        proxy_send_timeout 600;
        proxy_read_timeout 600;
        send_timeout 600;
    }
}

Attiva la configurazione:

sudo ln -s /etc/nginx/sites-available/portainer.conf /etc/nginx/sites-enabled/

Verifica la configurazione di Nginx:

sudo nginx -t

Se la verifica ha esito positivo, riavvia Nginx:

sudo systemctl restart nginx

2. Configurazione di HTTPS (consigliato)

Installa Certbot:

sudo apt install -y certbot python3-certbot-nginx

Ottenere un certificato SSL:

sudo certbot --nginx -d <your_domain></your_domain>

Sostituisci con il tuo dominio.

Durante l'installazione, inserisci il tuo indirizzo e-mail, ad esempio admin@, quindi premi Y due volte.

Verifica il rinnovo automatico del certificato:

sudo systemctl list-timers | grep certbot

Configurazione del firewall

L'accesso diretto alle porte di Portainer deve essere limitato. Consenti l'accesso alle porte 8000 e 9443 solo da indirizzi IP affidabili.

Esempio per UFW:

sudo ufw allow from 192.168.1.0/24 to any port 9443 proto tcp
sudo ufw deny 9443

Dove 192.168.1.0/24 è la sottorete degli indirizzi IP affidabili.

Aggiornamenti regolari

Si raccomanda di tenere sotto controllo il rilascio di nuove versioni di Portainer e di aggiornare il container tempestivamente per eliminare potenziali vulnerabilità.

Verifica del funzionamento

Per verificare che Portainer funzioni correttamente, eseguire le seguenti azioni.

1. Controllo visivo: nella sezione "Container", assicurarsi che il container di Portainer abbia lo stato "in esecuzione".
2. Creazione di un container di prova:
   • Accedere alla sezione "Container", fare clic sul pulsante "Aggiungi container".
   • Nel campo "Nome", specificare test-nginx.
   • Nel campo "Immagine", specificare nginx:alpine.
   • Nella sezione "Mappatura delle porte", specificare la porta host 8080 e la porta del container 80.
   • Fare clic su "Distribuisci il container".
3. Verifica dell’accessibilità:
   • Attendere che il container compaia nell'elenco con lo stato "In esecuzione".
   • Apri un browser e vai su http://<IL_TUO_INDIRIZZO_IP>:8080. Dovrebbe essere visualizzata la pagina di benvenuto di Nginx.
4. Verifica della gestione:
   • In Portainer, individuare il container test-nginx e fare clic sul pulsante "Stop".
   • Aggiorna la pagina di Nginx nel browser: l'accesso dovrebbe risultare indisponibile.
   • Fai clic su "Start": l'accesso alla pagina dovrebbe essere ripristinato.

Risoluzione dei problemi

Problema 1: Impossibile aprire l’interfaccia web di Portainer all’indirizzo https://:9443

Possibile causa: il firewall sta bloccando la porta 9443.
Soluzione: controlla le regole del firewall e assicurati che la porta sia aperta. Per UFW: sudo ufw status | grep 9443.

Problema 2: Errore "Impossibile connettersi al daemon di Docker" durante l'esecuzione dei comandi Docker.

Possibile causa: il daemon di Docker non è in esecuzione oppure l'utente non dispone dei permessi necessari.
Soluzione: Avvia il daemon: sudo systemctl start docker. Se hai aggiunto l’utente al gruppo docker, esci e accedi nuovamente.

Problema 3: Il container Portainer non si avvia e si chiude immediatamente (stato "exited").

Possibile causa: conflitto di porte o immagine danneggiata.
Soluzione: verificare se la porta 9443 è occupata da un'altra applicazione: sudo ss -tulpn | grep 9443. Provare a riassegnare la porta e riavviare il container: sudo docker restart portainer.

Conclusione

Portainer CE offre uno strumento efficace per il monitoraggio e la gestione visiva dei container Docker. La possibilità di valutare rapidamente lo stato dei container, analizzare i grafici di consumo delle risorse ed eseguire operazioni tipiche senza connettersi tramite SSH riduce i tempi di risposta agli incidenti e semplifica l’amministrazione quotidiana.

Questo strumento può rivelarsi utile quando è necessario fornire un accesso limitato alla gestione dei container a sviluppatori o personale meno esperto, senza concedere l’accesso diretto alla riga di comando del server. Portainer CE è una soluzione standard per la visualizzazione dell’infrastruttura dei container ed è consigliato per l’uso sui server.

---

Versione del documento: 1 .1
Ultimo aggiornamento: marzo 2026
Responsabile: Team di documentazionetecnica