github/Bose-SoundTouch
1
0
Fork 0
mirror of https://github.com/gesellix/Bose-SoundTouch.git synced 2026-08-18 08:36:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: document HTTPS URL derivation/override + cert-chain health warning (#355)

Browse Source 
- HTTPS-SETUP.md: the HTTPS endpoint is only needed for certain features
  and its URL now derives from the Target Domain by default; note the
  https-Target-Domain shortcut and the Settings override.
- SOUNDTOUCH-SERVICE.md: HTTPS_SERVER_URL is an override that derives from
  SERVER_URL when empty, and is viewable/overridable in Settings.
- TROUBLESHOOTING.md: new entry for the "HTTPS endpoint TLS configuration"
  health warning (wrong port / not reachable), how to fix via the Settings
  HTTPS URL, and when it's an expected reverse-proxy case.

refs #355

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tobias Gesellchen
2026-07-04 17:45:41 +02:00
co-authored by Claude Opus 4.8
parent edc6869faf
commit c153592a40
3 changed files with 34 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content/docs/guides/HTTPS-SETUP.md
+1 -1
View File
@@ -21,7 +21,7 @@ The service includes a built-in HTTPS listener (default port `8443`) that presen
- Wildcard: `*.api.bose.io`, `*.api.bosecm.com`
- Specific: `streaming.bose.com`, `bmx.bose.com`, `stats.bose.com`, `updates.bose.com`, `worldwide.bose.com`, `bose-prod.apigee.net`, `media.bose.io`, `downloads.bose.com`, `voice.api.bose.io`, and more
> **Note**: The hostname you configure as `HTTPS_SERVER_URL` (e.g. `https://soundtouch.fritz.box:8443`) is also added as a Subject Alternative Name, ensuring valid TLS for direct browser or API access.
> **Note**: The HTTPS endpoint is only needed for certain features (the DNS-based redirect, Spotify/Amazon login, and certificate trust). Its URL is added as a Subject Alternative Name, ensuring valid TLS for direct browser or API access. By default this URL is **derived from the Target Domain** (same host, `https`, on the HTTPS port), so you usually don't configure it separately. If you don't need plain HTTP at all, you can set the Target Domain itself to an `https://` URL — it is then used as the HTTPS endpoint as-is, with no separate override. Settings → **HTTPS URL** shows the effective value; set an override (`HTTPS_SERVER_URL` / `--https-server-url`, or the "advanced" field in Settings) only when a reverse proxy serves HTTPS on a different host or port.
---
docs/content/docs/guides/SOUNDTOUCH-SERVICE.md
+1 -1
View File
@@ -163,7 +163,7 @@ The service supports multiple ways to configure its behavior. When multiple sour
| `DATA_DIR` | `--data-dir` | Directory for persistent data | `./data` |
| `SERVER_URL` | `--server-url`, `-s` | External URL of this service | `http://<hostname>:8000` |
| `HTTPS_PORT` | `--https-port` | HTTPS port to bind the service to | `8443` |
| `HTTPS_SERVER_URL` | `--https-server-url`, `-S` | External HTTPS URL | `https://<hostname>:8443` |
| `HTTPS_SERVER_URL` | `--https-server-url`, `-S` | External HTTPS URL. An override: when empty it is derived from `SERVER_URL` (same host, `https`, on `HTTPS_PORT`), and can also be viewed/overridden in Settings. | derived from `SERVER_URL` |
| `PYTHON_BACKEND_URL`, `TARGET_URL` | `--target-url` | URL for Python-based service components (legacy) | `http://localhost:8001` |
| `REDACT_PROXY_LOGS` | `--redact-logs` | Redact sensitive data in proxy logs | `true` |
| `LOG_PROXY_BODY` | `--log-bodies` | Log full request/response bodies | `false` |
docs/content/docs/guides/TROUBLESHOOTING.md
+32
View File
@@ -342,6 +342,38 @@ avahi-resolve -n soundtouch.local
---
### ⚠️ Health tab: "HTTPS endpoint TLS configuration" warns about the wrong port / not reachable {#https-endpoint-tls-config}
**Symptoms:**
- The Health tab's **HTTPS endpoint TLS configuration** check shows a warning like
*"Configured HTTPS URL … uses port 443, but the service is listening on port 8443"*,
or *"Configured HTTPS endpoint … isn't reachable from inside the service."*
- You run AfterTouch on non-default ports (for example HTTP `8080`, HTTPS `8443`).
**Cause:**
AfterTouch advertises an HTTPS URL (used for the DNS-based redirect, Spotify/Amazon
login, and certificate trust) separately from the HTTP one. If that URL's port
doesn't match the port the HTTPS listener is actually bound to, the check dials the
wrong place. This most often happened when the HTTPS URL had been set without a port
(so it defaulted to `443`) while the listener was on `8443`.
**Fix:**
- Open **Settings → Service URLs**. The **HTTPS URL** line shows the effective value.
By default it now *derives* from the Target Domain (same host, on the HTTPS port),
so simply saving a correct Target Domain fixes it. Expand the ⓘ next to **HTTPS URL**
to set an **override** only if a reverse proxy serves HTTPS on a different host/port.
- Equivalent CLI/env: set `--https-server-url` / `HTTPS_SERVER_URL` to include the
right port, e.g. `https://<host>:8443`, then restart.
**Not always a problem:** if a reverse proxy intentionally terminates TLS on one port
(e.g. `443`) and forwards to AfterTouch on another (e.g. `8443`), the warning is
expected and can be ignored — the check can't see your proxy from inside the service.
---
## 🎵 **Playback Control Issues**
### ❌ "Play/Pause not working"