Installazione e configurazione di Portainer CE

Livello: Principiante
Tempo per completare: ~30 minuti

Obiettivo: Al termine di questa guida, avrai 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 deployment prevedibile e un'efficiente scalabilità dei servizi. Tuttavia, quando si eseguono dozzine di container, gestirli esclusivamente tramite la riga di comando diventa scomodo. Portainer CE risolve questo problema fornendo un'interfaccia web user-friendly per l'amministrazione di Docker: offre accesso a tutti i container, i loro stati, log e risorse, e la gestione viene eseguita in pochi clic senza perdere il controllo del sistema.

Preparazione del server

Prima dell'installazione, è necessario assicurarsi che il server sia pronto per il deployment di Portainer. Portainer stesso viene eseguito come container, quindi è necessario installare solo Docker.

Requisiti di sistema

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

Verifica della disponibilità di Docker

Connettiti al server tramite SSH. Prima di tutto, verifica se Docker è installato e se il demone è in esecuzione:

docker --version
sudo systemctl status docker

Se viene visualizzata la versione di Docker e lo stato è attivo (running), il passaggio di installazione di Docker può essere saltato.

Installazione di Docker (se necessario)

Sui nuovi server, Docker di solito non è presente. Per installarlo, esegui 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), esegui:

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

Verifica la versione del docker compose installato:

docker compose version

Distribuzione di Portainer CE in Docker

Ci sono due modi principali per eseguire Portainer: tramite il comando docker run (avvio rapido) e tramite docker-compose.yml (comodo per il versioning della configurazione).

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

Spiegazione dei parametri:

• -d – Esegui il container in background.
• -p 8000:8000 – Port forwarding per agenti Edge e tunnel.
• -p 9443:9443 – Port forwarding per l'interfaccia web sicura (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. Questo consente a Portainer di interagire e gestire il demone Docker sull'host.
• -v portainer_data:/data – Crea un volume nominato per memorizzare i 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, crea 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

Dopo l'avvio del container Portainer, diventa accessibile tramite la rete.

Passo 1. Connessione all'interfaccia web

Apri un browser e vai a: https://<indirizzo-IP-server>:9443.

Passo 2. Creazione di un utente

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

Passo 3. Connessione dell'ambiente

Dopo aver creato l'utente, Portainer ti chiederà di connettere gli ambienti. In questa fase, puoi connettere il Docker locale (già disponibile grazie al socket montato) o procedere ad aggiungere ambienti remoti tramite il pulsante "Aggiungi ambienti". Gli ambienti remoti sono utili quando è necessario gestire più server da un'unica interfaccia Portainer: ad esempio, aggiungendo host Docker in diversi data center o server con Kubernetes. La connessione avviene tramite agenti Portainer o tramite l'API utilizzando certificati TLS.

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

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

• Clicca su di esso per completare la configurazione.

La configurazione è completa. Il dashboard di Portainer (schermata principale) si aprirà con brevi statistiche su container, immagini, volumi e reti.

Funzionalità principali di Portainer

Esaminiamo le principali sezioni dell'interfaccia utilizzate per le attività di amministrazione quotidiane.

Dashboard

La schermata iniziale che visualizza il quadro generale: il numero di container in esecuzione e fermati, 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, ferma, riavvia, elimina un container con un solo clic.
• Log: La scheda "Log" fornisce accesso alla visualizzazione dei 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 di consumo CPU, memoria e rete per ciascun container. Aiuta a determinare il consumo di risorse da parte dei singoli servizi.
• Console Exec: 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 esempio, nginx:latest o mysql:8.0) direttamente dall'interfaccia.
• Rimuovi: Pulizia delle immagini non utilizzate 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. Criticamente importante per database e dati utente.

Reti

Consente di creare reti isolate per l'interazione tra container.

Ripristino delle modifiche (Rimozione di Portainer)

Se è necessario rimuovere completamente Portainer e i suoi dati dal server, segui questi passaggi:

1. Ferma e rimuovi il container Portainer:

sudo docker stop portainer
sudo docker rm portainer

2. Rimuovi il volume dati di Portainer (attenzione: questa azione è irreversibile):

sudo docker volume rm portainer_data

3. Rimuovi l'immagine di Portainer (opzionale):

sudo docker rmi portainer/portainer-ce:latest

Sicurezza e raccomandazioni

Per la produzione, è necessaria una configurazione di sicurezza aggiuntiva di Portainer.

Utilizzo di un Reverse Proxy (Nginx/Apache)

Si consiglia di configurare un sottodominio (ad esempio, portainer.domain.com) e di proxyare il traffico tramite Nginx. Questo fornirà:

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

1. Installazione e configurazione di Nginx

Installa Nginx:

sudo apt install -y nginx              # Per Debian/Ubuntu
# o
sudo dnf install -y nginx              # Per CentOS/Rocky Linux

Crea un file di configurazione per Portainer:

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

Aggiungi la seguente configurazione, sostituendo <YOUR_DOMAIN> con il tuo dominio che punta all'IP del server:

server {
    listen 80;
    server_name ;
    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;
        
        # Timeout per operazioni lunghe
        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 il controllo ha esito positivo, riavvia Nginx:

sudo systemctl restart nginx

2. Configurazione di HTTPS (consigliato)

Installa Certbot:

sudo apt install -y certbot python3-certbot-nginx

Ottieni un certificato SSL:

sudo certbot --nginx -d 

Sostituisci <YOUR_DOMAIN> con il tuo dominio.

Durante l'installazione, inserisci la tua email, ad esempio, admin@<YOUR_DOMAIN>, 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 dovrebbe essere limitato. Consenti l'accesso alle porte 8000 e 9443 solo da indirizzi IP fidati.

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 subnet degli indirizzi IP fidati.

Aggiornamenti regolari

Si consiglia di monitorare il rilascio di nuove versioni di Portainer e di aggiornare tempestivamente il container per eliminare potenziali vulnerabilità.

Verifica del funzionamento

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

1. Controllo visivo: Nella sezione "Container", assicurati che il container portainer abbia uno stato di esecuzione.

2. Creazione di un container di test:

• Vai alla sezione "Container", clicca sul pulsante "Aggiungi container".
• Nel campo "Nome", specifica test-nginx.
• Nel campo "Immagine", specifica nginx:alpine.
• Nella sezione "Mappatura delle porte", specifica la porta host 8080, la porta del container 80.
• Clicca su "Distribuisci il container".

3. Verifica dell'accessibilità:

• Attendi che il container appaia nell'elenco con uno stato di esecuzione.
• Apri un browser e vai a http://<YOUR_IP_ADDRESS>:8080. Dovrebbe essere visualizzata la pagina di benvenuto di Nginx.

4. Verifica della gestione:

• In Portainer, trova il container test-nginx e clicca sul pulsante "Ferma".
• Aggiorna la pagina di Nginx nel browser – l'accesso dovrebbe essere non disponibile.
• Clicca su "Avvia" – l'accesso alla pagina dovrebbe essere ripristinato.

Risoluzione dei problemi

Problema 1: Impossibile aprire l'interfaccia web di Portainer su https://<YOUR_IP_ADDRESS>: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 demone Docker" quando si eseguono comandi Docker.

Possibile causa: Il demone Docker non è in esecuzione o l'utente non ha i permessi.

Soluzione: Avvia il demone: sudo systemctl start docker. Se hai aggiunto l'utente al gruppo docker, disconnettiti e riconnettiti.

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

Possibile causa: Conflitto di porta o immagine corrotta.

Soluzione: Verifica se la porta 9443 è occupata da un'altra applicazione: sudo ss -tulpn | grep 9443. Prova a riassegnare la porta e riavvia il container: sudo docker restart portainer.

Conclusione

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

Questo strumento può essere utile quando è necessario fornire 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 è consigliata per l'uso sui server.

Versione del documento: 1.1
Ultimo aggiornamento: Marzo 2026
Proprietario: Team di Documentazione Tecnica