use nginx proxy manager with home assistant to access many network devices

If you need to access Home Assistant remotely away from home, skip this page and instead go to access your Home Assistant remotely using DuckDNS, Letsencrypt and the nginx SSL proxy.

This page is for those who want to access Home Assistant from outside the home, and also want to access other devices, a router, a camera or a server on your home network. If that’s you, you need* to install the Home Assistant add-on called nginx Proxy Manager and not install a similar sounding add-on called ‘nginx Home Assistant SSL proxy‘. The procedure to set this up via nginx is tricky but follow along to learn how it’s done.

As of 2023 Home Assistant started exposing the names and photos of all the family members you may have added as Home Assistant logins. It’s a trivial, eye-candy feature and worth turning off. My setup below appears to work safely (it appears to detect external logins not expose those names and ‘capture the header of the incoming request). If you’re concerned use Tailscale. See here for what I did to setup Tailscale*.

*BTW there are alternative ways to make access to your home network secure – one method uses the Wireguard add-on to connect your phone to the network then lets you browse your Home Assistant internal IP, router, IP camera, printer, NAS drive as if you were at your desk. The process of setting up Wireguard in Home Assistant is here. Another method I favour uses the Tailscale add-on.

the nginx proxy manager setup can be summarised:

• Create an account and up to 5 subdomains at DuckDNS
• Set up the DuckDNS add-on in Home Assistant
• Temporarily edit configuration.yaml
• Set up the nginx proxy manager add-on in Home Assistant
• Forward some ports in your router.
• Set up the subdomains in nginx proxy manager
• Request certificates via nginx proxy manager
• Re-edit configuration.yaml and restart Home Assistant
• Access your Home Assistant securely using your DuckDNS subdomain without a port number.

connect Home Assistant to a subdomain at duckdns.org

When you’re away from home, the first problem to solve is to be able to find your home network. You can do that by firstly having an easy to remember network name (e.g myhome.duckdns.org). Create an account at duckdns.org, choose a subdomain and get the token (or long password) from your DuckDNS page.

The second problem to solve is that your home IP address can change. If it changes, thankfully the Home Assistant DuckDNS add-on will tell DuckDNS your latest home IP address. Go to Home Assistant > Supervisor > Add-on Store > Install Duck DNS. Then, on the Duck DNS Configuration tab fill in the information shown in bold just below:

When the DuckDNS add-on is running, you’ll be able to use your phone to access your home network from anywhere. However, there’s still more to do if you want this to happen securely.

lets_encrypt:
  accept_terms: true
  certfile: fullchain.pem
  keyfile: privkey.pem
token: 8730bbcf-YOUR-TOKEN-FROM-DUCKDNS
domains:
  - YOUR-SUBDOMAIN.duckdns.org
  - YOUR-OTHER-SUBDOMAIN.duckdns.org
aliases: []
seconds: 3000

As you also want to connect to other devices on your home network I suggest that you create additional DuckDNS subdomains now.

use nginx proxy manager to get your domain connected

Go to Home Assistant > Supervisor > Add-on Store > Install nginx Proxy Manager. Then, on the nginx Proxy Manager Configuration tab fill in the information as shown below.

Wait some minutes after you start the nginx add-on. Read the Log tab nearby and hope for only happy messages there. Ideally you want the host entrance port above to be 80 not 8888. You’re welcome to try this – when I try this I get a message saying that port 80 was already in use, hence I changed it to the alt http port 8888.

open up ports for nginx in your router

Go to your home router admin page and find the port forwarding section. Forward the public inward ports to your internal private ports as follows:

• forward public tcp port 443 to private port 443 on the IP address of your Home Assistant computer
• forward public tcp port 8888 to private port 80 on the IP address of your Home Assistant computer
• do not forward public tcp ports 80 or 81 to any other computer.

temporarily edit your configuration.yaml to set up nginx

The Home Assistant docs suggest adding some lines to configuration.yaml. However I had more success setting up nginx when I commented out (#) the entire http block:

# http:
   # ssl_certificate: /ssl/fullchain.pem
   # ssl_key: /ssl/privkey.pem
  # use_x_forwarded_for: true
  # trusted_proxies:
  #   - 10.0.0.200
  #   - 172.30.33.0/24

set up the host redirect on nginx proxy manager

Go to the nginx proxy manager add-on page and click Open Web UI of nginx proxy manager. There should be a sign-in page there that lets you log in with admin@example.com and password changeme. When you’re signed in create a login with your own name, email address and password.

Go to the Hosts tab of nginx proxy manager. Create a new Proxy host. Enter your DuckDNS host name eg YOUR-SUBDOMAIN.duckdns.org. Turn on Websocket support. Add the internal IP address for your Home Assistant device and the port of 8123. Click Save:

Go back to the Hosts tab of nginx proxy manager. Find your DuckDNS host name eg YOUR-SUBDOMAIN.duckdns.org click the three dots to Edit this entry. Click SSL tab. Check Force SSL. Click the drop-down to Request a new SSL certificate. Agree terms and enter your DuckDNS login email address. Click Save and wait a minute for this to complete.

With luck you’ll see that a certificate was granted (by the invisible Letsencrypt). You may see Internal Error or other message in which case try again and check the steps above (which differ from the official procedure).

If you also want to connect to other devices on your home network repeat the above for those devices. In other words, create proxies for your other DuckDNS subdomains and enter the forwarding IP addresses and ports. eg 192.168.1.25:5000 might access a Synology box.

edit your configuration.yaml to get the benefit of nginx

We’re almost done. Use File Editor to change your configuration.yaml as below. It permits Home Assistant to allow access by nginx proxy (as in use_x_forwarded_for: true). The trusted proxies IP addresses are internal addresses and you may add your own to this list. The two certificate lines make my Home Assistant inaccessible so I’ve removed them by adding #. Your configuration.yaml can now read exactly as follows.

http:
# ssl_certificate: /ssl/fullchain.pem
# ssl_key: /ssl/privkey.pem
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.0.0.200
    - 172.30.33.0/24

Go to the Server controls page in Home Assistant Configuration. If the configuration check here is good restart Home Assistant. To simulate connecting to your Home Assistant remotely, disconnect your phone from your home wifi and use a browser to try out YOUR-SUBDOMAIN.duckdns.org in the browser. You don’t need to add the port number to the URL because nginx is doing that for you (indeed, it’s acting as a proxy):

• If you see the Home Assistant login page: yay it works!
• If an error appears, go to the nginx proxy manager add-on logs and look for clues.
• You may see a Blank page with Bad request. Likely nginx has blocked access. Other things being equal the http: section above might be absent.
• Do not be running the other Home Assistant nginx proxy add-on.
• You may see a Home Assistant page with retry: first check that you can access Home Assistant using the normal internal address eg 192.168.1.42:8123. Check that you are accessing Home Assistant remotely and not over your wifi (although it may not matter). Check all the steps above after you’ve cleared the cache of your browser or tried another browser. Edit the URL to try access with http:// or https:// and without the port number.
• Remember that the DuckDNS add-on needs to run to refresh your certificates and your IP address. If that fails your certificate or broadband IP address will go out of date.

use nginx proxy manager to protect and allow access to other devices on your network

The point of the above tricky process was that, as well as Home Assistant, you want to access other devices such as a Synology box or a server on your home network. Suppose your other device was Synology on port 5000 with an internal address 192.168.1.20:5000. Do the following:

1. Go to DuckDNS and create a subdomain such as mysynology.duckdns.org
2. Go to the DuckDNS add-on and add mysynology.duckdns.org to its configuration. The add-on should restart.
3. Optional (but required on my system): use Home Assistant File Editor to comment out the http: section of configuration.yaml. In Server Controls check the configuration and restart Home Assistant.
4. Optional – check that the router has the open ports as earlier. (You may have changed the ports since you set up the initial Home Assistant proxy.)
5. Go to the nginx proxy manager add-on. Open web UI and login again (your previously entered login should be used). Set up a new proxy for that subdomain – enter the forwarding IP address 192.168.1.20 and the port 5000 as used by the Synology box and Save it.
6. Edit the proxy and use the SSL tab to Request a new certificate. Enter your email and Agree to terms. Force SSL and click Save.
7. If you get an Internal Error rather than a Letsencrypt certificate then you may well need the optional steps 3, 4 and 8 to make progress.
8. Optional (but required on my system): use Home Assistant File Editor to restore the http: section of configuration.yaml. In Server Controls check the configuration and restart Home Assistant.
9. Use a browser to access your Synology from outside your network with mysynology.duckdns.org

close the unnecessary ports in your router

Go to your home router admin and find the port forwarding / virtual servers section. You can check the ports as follows:

• forward public tcp port 443 to private port 443 on the IP address of your Home Assistant computer
• forward public tcp port 8888 to private port 80 on the IP address of your Home Assistant computer.
• don’t forward public tcp ports 80 or 81 to any computer.