docs: fixup HA SSL reverse proxy instructions

Author: ukkopahis

docs/Containers/Home-Assistant.md

@@ -222,10 +222,19 @@ $ cd ~/IOTstack
 $ docker-compose up -d
 ```
 
-## Adding https access to your Home Assistant
+## HTTPS with a valid certificate
 
-Some HA integration (e.g google assistant) require your HA to be accessible
-through https. This tells you how to use a [linuxserver swag container](https://docs.linuxserver.io/general/swag) ([Docker hub docs](https://hub.docker.com/r/linuxserver/swag)) to automatically generate a SSL-certificate and setup a reverse proxy.
+Some HA integrations (e.g google assistant) require your HA API to be
+accessible via https with a valid certificate. You can configure HA to do this:
+[docs](https://www.home-assistant.io/docs/configuration/remote/) /
+[guide](https://www.home-assistant.io/docs/ecosystem/certificates/lets_encrypt/)
+or use a reverse proxy container, as described below.
+
+The linuxserver Secure Web Access Gateway container
+([swag](https://docs.linuxserver.io/general/swag)) ([Docker hub
+docs](https://hub.docker.com/r/linuxserver/swag)) will automatically generate a
+SSL-certificate, update the SSL certificate before it expires and act as a
+reverse proxy.
 
 1. First test your HA is working correctly: `http://raspberrypi.local:8123/` (assuming
 your RPi hostname is raspberrypi)
@@ -253,31 +262,77 @@ your RPi hostname is raspberrypi)
       - 443:443
     restart: unless-stopped
 ```
-5. Start the swag container (creates the file to be edited in the next step): `cd ~/IOTstack && docker-compose up -d` and check it started OK `docker-compose logs -f swag`
-6. Rename the file volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf.sample to remove .sample from the filename.
-7. Enable reverse proxy to `raspberrypi.local` and fix homeassistant container name:
+    Replace the bracketed values. Do NOT use any "-characters to enclose the values.
+
+5. Start the swag container, this creates the file to be edited in the next step:
+   ```
+   cd ~/IOTstack && docker-compose up -d
+   ```
+
+    Check it starts up OK: `docker-compose logs -f swag`. It will take a minute or two before it finally logs "Server ready".
+
+6. Enable reverse proxy for `raspberrypi.local`. `homassistant.*` is already by default. and fix homeassistant container name ("upstream_app"):
       ```
-      sed -i -e 's/server_name/server_name *.local/' \
-          -e 's/upstream_app homeassistant/upstream_app home_assistant/' \
-          volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf
+      sed -e 's/server_name/server_name *.local/' \
+          volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf.sample \
+          > volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf
       ```
-8. Add password protection:
+
+7. Forward to correct IP when target is a container running in "network_mode:
+   host" (like Home Assistant does):
+   ```
+   cat << 'EOF' | sudo tee volumes/swag/config/custom-cont-init.d/add-host.docker.internal.sh
+   #!/bin/sh
+   DOCKER_GW=$(ip route | awk 'NR==1 {print $3}')
+
+   sed -i -e "s/upstream_app .*/upstream_app ${DOCKER_GW};/" \
+       /config/nginx/proxy-confs/homeassistant.subdomain.conf
+   EOF
+   sudo chmod u+x volumes/swag/config/custom-cont-init.d/add-host.docker.internal.sh
+   ```
+   (This needs to be copy-pasted/entered as-is, ignore any "> "-prefixes printed
+   by bash)
+
+8. (optional) Add reverse proxy password protection if you don't want to rely
+   on the HA login for security, doesn't affect API-access:
     ```
-    sed -i 's/#auth_basic/auth_basic/' volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf
+    sed -i -e 's/#auth_basic/auth_basic/' \
+        volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf
     docker-compose exec -it swag htpasswd -c /config/nginx/.htpasswd anyusername
     ```
-8. Add `use_x_forwarded_for` and `trusted_proxies` to your homeassistant [http config](https://www.home-assistant.io/integrations/http). For a default install the result will be:
+9. Add `use_x_forwarded_for` and `trusted_proxies` to your homeassistant [http
+   config](https://www.home-assistant.io/integrations/http). The configuration
+   file is at `volumes/home_assistant/configuration.yaml` For a default install
+   the resulting http-section should be:
+   ```
+   http:
+      use_x_forwarded_for: true
+      trusted_proxies:
+        - 172.16.0.0/12
+        - 10.77.0.0/16
+   ```
+10. Refresh the stack: `cd ~/IOTstack && docker-compose stop && docker-compose
+    up -d` (again may take 1-3 minutes for swag to start if it recreates
+    certificates)
+11. Test homeassistant is still working correctly:
+    `http://raspberrypi.local:8123/` (assuming your RPi hostname is
+    raspberrypi)
+12. Test the reverse proxy https is working correctly:
+    `https://raspberrypi.local/` (browser will issue a warning about wrong
+    certificate domain, as the certificate is issued for you duckdns-domain, we
+    are just testing)
+
+    Or from the command line in the RPi:
     ```
-    http:
-       use_x_forwarded_for: true
-       trusted_proxies:
-         - 172.16.0.0/12
-         - 10.77.0.0/16
+    curl --resolve homeassistant.<yourdomain>.duckdns.org:443:127.0.0.1 \
+        https://homeassistant.<yourdomain>.duckdns.org/
     ```
-9. Refresh the stack: `cd ~/IOTstack && docker-compose stop && docker-compose up -d`
-10. Test homeassistant is still working correctly: `http://raspberrypi.local:8123/` (assuming your RPi hostname is raspberrypi)
-11. Test the reverse proxy is working correctly: `https://raspberrypi.local/` (note: https)
-12. And finally test your router forwards correctly by accessing it from outside your LAN(e.g. using a mobile phone): `https://homeassistant.<yourdomain>.duckdns.org/`
+    (output should end in `if (!window.latestJS) { }</script></body></html>`)
+
+13. And finally test your router forwards correctly by accessing it from
+    outside your LAN(e.g. using a mobile phone):
+    `https://homeassistant.<yourdomain>.duckdns.org/` Now the certificate
+    should work without any warnings.
 
 ## Deactivating Hass.io