NGINX on OPNsense for Home Assistant

I’ve been experimenting with Home Assistant (HA) for some temperature monitoring around the house. It has a great mobile client that’ll work across the public internet, but HA itself unfortunately it only does HTTP by default. It has some minor built in support for HTTPS by using the NGINX proxy and Let’s Encrypt (LE) Add-ons, but for a couple of reasons[1] I didn’t like this solution. I’m not about to expose something with credentials across the public internet via plain HTTP, so I wanted to do this proxying on my firewall instead of on the device itself.

My firewall at home runs OPNsense which has an NGINX Plugin, along with a full featured ACME client that I’m already using for other certificates, so it was perfect for doing this forwarding. After a bit of frustration, fooling around, and unexpected errors I got things working, so I wanted to share a simple summary of what it took to make it work. I’m leaving the DNS, certificate, and firewall sides of this out, as they’ll vary and are well documented elsewhere.

Here’s the steps I used:

• Set up DNS so the hostname you wish to use is accessible internally and externally. In this example homeass.site.nuxx.net will resolve to 24.25.26.13 on the public internet, and 192.168.2.1 at home, which are the WAN and LAN interfaces on the OPNsense box.
• Set up the ACME plugin to get a certificate for the hostname you will be using for, in this case homeass.site.nuxx.net.
• On your Home Assistant instance, add the following to the configuration.yaml. This tells HA to accept proxied connections from the gateway. If you don’t do this, or specify the wrong trusted_proxy, you will receive a 400: Bad Request error when trying to access the site via the proxy:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.2.1/32

• In OPNsense, install NGINX.
• In Configuration → Upstream → Upstream Server define your HA instance as a server:
  • Description: HA Server
  • Server: 192.168.2.23 (your Home Assistant device)
  • Port: 8123 (the port you have Home Assistant running on, 8123 is the default)
  • Server Priority: 1
• In Configuration → Upstream → Upstream define a grouping of upstream servers, in this case the one you defined in the previous step:
  • Description: Home Assistant
  • Server Entries: HA Server
• In Configuration → HTTP(S) → Location define what will get redirected to the Upstream:
  • Toggle Advanced Mode
  • Description: Home Assistant
  • URL Pattern: /
  • Upstream Servers: Home Assistant
  • Advanced Proxy Options → WebSocket Support: ✓
• In Configuration → HTTP(S) → HTTP Server define the actual server to listen for HTTP connections:
  • HTTP Listen Address: Clear this out unless you want to proxy HTTP for some reason.
  • HTTPS Listen Address: 8123 and [::]:8123. Leave out the latter if you don’t wish to respond on IPv6.
  • Default Server: ✓
  • Server Name: homeass.site.nuxx.net
  • Locations: Home Assistant
  • TLS Certificate: Pick the certificate that you created early on with the ACME plugin.
  • HTTPS Only: ✓ (Unless for some reason you wish to support cleartext HTTP.)
• Then under General Settings check Enable nginx and click Apply.
• Finally, if needed, be sure to create the firewall rule(s) needed to allow traffic to connect to the TCP port you designated in the HTTP Server portion of the NGINX configuration.

[1] Reasons for doing the proxying on the firewall include:

• The Let’s Encrypt Add-on won’t restart NGINX automatically on cert renewal as OPNsense can. This means I’d have to either write something to do it, or manually restart the add-on to avoid periodic certificate errors.
• If NGINX is running on the same device as Home Assistant, then it needs to be on a different port. I prefer using the default port.
• I’d prefer to run just one copy of NGINX on my network for reverse proxying.
• While experimenting with NGINX and LE on HA I kept running into weird problems where something would start logging errors or just not work until I restarted the box. With everything running as containers, troubleshooting intermittent issues like these is painful enough that I preferred to avoid it.