fix: allow EOSdash through an external reverse proxy (#1355)

Support externally proxied EOSdash (#1320)

* test: verify optional dashboard port stays unpublished

* docs: describe optional proxy access and public URL

docs/_generated/configexample.md

@@ -392,6 +392,7 @@
            "startup_eosdash": true,
            "eosdash_host": "127.0.0.1",
            "eosdash_port": 8504,
+           "eosdash_public_url": "https://energy.example.com/dashboard",
            "eosdash_supervise_interval_sec": 10,
            "run_as_user": null,
            "reload": true

docs/_generated/configserver.md

@@ -9,6 +9,7 @@
 | ---- | -------------------- | ---- | --------- | ------- | ----------- |
 | eosdash_host | `EOS_SERVER__EOSDASH_HOST` | `str` | `rw` | `127.0.0.1` | EOSdash server IP address. Defaults to EOS server IP address. |
 | eosdash_port | `EOS_SERVER__EOSDASH_PORT` | `int` | `rw` | `8504` | EOSdash server IP port number. Defaults to 8504. |
+| eosdash_public_url | `EOS_SERVER__EOSDASH_PUBLIC_URL` | `Optional[str]` | `rw` | `None` | Public EOSdash base URL for redirects and error-page links, including an optional proxy path prefix. Set this for reverse proxies or mapped ports; it does not change the bind address. Without it, direct access uses the request host and EOSdash port. Raw forwarded headers are not used. |
 | eosdash_supervise_interval_sec | `EOS_SERVER__EOSDASH_SUPERVISE_INTERVAL_SEC` | `int` | `rw` | `10` | Supervision interval for EOS server to supervise EOSdash [seconds]. |
 | host | `EOS_SERVER__HOST` | `str` | `rw` | `127.0.0.1` | EOS server IP address. Defaults to 127.0.0.1. |
 | port | `EOS_SERVER__PORT` | `int` | `rw` | `8503` | EOS server IP port number. Defaults to 8503. |
@@ -33,6 +34,7 @@
            "startup_eosdash": true,
            "eosdash_host": "127.0.0.1",
            "eosdash_port": 8504,
+           "eosdash_public_url": "https://energy.example.com/dashboard",
            "eosdash_supervise_interval_sec": 10,
            "run_as_user": null,
            "reload": true

docs/akkudoktoreos/serverapi.md

@@ -8,3 +8,24 @@
 :relative-docs: ..
 :relative-images:
 ```
+
+## Dashboard redirects behind a reverse proxy
+
+For direct access, EOS redirects to the request host with the configured
+`server.eosdash_port`. IPv4, hostnames and bracketed IPv6 addresses are supported.
+
+If a reverse proxy exposes EOSdash through HTTPS, another public port or a path
+prefix, set `server.eosdash_public_url` to the externally reachable dashboard base
+URL, for example `https://energy.example.com` or
+`https://energy.example.com:9443/dashboard`. EOS preserves this scheme, port and
+prefix for redirects and the dashboard link on error pages. Configure the proxy
+to route that base URL to EOSdash; this setting does not configure the proxy or
+change the dashboard's bind address.
+
+The base URL must not include credentials, a query or a fragment. A request for
+`/eosdash/health` with the second example redirects to
+`https://energy.example.com:9443/dashboard/eosdash/health`. Raw
+`X-Forwarded-Host` and `X-Forwarded-Proto` headers do not override the configured
+URL. Without an explicit public URL, scheme handling follows the ASGI server's
+trusted-proxy configuration; EOS cannot infer an external dashboard route from
+forwarding headers.

docs/develop/install.md

@@ -337,6 +337,25 @@ In the dashboard, go to:
 Config
 ```
 
+### 6) Access EOSdash through an external reverse proxy (M5)
+
+Home Assistant Ingress needs no further setup. An external reverse proxy needs two
+settings, because EOSdash runs on its own port:
+
+1. Map the optional add-on port `8504` in:
+
+   ```bash
+   Settings → Add-ons → Akkudoktor-EOS → Configuration → Network
+   ```
+
+   The port is unpublished by default. Route the proxy to it and set
+   `server.eosdash_host` to `0.0.0.0`, so EOSdash accepts connections from the proxy.
+
+2. Set `server.eosdash_public_url` to the address the browser uses, for example
+   `https://eos.example.com:8504`. EOS redirects to that address instead of guessing one
+   from the request. Without it, EOS only redirects to hosts it knows, such as
+   `localhost` or its own IP address, and answers with an error page otherwise.
+
 ## Helpful Docker Commands
 
 ### View logs