access your Home Assistant remotely using DuckDNS, Letsencrypt and the nginx SSL proxy

---

Home Assistant is more useful if you can access this ‘home automation hub’ away from home. You can then control Home Assistant remotely with a browser or an excellent mobile phone app. A bit, actually a lot, of magic achieves this if you want to do it for free. Additionally the app can access sensors in your phone for useful information – such as its battery’s behaviour and where you are.

Important: if you want to do more than access Home Assistant securely from outside the home, such as access other devices such as a NAS or Synology or a server on your home network you need a different workflow to achieve that. Leave this page now and see my page using nginx proxy manager with home assistant. However you also want to enable local https:// on your local services – see access your IP services with local HTTPS or remote https

A remote access ‘feature’ is so important that it’s worth having other methods in case of failure (eg of a certificate renewal). These methods use Wireguard or Tailscale to let your phone browse to any of your home internal IP addresses as if you were at your desk. I explain how to set up Wireguard on Home Assistant here. I’m reliably using both of them.

If you want to access Home Assistant securely from outside your home you need to do the following:

• Create an account and a subdomain at DuckDNS
• Set up the DuckDNS add-on in Home Assistant
• Edit configuration.yaml
• Forward port 443 in your router.
• Set up the nginx SSL proxy add-on in Home Assistant
• Access your Home Assistant remotely and securely using your DuckDNS subdomain without a port number.
• But if you want to access cameras, servers as well as Home Assistant see this guide instead

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 an easily remembered subdomain and get the token (= long password) from your DuckDNS page.

Your home IP address changes – eg when you reboot the router. If you now install the Home Assistant DuckDNS add-on, DuckDNS will keep track of your current home IP address. Go to Home Assistant > Settings > Add-on Store > Install Duck DNS. Then, on the Duck DNS Configuration tab fill in the information shown below:

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

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

open up ports for nginx in your router

Find your home router admin page and find the port forwarding section. Forward the public inward TCP port 443 to your internal private port 443 to your Home Assistant IP address. Do not forward public tcp ports 80 or 81 to any computer.

edit your configuration.yaml to permit nginx

The Home Assistant docs suggest editing configuration.yaml as follows. The commented out lines can be deleted entirely. Go to the Server controls page in Home Assistant Configuration. If the configuration check here is good, restart Home Assistant.

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

use nginx SSL proxy to get your domain connected

Go to Home Assistant > Add-on Store > Install NGINX Home Assistant SSL proxy. (You don’t need to install the Letsencrypt add-on. Do not install the similar sounding nginx Proxy Manager for this). Type your DuckDNS subdomain for the domain entry. All else can be left as is. Start the nginx add-on. Wait some minutes after you start the add-on. Read the Log tab nearby and hope for only happy messages there.

start using your subdomain to access 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 and doing some obfuscating). Here is what to do if it works first time, or if it doesn’t

• Home Assistant login page: yay it works! Go to the mobile app settings > App configuration and enter the external Home Assistant URL as https://YOUR-SUBDOMAIN.duckdns.org. If you also enter your Home Network wifi SSID, the app will know when you are away from home and will switch from using the internal URL to use the external DuckDNS subdomain.
• If an error appears, go to the nginx SSL proxy add-on logs and look for clues. Go to the Server controls page in Home Assistant Configuration. If the configuration check here is good restart Home Assistant and wait a few minutes or till the nginx proxy logs show that it’s all OK.
• You may see a Blank page with Bad request. Likely nginx has blocked access. Other things being equal the http: section in configuration.yaml might be different to the one suggested above. Reminder: do not run the Home Assistant nginx proxy manager add-on – that’s for a different wider purpose (described here).
• 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 setup steps 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 also needs to run to refresh your certificates and your IP address. If it fails, your certificate or broadband IP address will go out of date and nginx will fail too.