IT

Applicazioni

Installare Portainer CE e proteggerne l'accesso

Installa Portainer Community Edition con Docker Compose su Debian o Ubuntu: accesso tramite tunnel SSH o HTTPS limitato, rischio del socket Docker, aggiornamenti e backup.

10 min di lettura, aggiornato il 18 novembre 2026

In questa pagina

I tuoi valori

Inseriscili una volta: i comandi della guida si aggiornano.

Portainer Community Edition (CE) è un'interfaccia web che permette di gestire i container, le immagini, i volumi, le reti e gli stack di un server Docker. Questa guida ti spiega come installarlo con Docker Compose senza esporre la sua interfaccia su Internet.

Al termine della guida, Portainer ascolta solo sull'indirizzo locale del server. Vi accedi tramite un tunnel SSH oppure, se lo desideri, in HTTPS dal solo tuo indirizzo IP. Sai anche valutare il rischio legato al socket Docker, aggiornare Portainer ed eseguire il backup dei suoi dati.

Ordina un Server

Questa guida si applica ai server che amministri tu stesso:

Prerequisiti

  • Un server con Debian 12 o 13, oppure Ubuntu 22.04 o 24.04
  • Un accesso SSH con un utente che dispone di sudo
  • Docker Engine e Docker Compose installati dal repository ufficiale, come spiegato nella guida Installare Docker Engine e Docker Compose. Non usare il pacchetto snap di Docker
  • Un client SSH sul tuo computer

I comandi docker presuppongono che il tuo utente appartenga al gruppo docker. In caso contrario, aggiungi sudo davanti.

Questa guida usa la versione 2.45.3, la versione LTS più recente al momento della stesura. Controlla l'ultima versione nella pagina delle versioni di Portainer e nell'elenco delle versioni di Docker supportate.

Porte utilizzate

Porta Ruolo Pubblicazione in questa guida Da aprire nel firewall
22/tcp SSH e tunnel verso Portainer Servizio SSH del server Sì, se non lo è già
9443/tcp Interfaccia HTTPS di Portainer Solo 127.0.0.1 No
9000/tcp Interfaccia HTTP, per un reverse proxy locale 127.0.0.1, solo con l'opzione Caddy No
8000/tcp Tunnel degli Edge Agent Non pubblicata No
80 e 443/tcp Caddy Solo con l'opzione Caddy Solo con l'opzione Caddy

Comprendere il rischio del socket Docker

Portainer controlla Docker tramite il socket /var/run/docker.sock, montato nel suo container. Questo socket dà accesso all'intera API di Docker, il cui demone viene eseguito come root.

Un account che controlla Docker può ad esempio avviare un container privilegiato o montare la radice / del server in un container, quindi leggere e modificare qualsiasi file. La documentazione di Docker ricorda che solo gli utenti fidati devono poter controllare il demone.

Alcune conseguenze pratiche:

  • Il montaggio :ro del socket non ti protegge: riguarda il file, non le azioni inviate all'API di Docker
  • Riserva il ruolo di amministratore alle persone che potrebbero già essere root sul server
  • Applica rapidamente gli aggiornamenti di Portainer
  • Preferisci il tunnel SSH, che evita di esporre l'interfaccia

Passo 1: creare il progetto Compose

Crea una cartella per Portainer:

Terminale
sudo mkdir -p /opt/portainer
sudo chown "$USER": /opt/portainer
cd /opt/portainer
nano compose.yaml

Incolla questa configurazione:

YAML
services:
  portainer:
    image: portainer/portainer-ce:2.45.3
    container_name: portainer
    restart: unless-stopped
    ports:
      - "127.0.0.1:9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:
    name: portainer_data

La porta 8000 non è pubblicata, perché serve solo agli Edge Agent. Convalida il file e scarica l'immagine:

Terminale
docker compose config --quiet
docker compose pull

Passo 2: aprire il tunnel SSH

Portainer concede 5 minuti per creare il primo amministratore dopo l'avvio. Prepara quindi il tunnel prima di avviare il container.

In un terminale sul tuo computer, esegui:

Terminale
ssh -N -L 9443:127.0.0.1:9443 TUO_USER@IP_DEL_TUO_SERVER

Il comando non mostra nulla e resta attivo: è normale. Lascia aperto questo terminale mentre usi Portainer, poi chiudi il tunnel con Ctrl+C. Se la porta 9443 è già occupata sul tuo computer, usa ad esempio -L 19443:127.0.0.1:9443 e l'indirizzo https://localhost:19443.

Passo 3: avviare Portainer

Sul server, avvia il container, poi recupera il token di installazione:

Terminale
cd /opt/portainer
docker compose up -d
docker compose ps
docker logs portainer 2>&1 | grep setup_token | tail -n 1

L'ultimo comando mostra una riga setup_token=.... Questo token monouso, richiesto a partire dalle versioni 2.39.4 e 2.43, impedisce a terzi di appropriarsi di una nuova istanza. Viene rigenerato a ogni avvio finché non esiste un amministratore.

Passo 4: creare l'account amministratore

  1. Apri https://localhost:9443 nel browser.
  2. Accetta l'avviso di sicurezza: per impostazione predefinita Portainer usa un certificato autofirmato. Il traffico passa nel tunnel SSH.
  3. Scegli un nome utente e una password unica di almeno 12 caratteri.
  4. Incolla il valore del token nel campo Setup token, poi conferma.
  5. Nella schermata Edge Compute, scegli Skip se non gestisci Edge Agent.
  6. Nella procedura guidata, clicca su Get Started: l'ambiente locale viene rilevato automaticamente.

Conserva questa password in un gestore di password.

Verificare il risultato

In Portainer, apri l'ambiente local: il container portainer deve comparire nell'elenco Containers.

Sul server, controlla poi l'indirizzo di ascolto:

Terminale
docker ps --filter name=portainer --format '{{.Names}} {{.Ports}}'
curl -kI https://127.0.0.1:9443

L'output deve contenere 127.0.0.1:9443->9443/tcp e curl deve restituire una risposta HTTP. Da un'altra macchina, senza tunnel, verifica infine che nulla sia accessibile:

Terminale
nmap -Pn -p 8000,9000,9443 IP_DEL_TUO_SERVER

Nessuna di queste porte deve risultare open.

Limitare i permessi in Portainer

Alcune impostazioni riducono i rischi se più persone usano l'interfaccia:

Impostazione Posizione Raccomandazione
Account individuali User-related > Users Un account per persona, senza il ruolo di amministratore salvo necessità
Durata della sessione Settings > Authentication Riduci il valore predefinito di 8 ore se necessario
Restrizioni Docker Ambiente local > Host > Setup > Docker Security Settings Attiva in particolare Hide bind mounts for non-administrators e Hide privileged mode for non-administrators

Queste restrizioni riguardano solo gli account non amministratori. Non limitano ciò che un amministratore può fare.

Opzione: pubblicare Portainer in HTTPS con Caddy

Il tunnel SSH è sufficiente nella maggior parte dei casi. Se ti serve un indirizzo web, metti Portainer dietro un reverse proxy e limita l'accesso al tuo indirizzo IP.

Devi aver seguito la guida Caddy come reverse proxy e creato un record A per portainer.tuo-dominio.com verso IP_DEL_TUO_SERVER.

Aggiungi la porta HTTP locale in /opt/portainer/compose.yaml:

YAML
    ports:
      - "127.0.0.1:9443:9443"
      - "127.0.0.1:9000:9000"

Applica la modifica:

Terminale
cd /opt/portainer
docker compose up -d

Aggiungi poi questo sito in /etc/caddy/Caddyfile:

caddyfile
portainer.tuo-dominio.com {
	@allowed client_ip TUO_IP

	handle @allowed {
		reverse_proxy 127.0.0.1:9000
	}

	handle {
		abort
	}
}

Poiché Caddy è installato sul server e non in Docker, UFW si applica alle sue porte. Aprile, poi ricarica la configurazione:

Terminale
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

Apri https://portainer.tuo-dominio.com dal tuo indirizzo autorizzato: deve comparire la pagina di accesso. Da un'altra connessione, ad esempio un telefono con i dati mobili, la connessione deve essere interrotta.

Se il tuo indirizzo IP cambia spesso, riserva piuttosto l'accesso a una rete privata, con WireGuard o Tailscale.

Aggiornare Portainer

Esegui prima il backup di Portainer, poi leggi le note di rilascio. Sostituisci il tag dell'immagine in compose.yaml con la nuova versione, poi esegui:

Terminale
cd /opt/portainer
nano compose.yaml
docker compose pull
docker compose up -d
docker compose images

Gli altri tuoi container non vengono arrestati. Riconnettiti poi per controllare che l'ambiente local risponda. I dati restano nel volume portainer_data.

Esiste anche il tag variabile lts, ma una versione precisa ti permette di scegliere il momento dell'aggiornamento e di sapere esattamente cosa è in esecuzione.

Backup e ripristino

Un backup di Portainer contiene il suo database e i file degli stack distribuiti da Portainer. Non contiene né i tuoi container, né le tue immagini, né i dati dei loro volumi: esegui il loro backup separatamente, come spiegato nella guida Docker.

Dall'interfaccia

  1. Apri Settings, poi scorri fino a Back up Portainer.
  2. Attiva Password protect e inserisci una password.
  3. Clicca su Download backup.

Nell'edizione CE, questo backup si avvia manualmente. I backup pianificati e l'invio verso S3 sono riservati all'edizione Business.

Dal server

Questo metodo può essere pianificato. Arresta Portainer per qualche istante, senza toccare gli altri container:

Terminale
cd /opt/portainer
mkdir -p backups
docker compose stop portainer
docker run --rm -v portainer_data:/data:ro -v "$PWD/backups":/backup alpine:3 tar czf "/backup/portainer-$(date +%F).tar.gz" -C /data .
docker compose start portainer
sudo chmod 600 backups/*.tar.gz

L'archivio contiene credenziali e chiavi API. Copialo, insieme a compose.yaml, fuori dal server in una posizione cifrata.

Ripristinare l'archivio del server

Sostituisci AAAA-MM-GG con la data dell'archivio. Il contenuto attuale del volume viene eliminato:

Terminale
cd /opt/portainer
docker compose down
docker run --rm -v portainer_data:/data -v "$PWD/backups":/backup:ro alpine:3 sh -c 'find /data -mindepth 1 -delete && tar xzf /backup/portainer-AAAA-MM-GG.tar.gz -C /data'
docker compose up -d

Usa la stessa versione di Portainer del backup, o una versione più recente.

Ripristinare un file scaricato

Questo ripristino è possibile solo su una nuova istanza, con un volume vuoto. Nella schermata di inizializzazione, apri Restore Portainer from backup, scegli il file, inserisci la sua password e il token setup_token, poi clicca su Restore Portainer.

In caso di problemi

the Portainer instance timed out for security purposes

Il primo amministratore non è stato creato entro 5 minuti. Riavvia il container, poi recupera il nuovo token:

Terminale
cd /opt/portainer
docker compose restart portainer
docker logs portainer 2>&1 | grep setup_token | tail -n 1

Se questo messaggio compare su un'istanza già configurata, verifica che il volume portainer_data sia montato correttamente: senza i suoi dati, Portainer si comporta come una nuova installazione.

Il token di installazione viene rifiutato

Il token cambia a ogni avvio. Usa l'ultimo valore mostrato dal comando precedente e copialo senza spazi.

open failed: connect failed: Connection refused

Questo messaggio compare nel terminale del tunnel. Il tunnel funziona, ma nulla è in ascolto sulla porta di destinazione del server. Verifica lo stato del container con docker compose ps e i suoi log con docker compose logs --tail=50 portainer.

bind [127.0.0.1]:9443: Address already in use

La porta è già occupata sul tuo computer, spesso da un vecchio tunnel. Chiudilo o scegli un'altra porta locale, come al passo 2.

Client sent an HTTP request to an HTTPS server

Stai usando http:// sulla porta 9443. Apri https://localhost:9443.

La porta 9443 risponde da Internet

La porta è stata probabilmente pubblicata senza indirizzo locale. Controlla l'output di docker ps: se contiene 0.0.0.0:9443, correggi compose.yaml e riesegui docker compose up -d.

403 Forbidden e CSRF check failed dietro un reverse proxy

Il proxy modifica probabilmente il nome host ricevuto da Portainer. Con il blocco Caddy di questa guida, il nome originale viene conservato. Se hai un altro proxy davanti, dichiara l'indirizzo pubblico con un URL completo:

YAML
    command: --trusted-origins https://portainer.tuo-dominio.com

Un nome senza https:// provoca l'errore invalid url for trusted origin all'avvio.

Errore 502 con Caddy

Caddy non raggiunge la porta 9000. Verifica che sia pubblicata con docker ps, poi prova curl -I http://127.0.0.1:9000. Se Force HTTPS only è attivo, disattivalo passando dal tunnel SSH.

Password di amministratore persa

Un altro amministratore può reimpostarla. Altrimenti, usa lo strumento ufficiale, che mostra una nuova password:

Terminale
cd /opt/portainer
docker compose stop portainer
docker pull portainer/helper-reset-password
docker run --rm -v portainer_data:/data portainer/helper-reset-password
docker compose start portainer

Riferimenti