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.
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
:rodel 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
rootsul 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:
sudo mkdir -p /opt/portainer
sudo chown "$USER": /opt/portainer
cd /opt/portainer
nano compose.yamlIncolla questa configurazione:
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_dataLa porta 8000 non è pubblicata, perché serve solo agli Edge Agent. Convalida il file e scarica l'immagine:
docker compose config --quiet
docker compose pullPasso 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:
ssh -N -L 9443:127.0.0.1:9443 TUO_USER@IP_DEL_TUO_SERVERIl 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:
cd /opt/portainer
docker compose up -d
docker compose ps
docker logs portainer 2>&1 | grep setup_token | tail -n 1L'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
- Apri
https://localhost:9443nel browser. - Accetta l'avviso di sicurezza: per impostazione predefinita Portainer usa un certificato autofirmato. Il traffico passa nel tunnel SSH.
- Scegli un nome utente e una password unica di almeno 12 caratteri.
- Incolla il valore del token nel campo Setup token, poi conferma.
- Nella schermata Edge Compute, scegli Skip se non gestisci Edge Agent.
- 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:
docker ps --filter name=portainer --format '{{.Names}} {{.Ports}}'
curl -kI https://127.0.0.1:9443L'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:
nmap -Pn -p 8000,9000,9443 IP_DEL_TUO_SERVERNessuna 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:
ports:
- "127.0.0.1:9443:9443"
- "127.0.0.1:9000:9000"Applica la modifica:
cd /opt/portainer
docker compose up -dAggiungi poi questo sito in /etc/caddy/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:
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyApri 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:
cd /opt/portainer
nano compose.yaml
docker compose pull
docker compose up -d
docker compose imagesGli 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
- Apri Settings, poi scorri fino a Back up Portainer.
- Attiva Password protect e inserisci una password.
- 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:
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.gzL'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:
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 -dUsa 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:
cd /opt/portainer
docker compose restart portainer
docker logs portainer 2>&1 | grep setup_token | tail -n 1Se 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:
command: --trusted-origins https://portainer.tuo-dominio.comUn 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:
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