From 03db59b6fc472b52a08d147628c0363d4854aaee Mon Sep 17 00:00:00 2001
From: ukkopahis <95980324+ukkopahis@users.noreply.github.com>
Date: Thu, 20 Jan 2022 03:23:30 +0200
Subject: [PATCH] homeassistant: add docs for https reverse proxy setup

---
 docs/Containers/Home-Assistant.md | 59 +++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/docs/Containers/Home-Assistant.md b/docs/Containers/Home-Assistant.md
index 8e886674b..b9d116231 100644
--- a/docs/Containers/Home-Assistant.md
+++ b/docs/Containers/Home-Assistant.md
@@ -222,6 +222,65 @@ $ cd ~/IOTstack
 $ docker-compose up -d
 ```
 
+## Adding https access to your Home Assistant
+
+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.
+
+1. First test your HA is working correctly: `http://raspberrypi.local:8123/` (assuming
+your RPi hostname is raspberrypi)
+2. Make sure you have duckdns working.
+3. On your internet router, forward public port 443 to the RPi port 443
+4. Add swag to ~/IOTstack/docker-compose.yml beneath the `services:`-line:
+```
+  swag:
+    image: ghcr.io/linuxserver/swag
+    cap_add:
+      - NET_ADMIN
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=Etc/UTC
+      - URL=<yourdomain>.duckdns.org
+      - SUBDOMAINS=wildcard
+      - VALIDATION=duckdns
+      - DUCKDNSTOKEN=<token>
+      - CERTPROVIDER=zerossl
+      - EMAIL=<e-mail> # required when using zerossl
+    volumes:
+      - ./volumes/swag/config:/config
+    ports:
+      - 443:443
+    restart: unless-stopped
+    networks:
+      - iotstack_nw
+```
+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:
+      ```
+      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
+      ```
+8. Add password protection:
+    ```
+    sed -i '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:
+    ```
+    http:
+       use_x_forwarded_for: true
+       trusted_proxies:
+         - 172.16.0.0/12
+         - 10.77.0.0/16
+    ```
+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/`
+
 ## <a name="deactivateHassio"> Deactivating Hass.io </a>
 
 Because Hass.io is independent of IOTstack, you can't deactivate it with any of the commands you normally use for IOTstack.