Come configurare NGINX Reverse Proxy per Home Assistant

NGINX Reverse Proxy è un software che riceve le richieste HTTPS pubbliche e le inoltra al servizio Home Assistant sulla LAN. In questa guida NGINX gira su un host Linux separato da Home Assistant, termina TLS con Let’s Encrypt e inoltra anche i WebSocket. La porta 8123 non viene pubblicata direttamente.

Prerequisiti & Hardware Necessario

• Home Assistant attivo su 192.168.1.10:8123.
• Server Linux sempre acceso per NGINX, con IP riservato 192.168.1.2. NGINX, Certbot e Home Assistant sono software; il server è l’hardware che li esegue.
• Dominio o sottodominio, per esempio ha.example.it, con record DNS A/AAAA verso l’IP pubblico.
• Router con inoltro delle sole porte TCP 80 e TCP 443 verso 192.168.1.2. Non inoltrare 8123.
• Account Home Assistant con password forte e MFA attivo. Per questa guida non sono necessari prodotti commerciali o link d’acquisto.

Procedura passo-passo

1. Controlla la rete. Dal server NGINX verifica che l’origin risponda:

   curl -I http://192.168.1.10:8123

   Se il comando fallisce, correggi prima routing, firewall o indirizzo di Home Assistant.
2. Installa NGINX e Certbot. Su Debian o Ubuntu:

   sudo apt update
   sudo apt install nginx certbot python3-certbot-nginx

   Controlla il servizio con sudo systemctl enable --now nginx.
3. Configura il DNS e il router. Crea il record A per ha.example.it verso l’IP pubblico e inoltra 80/TCP e 443/TCP dal router a 192.168.1.2. Se usi IPv6, configura anche il record AAAA solo quando il server è realmente raggiungibile via IPv6.
4. Crea il virtual host HTTP. Sostituisci il dominio con il tuo:

   sudo nano /etc/nginx/sites-available/homeassistant

   server {
       listen 80;
       listen [::]:80;
       server_name ha.example.it;
   
       location / {
           proxy_pass http://192.168.1.10:8123;
           proxy_http_version 1.1;
           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_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_read_timeout 3600;
       }
   }

   Il parametro proxy_http_version 1.1 e gli header Upgrade/Connection sono necessari per il corretto passaggio dei WebSocket.
5. Abilita il sito e verifica la sintassi.

   sudo ln -s /etc/nginx/sites-available/homeassistant /etc/nginx/sites-enabled/homeassistant
   sudo rm -f /etc/nginx/sites-enabled/default
   sudo nginx -t
   sudo systemctl reload nginx

   Non eseguire il reload se nginx -t segnala errori.
6. Emetti il certificato TLS. Quando DNS e porta 80 sono raggiungibili dall’esterno, esegui:

   sudo certbot --nginx -d ha.example.it

   Seleziona il redirect automatico HTTP→HTTPS e completa l’email richiesta. Verifica il rinnovo con sudo certbot renew --dry-run.
7. Configura Home Assistant per il reverse proxy. In configuration.yaml inserisci l’IP o la subnet reale da cui NGINX arriva a Home Assistant. Se NGINX usa 192.168.1.2 direttamente:

   http:
     use_x_forwarded_for: true
     trusted_proxies:
       - 192.168.1.2

   Non inserire una subnet inventata. Se il proxy è in Docker, usa la subnet o l’IP effettivo visibile nei log di Home Assistant; per una rete, usa l’indirizzo di rete corretto, per esempio 172.20.0.0/16, non un host scritto come 172.20.0.5/16.
8. Controlla la configurazione e riavvia Home Assistant. Usa Impostazioni → Sistema → Controlli del server → Controlla configurazione. Se il controllo è valido, riavvia Home Assistant. In caso di errore “a request from a reverse proxy was received”, interrompi il test pubblico e correggi trusted_proxies.
9. Imposta gli URL di Home Assistant. In Impostazioni → Sistema → Rete imposta come URL Internet https://ha.example.it. Mantieni l’URL locale coerente con la tua rete e con l’app Companion.
10. Verifica l’esposizione. Da una rete esterna apri https://ha.example.it. Il browser deve mostrare un certificato valido, il login deve funzionare e il dashboard deve aggiornarsi. L’IP pubblico non deve rispondere direttamente sulla porta 8123.

Verifica del funzionamento

1. Esegui sudo nginx -t e verifica il certificato con curl -I https://ha.example.it.
2. Controlla sudo journalctl -u nginx -n 50 --no-pager e i log di Home Assistant per richieste rifiutate dal proxy.
3. Apri una dashboard con entità live, automazioni e cronologia: se i WebSocket funzionano, gli aggiornamenti arrivano senza ricaricare la pagina.
4. Verifica il rinnovo automatico con sudo certbot renew --dry-run.
5. Da una scansione esterna autorizzata controlla che siano esposte solo 80/TCP e 443/TCP, non 8123/TCP.

Problemi comuni

FAQ essenziali

Devo configurare SSL anche in Home Assistant?

No, se TLS termina su NGINX. Home Assistant può restare in HTTP sulla LAN; il collegamento esterno deve usare HTTPS e il proxy deve essere attendibile.

Posso usare NGINX senza dominio?

Per HTTPS pubblico e certificato Let’s Encrypt serve un nome DNS valido. Un IP può essere usato per test locali, ma non sostituisce una configurazione TLS pubblica affidabile.