IT

Applicazioni

Installare Nginx Proxy Manager

Installare Nginx Proxy Manager con Docker su Debian o Ubuntu, tenere la sua interfaccia fuori da Internet, pubblicare un servizio in HTTPS, limitare gli accessi, aggiornare ed eseguire il 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.

Nginx Proxy Manager (NPM) è un reverse proxy basato su Nginx, gestito da un'interfaccia web. Riceve i visitatori sulle porte 80 e 443, richiede i certificati Let's Encrypt e inoltra le richieste ai tuoi servizi, senza che tu debba scrivere alcuna configurazione Nginx.

Al termine della guida, NPM funziona in Docker e la sua interfaccia di amministrazione è accessibile solo tramite un tunnel SSH. Un servizio di prova risponde su https://app.tuo-dominio.com e sai limitare un accesso, aggiornare NPM ed eseguire il backup dei suoi dati.

La versione utilizzata è la 2.17.0, l'ultima versione stabile al momento della stesura, a novembre 2026.

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, con architettura amd64 o arm64
  • Un accesso SSH con un utente che dispone di sudo e appartiene al gruppo docker
  • Docker Engine e Docker Compose, installati con la guida Installare Docker Engine e Docker Compose
  • Un nome di dominio di cui gestisci la zona DNS
  • Nessun altro software sulle porte 80 e 443, come Nginx, Apache, Caddy o Traefik

Porte utilizzate

Porta Direzione Ruolo Da aprire
80/tcp In entrata Validazione Let's Encrypt e reindirizzamento a HTTPS Sì
443/tcp In entrata Siti pubblicati in HTTPS Sì
81/tcp Locale Interfaccia di amministrazione, su 127.0.0.1 No

Passo 1: far puntare il dominio al server

Crea un record A per app.tuo-dominio.com verso IP_DEL_TUO_SERVER. Se il tuo dominio è gestito presso HostMyServers, segui la guida Creare un record A.

Verifica poi il risultato dal server:

Terminale
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.tuo-dominio.com
dig +short AAAA app.tuo-dominio.com

Il primo comando deve restituire l'indirizzo del tuo server. Se il secondo restituisce un indirizzo IPv6, anch'esso deve corrispondere a questo server. In caso contrario, elimina questo record AAAA.

Passo 2: preparare la cartella e la rete

Crea la cartella del progetto, poi una rete Docker condivisa tra NPM e i servizi da pubblicare:

Terminale
sudo install -d -o "$USER" -g "$USER" /opt/npm
docker network create proxy

Passo 3: scrivere il file Compose

Terminale
nano /opt/npm/compose.yaml
YAML
services:
  npm:
    image: jc21/nginx-proxy-manager:2.17.0
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "127.0.0.1:81:81"
    environment:
      TZ: "Europe/Paris"
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    networks:
      - proxy

networks:
  proxy:
    external: true
Elemento Ruolo
127.0.0.1:81:81 Rende l'interfaccia accessibile solo dal server
./data Database SQLite, chiavi dell'applicazione, configurazione degli host e log
./letsencrypt Certificati e chiavi private
proxy Rete attraverso cui NPM raggiunge i tuoi servizi

Passo 4: avviare NPM

Terminale
cd /opt/npm
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs -f npm

Il primo avvio inizializza il database e genera le chiavi, il che può richiedere qualche minuto. Esci dai log con Ctrl+C, poi controlla le porte:

Terminale
sudo ss -ltnp | grep -E ':(80|81|443) '

La porta 81 deve comparire solo su 127.0.0.1.

Passo 5: controllare il firewall

Docker pubblica le porte 80 e 443 con le proprie regole, applicate prima di quelle di UFW. Queste due porte sono quindi raggiungibili anche senza ufw allow, e UFW non può limitarle. Per questo motivo la porta 81 deve essere limitata in compose.yaml, e non in UFW. La guida Configurare il firewall UFW descrive in dettaglio questo funzionamento.

Se usi il firewall integrato della tua istanza, autorizza anche le porte 80 e 443 dalla tua area clienti.

Passo 6: creare l'account amministratore

Dal tuo computer, apri un tunnel SSH e lascia aperto questo terminale:

Terminale
ssh -N -L 8181:127.0.0.1:81 TUO_USER@IP_DEL_TUO_SERVER

Apri poi http://127.0.0.1:8181 nel browser. Il traffico passa nel tunnel cifrato.

NPM mostra una schermata Welcome! per la creazione dell'account. Compila Full Name, Email address e Password (almeno 8 caratteri, ma sceglierne una lunga e unica), poi conferma. Questo indirizzo e-mail serve anche per la registrazione presso Let's Encrypt: indicane uno valido.

I menu sono citati qui in inglese, la lingua predefinita dell'interfaccia. Puoi cambiarla dall'interfaccia.

Rafforza poi l'installazione:

  1. Apri il menu del tuo account, in alto a destra, poi Two-Factor Auth. Attiva l'autenticazione a due fattori e conserva i codici di emergenza.
  2. In Settings, apri Default Site e scegli No Response (444). Le richieste che non corrispondono a nessuno dei tuoi nomi non riceveranno più una pagina di benvenuto.

Passo 7: pubblicare un servizio

Crea un servizio di prova collegato alla rete proxy. Non pubblica alcuna porta sul server:

Terminale
sudo install -d -o "$USER" -g "$USER" /opt/whoami
nano /opt/whoami/compose.yaml
YAML
services:
  whoami:
    image: traefik/whoami:v1.12.0
    restart: unless-stopped
    networks:
      - proxy

networks:
  proxy:
    external: true
Terminale
cd /opt/whoami
docker compose up -d

In NPM, apri Hosts, poi Proxy Hosts, e fai clic su Add Proxy Host. Nella scheda Details:

Campo Valore
Domain Names app.tuo-dominio.com
Scheme http
Forward Hostname / IP whoami
Forward Port 80
Access List Publicly Accessible
Block Common Exploits Attivato

Il nome whoami è quello del servizio Compose e 80 è la sua porta nel container. Attiva Websockets Support se la tua applicazione ne ha bisogno. Collega alla rete proxy solo servizi fidati: all'interno di questa rete possono raggiungere la porta 81 di NPM.

Nella scheda SSL:

  1. In SSL Certificate, scegli Request a new Certificate.
  2. Attiva Force SSL e HTTP/2 Support.
  3. Lascia Use DNS Challenge disattivato: la validazione passa dalla porta 80.

Fai clic su Save. Attiva HSTS Enabled solo quando sei certo di mantenere questo nome in HTTPS: i browser memorizzano questa scelta.

NPM controlla ogni ora i certificati e rinnova quelli che scadono entro 30 giorni.

Verificare il risultato

Dal server o dal tuo computer:

Terminale
curl -I http://app.tuo-dominio.com
curl -I https://app.tuo-dominio.com
echo | openssl s_client -connect app.tuo-dominio.com:443 -servername app.tuo-dominio.com 2>/dev/null | openssl x509 -noout -issuer -dates

La richiesta HTTP deve restituire un reindirizzamento verso HTTPS, e la richiesta HTTPS un codice 200. L'emittente del certificato deve essere Let's Encrypt.

Dal tuo computer, la porta di amministrazione non deve rispondere:

Terminale
curl -m 5 http://IP_DEL_TUO_SERVER:81

Limitare l'accesso a un servizio

In Access Lists, fai clic su Add Access List:

  1. In Details, dai un nome alla lista. Lascia Satisfy Any disattivato per richiedere tutte le condizioni, e Pass Auth to Upstream disattivato.
  2. In Authorizations, aggiungi un nome utente e una password.
  3. In Rules, aggiungi una regola Allow con TUO_IP. NPM aggiunge un deny all finale non appena esiste una regola.

Salva, poi seleziona questa lista nel campo Access List del Proxy Host.

Accedere all'interfaccia tramite un nome di dominio

Il tunnel SSH resta la soluzione più sicura. Se preferisci un nome di dominio, metti l'interfaccia dietro NPM e limitala al tuo indirizzo IP:

  1. Crea un record A per npm.tuo-dominio.com, senza record AAAA. Una connessione in IPv6 può arrivare con l'indirizzo del gateway Docker e verrebbe rifiutata.
  2. Crea una lista di accesso che contenga solo la regola Allow TUO_IP, senza utente: l'interfaccia di NPM usa essa stessa l'header Authorization.
  3. Crea un Proxy Host npm.tuo-dominio.com in http verso 127.0.0.1, porta 81, con questa lista di accesso.
  4. In SSL, richiedi un certificato e attiva Force SSL.

Mantieni la pubblicazione 127.0.0.1:81:81: ti permette di tornare dal tunnel SSH in caso di errore. Se il tuo indirizzo IP cambia spesso, preferisci una rete privata con WireGuard o Tailscale.

Aggiornare

Leggi prima le note di rilascio. La versione 2.17.0, ad esempio, aggiorna Certbot e può compromettere alcuni plugin DNS. Esegui poi il backup di NPM, modifica il tag dell'immagine in compose.yaml, quindi esegui:

Terminale
cd /opt/npm
docker compose pull
docker compose up -d
docker compose logs --tail 50 npm

Verifica poi l'accesso all'interfaccia e ai tuoi servizi.

Backup e ripristino

Tutto si trova in /opt/npm: il file compose.yaml, data e letsencrypt. Arresta NPM per la durata dell'archivio, così da ottenere un database SQLite coerente:

Terminale
cd /opt/npm
docker compose stop
sudo tar -czf /root/npm-$(date +%F).tar.gz -C /opt npm
sudo chmod 600 /root/npm-$(date +%F).tar.gz
docker compose start

Questo archivio contiene chiavi private: copialo fuori dal server in una posizione cifrata. Se hai configurato una validazione DNS, può contenere anche le tue credenziali API.

Per ripristinare l'archivio, sostituendo AAAA-MM-GG con la sua data, crea la rete se non esiste ancora su questo server:

Terminale
cd /opt/npm 2>/dev/null && docker compose down
sudo tar -xzf /root/npm-AAAA-MM-GG.tar.gz -C /opt
docker network create proxy
cd /opt/npm
docker compose up -d

In caso di problemi

I log generali si mostrano con docker compose logs --tail 100 npm, da /opt/npm. Quelli di ogni Proxy Host si trovano in /opt/npm/data/logs/, nella forma proxy-host-1_access.log e proxy-host-1_error.log. Leggili con sudo.

port is already allocated o address already in use

Un altro servizio occupa la porta 80 o 443:

Terminale
sudo ss -ltnp | grep -E ':(80|443) '

Arresta questo servizio se non ti serve più, ad esempio con sudo systemctl disable --now nginx.

Address family not supported by protocol

Il server non ha IPv6. Aggiungi questa variabile in environment, poi riavvia con docker compose up -d:

YAML
DISABLE_IPV6: "true"

channel 2: open failed: connect failed: Connection refused

Il tunnel SSH funziona, ma nulla è in ascolto sulla porta 81. NPM si sta ancora avviando oppure si è arrestato: controlla docker compose ps e i suoi log.

502 Bad Gateway

NPM non raggiunge il servizio. Verifica che il container sia avviato, che sia collegato alla rete proxy, poi che il nome e la porta del Proxy Host siano esatti:

Terminale
docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}'

In Forward Hostname / IP, 127.0.0.1 indica il container NPM stesso, e non il server. Il servizio deve inoltre ascoltare su 0.0.0.0 nel suo container.

Il certificato non viene emesso

Dalla versione 2.17, l'interfaccia mostra il motivo fornito da Certbot:

  • NXDOMAIN: il nome non esiste ancora nel DNS.
  • Timeout during connect o Connection refused: la porta 80 non è raggiungibile da Internet. Controlla i record A e AAAA, poi il firewall della tua istanza. Se è tutto corretto, contatta il supporto dalla tua area clienti.
  • CAA record: un record CAA vieta Let's Encrypt.
  • too many certificates o too many failed authorizations: è stato raggiunto un limite di Let's Encrypt. Attendi la data indicata nel messaggio.

403 Forbidden su un servizio protetto

Il tuo indirizzo non è nella lista di accesso. Confrontalo con quello riportato nel log degli accessi del Proxy Host, poi correggi la regola.

Il login all'applicazione va in loop dopo l'aggiunta di una password

È il conflitto sull'header Authorization descritto sopra. Rimuovi gli utenti dalla lista di accesso e mantieni solo le regole basate sugli indirizzi IP.

Ciclo di reindirizzamenti

L'applicazione forza HTTPS senza riconoscere l'header X-Forwarded-Proto. Attiva l'opzione «trust proxy» o il suo equivalente nell'applicazione. Se il dominio passa dal proxy di Cloudflare, imposta la modalità SSL/TLS su Full (strict).

Riferimenti